> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runflow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API catalog

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

[RFC 9727](https://datatracker.ietf.org/doc/rfc9727/) 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

```json theme={"dark"}
{
  "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`](https://api.runflow.io/v1/health) (thin) and [`/v1/readiness`](https://api.runflow.io/v1/readiness) (per-component checks) are reachable. |

## Use it

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

```python theme={"dark"}
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

<CardGroup cols={2}>
  <Card title="OpenAPI" icon="code" href="/agents/openapi">The spec the catalog points at.</Card>
  <Card title="Skill" icon="sparkles" href="/agents/skills">Higher-level agent integration.</Card>
</CardGroup>