# Changelog

Changes to the API, the MCP server, the agent files and these docs, newest first.

We add fields, SKUs and error details without notice; a client should ignore fields it does not know. Anything that could break a working integration (removing a field, changing a type or a meaning, removing an endpoint) would ship under a new version prefix with advance notice here. New and changed APIs in the catalog are visible in the [API reference](/docs/api-reference) and in `GET /v1/apis`.

## 2026-11-15: Accounts are called workspaces everywhere

The dashboard has always called them workspaces; the API now does too. The old names are no longer accepted.

**Changed**

- `GET /v1/account` is now `GET /v1/workspace`, and `POST /v1/account/restricted-terms` is now `POST /v1/workspace/restricted-terms`. The old paths answer 404.
- Request fields named `accountId` are now `workspaceId` (`POST /v1/agent/claim/{token}/approve`). A request that still sends `accountId` is refused with 400.
- The dashboard's workspace header is `X-Workspace-Id`; `X-Account-Id` is ignored.
- Error messages say "workspace" where they said "account".

## 2026-11-12: Attempt logs and retention by plan

Every webhook delivery now keeps a log of each attempt. Monitors pause after 10 failed runs in a row instead of after 7 days. How long results and event bodies are kept now depends on your plan. [Webhooks](/docs/webhooks), [Monitors](/docs/monitors#when-runs-keep-failing) and [Pricing and billing](/docs/pricing-and-billing#data-retention) explain each.

**Added**

- The attempt log: `attemptLog` on `GET /v1/monitors/{id}/deliveries/{deliveryId}` (new). Each attempt's start, duration, status or error (`timeout`, `connection_refused`, `connection_reset`, `tls_failed`, `connect_failed`, `dns_failed`, `blocked_url`, `http_<status>` …), the first 1,024 bytes of the response, and the next attempt's time.
- `consecutiveFailures` on monitors, and on `monitorPaused` in the failure event of the run that paused it.

**Changed**

- Monitors pause after 10 failed runs in a row, replacing the 7-day rule. A run also counts as failed when its call succeeded but its webhook was still undelivered after every retry; a success resets the count.
- Call results are kept 24 hours on Pay as you go and 7, 30 or 90 days on Builder, Pro, Scale and Enterprise. Webhook event bodies are kept until delivered on Pay as you go, and the same days on a plan. Both are fixed when the data is made. Before, results were kept at least 24 hours and event bodies 7 days for everyone.
- Redelivering an event whose body is no longer kept now answers `422 unprocessable` with `details.reason: "event_body_deleted"`, for every event. It used to answer `404 not_found` for events past retention. If your code checks for the 404, check for the 422 too.
- On Pay as you go, an event can be redelivered only while a delivery of it is still pending or retrying.
- Delivery attempts now keep the first 1,024 bytes of your endpoint's response in the attempt log. Keep response bodies short and free of secrets.

## 2026-11-12: Monitors that keep failing

A failed run never pauses a monitor. Only when every run has failed for 7 days in a row do we pause it, and that run's failure event says so. [Monitors](/docs/monitors#when-runs-keep-failing) explains it.

*Replaced later the same day: monitors now pause after 10 failed runs in a row, not after 7 days (see the entry above).*

**Added**

- `failingSince` on monitors: when the current run of failures began, or `null`.
- `pausedReason: "failing"`: every run failed for 7 days, so we paused the monitor. Resuming clears it and `failingSince`.
- `monitorPaused` (`reason`, `failingSince`) on the `monitor.run.failed` event of the run that paused the monitor. It is left out of every other event.

## 2026-11-09: Monitors and webhooks

Monitors run an API on a schedule with input you save, and send the result to your webhook URL: the first result and every change, or every result. A run is an ordinary call of the API, with the same credits, and a failed or skipped run costs nothing. Webhooks are signed and retried for almost four days. [Monitors](/docs/monitors) and [Webhooks](/docs/webhooks) explain both.

**Added**

- `POST /v1/monitors`, `GET /v1/monitors` (`status`, `sku` and `customId` filters), `GET`, `PATCH` and `DELETE /v1/monitors/{id}`, and `GET /v1/monitors/by-custom-id/{customId}`, to find a monitor by your own reference.
- `POST /v1/monitors/{id}/run` (run now, charged like a call; `202` while the API is still working), `POST /v1/monitors/{id}/test` (a free `monitor.test` event), `GET /v1/monitors/{id}/runs` and `GET /v1/monitors/{id}/deliveries`, and `POST /v1/monitors/{id}/deliveries/{deliveryId}/redeliver`.
- `GET /v1/webhooks/secret` and `POST /v1/webhooks/secret/rotate`: the workspace's signing secret, for owners, admins and keys with full access.
- Webhook events `monitor.run.succeeded`, `monitor.run.failed` and `monitor.test`, with the `PrimaryAPI-Signature`, `PrimaryAPI-Event-Id`, `PrimaryAPI-Event-Type`, `PrimaryAPI-Delivery-Id` and `PrimaryAPI-Delivery-Attempt` headers.
- The error code `custom_id_taken` (`409`): another monitor of the workspace already uses that `customId`.
- A role permission for monitors: owners, admins and developers create and change them; every member can read them.

## 2026-11-09: Auto top-up and spend alerts

Auto top-up buys credits with a saved card whenever your balance falls below a threshold you choose, and spend alerts email your team as auto top-up spend passes parts of a monthly budget. Both are set in Dashboard → Settings → Billing; [Pricing and billing](/docs/pricing-and-billing#auto-top-up) explains how they work.

**Added**

- `GET /v1/billing/auto-topup` (key with view or full access, or the dashboard) and `PUT /v1/billing/auto-topup` (dashboard): the settings, the saved card's brand, last four digits and expiry, and this month's auto top-up spend.
- `POST /v1/billing/card/setup` opens Stripe's page to save a card; `DELETE /v1/billing/card` forgets it and turns auto top-up off. Both are dashboard-only.
- `source` on `GET /v1/billing/orders` items: `checkout`, `auto` or `dev`.

**Changed**

- `GET /v1/billing/orders` lists purchases only: a checkout appears once it is paid, or once you finish it with a bank payment that is still clearing. Checkouts that were opened and not finished are no longer listed, so `expired` items no longer appear.

## 2026-11-09: Credits replace the dollar balance

You now buy and spend whole credits instead of holding a balance in US dollars. Every API has a price in credits, and it is the same on every plan. A credit is $0.005 on Pay as you go; plans include credits every month at a discount (a deeper one billed yearly) and sell extra credits for less than Pay as you go. [Pricing and billing](/docs/pricing-and-billing) explains how it works. Error codes are unchanged, but fields that carried dollars were renamed, so check your client against the list below.

**Renamed (breaking)**

- `costUsd` → `credits` on the run envelope, stored results (`GET /v1/results/{id}`), request snapshots (`GET /v1/requests/{id}`) and `GET /v1/requests` items. It is a whole number of credits, `0` when nothing was charged.
- `POST /v1/quote/{sku}`: `costUsd` and `maxCostUsd` → `credits` and `maxCredits`. The quote is `{ sku, credits, maxCredits, unit, inputValid }`.
- The routing control `maxCostUsd` → `maxCredits`, a whole number of credits, in REST bodies and in MCP `run_api`. A request that still sends `maxCostUsd` now answers `400 invalid_input` naming `maxCredits`, instead of running without the cap. A cap that the input cannot fit answers `400 invalid_input` with `details` `{ maxCredits, cheapestCredits }`.
- Catalog prices: `fromPer1kUsd` and `maxPer1kUsd` → `fromCredits` and `maxCredits` on `GET /v1/apis` and `GET /v1/apis/{sku}`, in credits per call, or per result for per-result APIs. `priceModel` is now `per_call` or `per_result` (it was `flat` or `per_result`), and `price` is `{ "model": "per_call", "credits" }` or `{ "model": "per_result", "creditsPerResult", "minCredits" }`. `GET /v1/platforms` items carry `fromCredits`, and `GET /v1/catalog` entries carry `pricing: { from, maxCredits }`.
- `GET /v1/balance` returns credits: `{ credits, paidCredits, promoCredits, promoExpiresAt, includedCredits, includedExpiry, creditPriceUsd }`, replacing `currency`, `balanceUsd`, `paidUsd` and `promoUsd`. `GET /v1/account` carries `balanceCredits` and `promoCredits`, and MCP `get_balance` reports credits.
- Billing: `POST /v1/billing/checkout` takes `{ "credits": N }` (a pack, or any amount from 1,000 to 1,000,000 in steps of 100) instead of `amountUsd`. `GET /v1/billing/packs` lists credit packs, ledger entries carry `credits` and `balanceAfterCredits`, and orders carry `credits` next to the `amountUsd` paid.
- API keys: `limitUsd`, `spentInWindowUsd` and `spentTotalUsd` → `limitCredits`, `spentInWindowCredits` and `spentTotalCredits`. Spend limits are whole credits.
- Usage: `GET /v1/usage` and `GET /v1/api-keys/{id}/usage` report `todayCredits`, `thisWeekCredits`, `thisMonthCredits` and `totalCredits`, and `credits` per API, per day and per member.
- Agents: `capUsd` → `capCredits` on `POST /agent/signup`. The claim receipt reports `spentCredits`, `capCredits` and `credits` for each recent call, and approving a key takes `limitCredits`. Connected apps' spend limits (OAuth grants) are `limitCredits` too.
- Error `details` that carried amounts now carry credits, for example `balanceCredits` on `workspace_has_balance`. The codes `insufficient_balance`, `key_limit_reached` and `trial_cap_reached` are unchanged.

## 2026-11-05: API-level reliability, provider-free responses

What served a call is now an internal detail: responses, request history, the catalog and the MCP tools show whether an API works and what it costs, never which upstream answered or how many sit behind an API. Some of these changes remove fields, so check your client against the list below.

**Removed (breaking)**

- `source` from the run envelope, from stored results (`GET /v1/results/{id}`, request snapshots) and from `GET /v1/requests` items. `provider` stays and is always `PrimaryAPI`.
- `lanes` from `POST /v1/quote/{sku}`: the quote is `{ sku, costUsd, maxCostUsd, unit, inputValid }`.
- `laneCount` from API summaries (`GET /v1/apis`), `lanes` from `GET /v1/apis/{sku}` and `GET /v1/catalog`, and `totals.lanes` from the catalog snapshot.
- `GET /v1/status/lanes`. Use `GET /v1/status/apis` instead.
- `details` on `all_sources_failed`, `timeout`, `unprocessable` and upstream-rejected `invalid_input` errors (they used to list each attempt's source). Quote the `requestId` to support instead.

**Retired, still accepted**

- The `source`, `allowFallbacks` and `ignoreSources` routing controls are retired. In a REST request body they are accepted and ignored, so existing requests keep working; MCP `run_api` no longer offers them (its arguments are strict). Use `maxCostUsd` to cap a call's price. `source_unavailable` is no longer returned.

**Added**

- `health` on `GET /v1/apis/{sku}` and `GET /v1/catalog`: `{ window, status, successPct, uptimePct, latencyP50Ms, latencyP95Ms, requests }`, with `status` one of `operational`, `degraded`, `outage`, `unknown`. Also `available` (whether the API can be served right now) and `price` (the headline price) on `GET /v1/apis/{sku}`.
- `GET /v1/status/apis` (optional `?sku=`): `[{ sku, available, health }]` for every visible API. See [Routing and failover](/docs/routing-and-failover#reliability-you-can-check).
- MCP `get_api` returns `pricing` and `health` instead of a per-source list.

## 2026-10-30: API v1 and documentation

The first public version of the API and of these docs.

**API**

- `POST /v1/run/{sku}` with one envelope for every API, routing to the cheapest healthy source and automatic failover.
- Routing controls on every call: `source`, `allowFallbacks`, `ignoreSources`, `preferLatencyUnderMs`, `maxCostUsd`.
- `POST /v1/quote/{sku}`: validation and pricing without a charge.
- Durable requests: the `Prefer` header (`respond-async`, `wait=N` up to 90 seconds), `202` with `Location`, `GET /v1/requests/{id}`, stored results for at least 24 hours with `GET /v1/results/{id}`.
- `Idempotency-Key` on runs, with replays, conflict detection and safe retries after temporary failures.
- Response trimming with `fields`, `max_items` and `summary`.
- API keys with `full`, `run` and `view` access, per-key spend limits (daily, weekly, monthly or lifetime, in UTC windows), expiry, disable, rotate and revoke.
- Prepaid wallet with promotional and paid balances, Stripe top-ups, ledger, usage reports per API, per day and per key.
- Public catalog and status endpoints: `GET /v1/apis`, `GET /v1/apis/{sku}`, `GET /v1/catalog`, `GET /v1/categories`, `GET /v1/platforms`, `GET /v1/status`, `GET /v1/status/lanes`, `GET /openapi.json`.
- Feedback endpoints: `POST /v1/feedback`, `POST /v1/bug-reports`, `POST /v1/api-requests`.

**Agents**

- `POST /agent/signup`: self-service trial keys with a budget, and a claim flow that lets a human approve the same key.
- MCP server at `https://api.primaryapi.com/mcp` with ten tools: `search_apis`, `list_apis`, `get_api`, `quote_api`, `run_api`, `get_request`, `read_result`, `get_balance`, `report_bug`, `send_feedback`.
- `/SKILL.md`, `/agent-onboarding/SKILL.md`, `/llms.txt`, `/llms-full.txt`, and a Markdown version of every docs page under `/docs/md`.

**Docs**

- Guides for every part of the API, a generated reference page for every API in the catalog, and hand-written references for the account endpoints.
