API catalog

RFC 9727 linkset that points at every machine-readable Runflow surface.

RFC 9727 defines an “API catalog” linkset: one URL that lists every machine-readable surface of an API. Runflow’s lives at:

https://www.runflow.io/.well-known/api-catalog

Payload

{
  "linkset": [
    {
      "anchor": "https://api.runflow.io/",
      "service-desc": [
        { "href": "https://docs.runflow.io/api/openapi.public.json", "type": "application/json" }
      ],
      "service-doc": [
        { "href": "https://docs.runflow.io/api-reference/models/search-models", "type": "text/html" },
        { "href": "https://docs.runflow.io/", "type": "text/html" }
      ],
      "status": [
        { "href": "https://api.runflow.io/v1/health", "type": "application/json" }
      ]
    }
  ]
}

Relations

Rel	What it points to
service-desc	Machine-readable public spec (OpenAPI).
service-doc	Human-readable API reference and docs.
status	Health/status endpoint. Both /v1/health (thin) and /v1/readiness (per-component checks) are reachable.

Use it

Discovery agents use the catalog to learn the spec URL without scraping. Code:

import requests
from requests.exceptions import RequestException

TIMEOUT = 5

try:
    r = requests.get("https://www.runflow.io/.well-known/api-catalog", timeout=TIMEOUT)
    r.raise_for_status()
    catalog = r.json()
    spec_url = catalog["linkset"][0]["service-desc"][0]["href"]

    r = requests.get(spec_url, timeout=TIMEOUT)
    r.raise_for_status()
    spec = r.json()
except RequestException as exc:
    raise SystemExit(f"Could not load Runflow API catalog: {exc}")

Related

OpenAPI

The spec the catalog points at.

Skill

Higher-level agent integration.