# Catalog and status

Reference for the public discovery endpoints (GET /v1/apis, /v1/apis/{sku}, /v1/catalog, /v1/categories, /v1/platforms, /openapi.json) and the status endpoints (GET /v1/status, /v1/status/apis). No key needed.

Everything on this page is public: no key, no account. Agents can browse the whole catalog before they have credentials.

Catalog responses are cacheable: they carry `Cache-Control: public, max-age=60, stale-while-revalidate=300` and a weak `ETag`; send `If-None-Match` to get a `304 Not Modified` when nothing changed.

## GET /v1/apis

`GET https://api.primaryapi.com/v1/apis`

Auth: None

Searches and lists API summaries.

| Parameter | Type | Description |
|---|---|---|
| `q` | string | Keywords or a use case, matched against SKU, title, summary, platform and tags. |
| `category` | string | One of `social`, `search-seo`, `enrichment`, `knowledge-data`, `video`, `ecommerce`, `travel`, `finance-crypto`, `validation`, `compliance`, `intelligence`, `audio`, `web`, `ai-search`. |
| `platform` | string | A platform slug, for example `instagram`. |
| `status` | string | `live`, `beta`, `planned` or `deprecated`. |
| `limit` | integer | 1–500, default 100. |
| `cursor` | string | `nextCursor` from the previous page. |

**200 OK**: `{ "items": [...], "nextCursor": "…" | null, "total": 123 }`. Each item:

| Field | Type | Description |
|---|---|---|
| `sku`, `title`, `summary` | string | Identity and one-line description. |
| `category`, `platform` | string | Where it lives in the catalog. |
| `kind` | string | `lookup`, `search`, `list`, `transcript`, `validation`, `enrichment`, `scrape`, `monitor` or `composite`. |
| `status` | string | `live` and `beta` can be called; `planned` cannot yet. |
| `restricted` | boolean | Needs an approved account ([Restricted APIs](/docs/restricted-apis)). |
| `mode` | string | `sync`, or `durable` for APIs that usually outlive the wait window. |
| `fromCredits` | number | Headline price in credits: what a call normally costs (per result for per-result APIs, so it can be fractional). |
| `maxCredits` | number | The price ceiling on the same basis: what a call costs when it is retried elsewhere at a higher price. |
| `priceModel` | string | `per_call` or `per_result`. |
| `tags` | string[] | Search keywords. |

```bash
curl -sS "https://api.primaryapi.com/v1/apis?q=email%20verification&limit=5"
```

## GET /v1/apis/\{sku\}

`GET https://api.primaryapi.com/v1/apis/{sku}`

Auth: None

The full contract of one API: the summary fields above, plus

| Field | Type | Description |
|---|---|---|
| `inputSchema` | object | JSON Schema (draft 2020-12) of the request body. Unknown fields are rejected. |
| `outputSchema` | object | JSON Schema of `output.data` when `found` is `true`. |
| `examples` | object[] | Worked examples: `{ input, output? }`. |
| `price` | object | The headline price in credits: `{ "model": "per_call", "credits": 1 }`, or `{ "model": "per_result", "creditsPerResult": 3.2375, "minCredits": 4 }` (a call is rounded up to whole credits and costs at least `minCredits`). `maxCredits` is the ceiling. |
| `health` | object | Measured reliability over 30 days (below). Absent only while statistics are temporarily unavailable. |
| `available` | boolean | `false` when this deployment cannot serve the API right now (calls would answer `503 service_unavailable`). |
| `notes`, `legal` | string | Usage notes and legal remarks, when present. |

`health` is `{ "window": "30d", "status", "successPct", "uptimePct", "latencyP50Ms", "latencyP95Ms", "requests" }`:

| Field | Description |
|---|---|
| `status` | `operational`, `degraded`, `outage` or `unknown` ([what each means](/docs/routing-and-failover#reliability-you-can-check)). |
| `successPct` | Share of calls that returned an answer (found or not found); calls rejected for the caller's own reasons are not counted. |
| `uptimePct` | Share of 5-minute intervals with traffic in which the API answered. |
| `latencyP50Ms`, `latencyP95Ms` | Response time of answered calls. |
| `requests` | Calls measured in the window. |

Figures are `null` until there is traffic to measure.

```json title="GET /v1/apis/email.verify → 200 OK (excerpt)"
{
  "sku": "email.verify",
  "fromCredits": 1,
  "maxCredits": 5,
  "priceModel": "per_call",
  "price": { "model": "per_call", "credits": 1 },
  "available": true,
  "health": {
    "window": "30d",
    "status": "operational",
    "successPct": 99.82,
    "uptimePct": 99.97,
    "latencyP50Ms": 410,
    "latencyP95Ms": 1820,
    "requests": 18452
  }
}
```

Errors: `404 not_found` for an unknown SKU.

## GET /v1/catalog

`GET https://api.primaryapi.com/v1/catalog`

Auth: None

Every callable API in one document, with pricing, measured health and availability: `{ "generatedAt": "…", "apis": [...] }`. Rebuilt at most every 60 seconds. Each entry is `{ sku, name, category, platform, description, mode, status, restricted, pricing: { from, maxCredits }, available, health }`, where `pricing.from` is the headline price in credits (the same shape as `price` above), `pricing.maxCredits` the price ceiling on the same basis, and `health` the object described above (absent while statistics are temporarily unavailable). Use it to mirror the catalog in bulk; use `GET /v1/apis/{sku}` for one API's schemas.

## GET /v1/categories and GET /v1/platforms

`GET https://api.primaryapi.com/v1/categories`

Auth: None

`{ "items": [{ "id", "label", "apiCount", "platformCount" }] }`

`GET https://api.primaryapi.com/v1/platforms`

Auth: None

`{ "items": [{ "platform", "label", "category", "apiCount", "fromCredits" }] }`, where `fromCredits` is what the platform's cheapest per-call API costs a call, or `null` when it has none.

## GET /openapi.json

`GET https://api.primaryapi.com/openapi.json`

Auth: None

An OpenAPI 3.1 document generated from the catalog, with one `POST /v1/run/{sku}` operation per API (request schema, response schema, prices in the description). Import it into an API client, a code generator or a tool that speaks OpenAPI.

## GET /v1/status

`GET https://api.primaryapi.com/v1/status`

Auth: None

Network health over 30 days, as shown on the [Network](https://primaryapi.com/network) page:

| Field | Type | Description |
|---|---|---|
| `generatedAt` | string | When the figures were computed. |
| `window` | string | `30d` |
| `totals` | object | `{ requests, servedPct, rescuedByFailover }`: calls, the share answered, and calls that were answered after an automatic retry. |
| `daily` | object[] | `{ date, requests, servedPct }` per day. |
| `topApis` | object[] | `{ sku, requests, servedPct }` for the busiest APIs. |

Percentages are `null` while there is no traffic to measure.

## GET /v1/status/apis

`GET https://api.primaryapi.com/v1/status/apis`

Auth: None

Health of every visible API, or of one API with `?sku=`. Each item is `{ sku, available, health }`, with `health` as described under [GET /v1/apis/\{sku\}](#get-v1apissku). An unknown `sku` answers `404 not_found`.

```json title="GET /v1/status/apis?sku=email.verify → 200 OK"
[
  {
    "sku": "email.verify",
    "available": true,
    "health": {
      "window": "30d",
      "status": "operational",
      "successPct": 99.82,
      "uptimePct": 99.97,
      "latencyP50Ms": 410,
      "latencyP95Ms": 1820,
      "requests": 18452
    }
  }
]
```

`GET /v1/status/lanes` was retired on 2026-11-05 ([Changelog](/docs/changelog)).

## GET /health and GET /ready

`GET https://api.primaryapi.com/health`

Auth: None

Liveness: the API process is up.

`GET https://api.primaryapi.com/ready`

Auth: None

Readiness: the API can reach its database and serve traffic.
