# Caib Registry API — LLM / agent orientation

You are on **`registry.caib.io`** or a **`caib.<apex>`** bridge (e.g. **`caib.caib.io`**): the **public read API** for Caib’s Registry — a **typed JSON catalogue**. **Parameters, enums, and models:** **`GET /openapi.json`** on this host.

**Stability:** The product is under active development; **`openapi.json`** is kept as **stable as practical**.

## Canonical entry points

| Use | URL |
|-----|-----|
| List / search | `GET /v1/entities` |
| Single entity | `GET /v1/entities/{id}` |
| **Contract** | https://registry.caib.io/openapi.json |
| DNS / CNAME instructions | `GET /v1/public/dns-instructions` |
| Health | `GET /health` |

## `GET /v1/entities` — query parameters (summary)

Full list and validation: **`openapi.json`**. Typical filters:

| Param | Meaning |
|-------|---------|
| **`domain`** | `tenant_domain`. On **`caib.<apex>`**, omitting **`domain`** defaults to that apex. |
| **`type`** | One designator: **SKU, SOU, JCU, NCU, ETU, HRU, BIO, BAM, MAR, CRU, AIQ** — **omit** for all types in scope. |
| **`caib_domain`** | Filter **`caib_domain_value`**. |
| **`q`**, **`limit`**, **`offset`** | Search and pagination — bounds in OpenAPI. |

## Unit types (`type=`)

**Payload** shapes and semantics: **models in `openapi.json`**. Codes: **SKU, SOU, JCU, NCU, ETU, HRU, BIO, BAM, MAR, CRU, AIQ**.

## Caib.org bridge example

`GET https://caib.caib.io/v1/entities?domain=caib.io`

## Good habits

- Use **`openapi.json`** as the single machine-readable spec.  
- Paginate; respect **429** / **`Retry-After`**.  
- **`verify.caib.io`** is UI; **`GET /v1/entities/{id}`** is truth.

## Broader context

- https://caib.io/llms.txt