Public API & agent discovery

Start from the headers

Every public page answers with a Link header (RFC 8288). One request to the homepage is enough to find the rest — no HTML parsing required.

$ curl -sI https://albamed.org/

Link: <https://albamed.org/.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json",
      <https://albamed.org/api/openapi.json>; rel="service-desc"; type="application/vnd.oai.openapi+json;version=3.1.0",
      <https://albamed.org/docs/api>; rel="service-doc"; type="text/html",
      <https://albamed.org/site.jsonld>; rel="describedby"; type="application/ld+json",
      <https://albamed.org/terms>; rel="terms-of-service"; type="text/html",
      <https://albamed.org/privacy>; rel="privacy-policy"; type="text/html"

Discovery documents

Each relation points at a document that is public, CORS-open and cacheable.

Relation	Target	Media type	What it is
`api-catalog`	`/.well-known/api-catalog`	`application/linkset+json`	RFC 9727 catalog: one entry per public API, each linking to its description, documentation and terms.
`service-desc`	`/api/openapi.json`	`application/vnd.oai.openapi+json;version=3.1.0`	OpenAPI 3.1 description of every endpoint below, with schemas and examples.
`service-doc`	`/docs/api`	`text/html`	This page.
`describedby`	`/site.jsonld`	`application/ld+json`	schema.org graph of the organization, its services and the FAQ — the same graph the homepage embeds inline.
`terms-of-service`	`/terms`	`text/html`	Terms of Service. Machine-readable at `/api/legal/terms`.
`privacy-policy`	`/privacy`	`text/html`	Privacy Policy. Machine-readable at `/api/legal/privacy`.

Authentication. /auth.md (also at /.well-known/auth.md) answers the question in the conventional place: there is nothing to register for and no credentials to present. It also says why no OAuth or OIDC discovery document is published here.

Resource manifest. /.well-known/ai-catalog.json (also at /.well-known/ard.json) is the Agentic Resource Discovery manifest: every machine-readable resource on this domain, each with its media type and the questions it can answer.

Agent skills. /.well-known/agent-skills/index.json (Agent Skills Discovery v0.2.0) lists the procedures an agent can run against this site — API discovery, reading the legal documents, and sending a contact request — each as a SKILL.md with its sha256 digest.

Agent index. /.well-known/agents.json is the organizational index a DNS-AID record points at. AlbaMed publishes no agent-to-agent or MCP endpoint, so its agents array is empty on purpose; the index hands you the links above instead.

The homepage and the legal pages add canonical and alternate (hreflang="en" / hreflang="es") so an agent can pick the right language. A crawler is also welcome at /robots.txt and /sitemap.xml.

Pages as markdown

Every public HTML page answers in markdown when you ask for it. Same URL, same content, one representation each — so the response carries Vary: Accept and a shared cache keeps the two apart.

$ curl -s -H 'Accept: text/markdown' https://albamed.org/

content-type: text/markdown; charset=utf-8
vary: Accept, Accept-Encoding
x-markdown-tokens: 5528
x-original-tokens: 61748

---
title: "AlbaMed — Practice management for behavioral health"
description: "One platform. Every provider, enrolled…"
url: "https://albamed.org/"
lang: "en"
---

# Clinical, billing and compliance for behavioral health.
…

What you get	YAML frontmatter from the page's own metadata, the body without navigation, chrome or decoration, and the JSON-LD graph preserved in a fenced `json` block at the end.
Language	Add `?lang=es` for the Spanish page; the frontmatter reports which one you got.
Token counts	`x-markdown-tokens` and `x-original-tokens` are estimates (~4 characters per token), not the output of a particular tokenizer.
Browsers	Unaffected: an `Accept` that does not mention `text/markdown`, or ranks HTML above it, keeps getting HTML.

Endpoints

Base URL https://albamed.org. No API key, no token, no rate limit beyond ordinary abuse protection. Responses are JSON and UTF-8.

get /api/branding Shared brand and social metadata

Public brand values every AlbaMed system reads: site name, logo, social preview image and the marketing title/description. Same payload as the CDN copy at platform/branding.json; this endpoint is the fallback source.

Request

curl -s https://albamed.org/api/branding

Response 200

{
  "site_name": "AlbaMed",
  "og_title": "AlbaMed \u2014 Healthcare operations, billing and compliance",
  "og_description": "Billing, clinical documentation and audit for Florida behavioral health.",
  "og_image_url": "https://albamed.org/assets/og-image.png",
  "og_image_width": 1200,
  "og_image_height": 630,
  "og_image_alt": "AlbaMed",
  "logo_url": "https://albamed.org/assets/logo.png",
  "logo_alt": "AlbaMed",
  "source": "https://albamed.org"
}

get /api/legal/{kind} Published Privacy Policy or Terms of Service as JSON

The currently published version of a legal document, section by section, with the rendered HTML, the plain-language summary of each section, the version number and the effective date. Returns 404 while no version is published for that language.

Parameters

Name	In	Required	Values	Description
`kind`	path	yes	`privacy` · `terms`	Document to read.
`lang`	query	no	`en` · `es`	Language of the published text.

Request

curl -s https://albamed.org/api/legal/privacy?lang=en

Response 200

{
  "ok": true,
  "doc_type": "privacy",
  "lang": "en",
  "version": "1.0",
  "title": "Privacy Policy",
  "effective_at": "2026-09-09T00:00:00",
  "sections": [
    {
      "anchor": "s1",
      "number": "1",
      "title": "Who we are",
      "summary": "Who runs this site and how to reach us.",
      "summary_kind": "plain",
      "html": "<p>\u2026</p>"
    }
  ]
}

post /contact Send a contact request

Stores a lead and notifies the team. Cross-site protected: read the token from the <meta name="csrf-token"> tag on the homepage and send it back in the X-CSRFToken header, with the session cookie from that same request. `name` and `email` are always required, plus at least one of `interests` or `message`. Returns 422 with the offending field name when validation fails.

Request body (JSON)

Field	Type	Required	Description
`name`	`string`	yes
`email`	`string`	yes
`phone`	`string`	no
`organization`	`string`	no
`interests`	`object`	no	Which services you are asking about: service key → list of labels. Unknown keys are dropped.
`message`	`string`	no

Request

curl -X POST https://albamed.org/contact \
  -H 'Content-Type: application/json' \
  -H 'X-CSRFToken: <token from the homepage>' \
  -b cookies.txt \
  -d '{"name": "\u2026", "email": "\u2026"}'

Response 200 · 422 on validation error

{
  "ok": true,
  "id": 42,
  "emailed": true
}

get /healthz Liveness probe

Returns 200 while the application is serving. No authentication, no side effects.

Request

curl -s https://albamed.org/healthz

Response 200

{
  "ok": true
}

Conventions

Authentication	None. Every endpoint on this page is public and read-only, except `POST /contact`. There is nothing to obtain a token for: this domain is not an OAuth authorization server, publishes no `/.well-known/openid-configuration`, and issues no tokens. Staff sign-in uses Google as the OpenID provider; that flow is not part of this API.
CORS	The discovery documents and `/api/branding` answer with `Access-Control-Allow-Origin: *`. `Link` is listed in `Access-Control-Expose-Headers`, so a browser client can read it cross-origin.
Caching	`Cache-Control: public, max-age=300` on the data endpoints, `3600` on the catalog and the OpenAPI document. Cache them; they change rarely.
Errors	JSON with `ok: false`. `404` when nothing is published, `422` with the offending `field` on invalid input.
Versioning	The OpenAPI document carries the site version in `info.version`. Fields are added, never silently repurposed.
Content signals	`/robots.txt` declares `search=yes, ai-input=yes, ai-train=no` (contentsignals.org): index us, read a page to answer a question about us, but do not train models on this content.
Contact	Questions about this API: the contact form.

What is not here

This is the public marketing site. Nothing on this API touches patient data: no protected health information, no claims, no clinical notes and no tenant records are reachable from these endpoints. The AlbaMed systems that hold that data — billing, clinical and audit — sit behind authentication and are not described here.