# 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-17: Full access for signed-in apps

Apps you sign in to with OAuth, such as your MCP client, can now ask for **Full access to your workspace**: everything an API key with full access can do, so an agent can buy and renew domains and change DNS and nameservers. The [MCP server](/docs/mcp-server) asks for it. Only owners and admins can allow it, and a signed-in app still never manages your API keys, webhook signing secrets, monitors, billing or members. Apps you already connected keep their permissions until you sign in to them again.

## 2026-11-17: Full access for Cloudflare connections

A Cloudflare connection now asks for everything your Cloudflare account allows, so you can add sites and reach any part of the Cloudflare API. [Connected accounts](/docs/connected-accounts#cloudflare-everything-your-account-allows) lists the capabilities and what each one unlocks.

**Added**

- Cloudflare capabilities `zones_manage` (add sites, see your accounts) and `everything` (anything the account allows; it includes every other Cloudflare capability).
- `cloudflare.accounts`: the Cloudflare accounts a connection can reach, with their ids.
- `cloudflare.create_zone`: adds a domain to one of your accounts and returns the name servers to set at your registrar.
- `cloudflare.api_request`: any call to the Cloudflare API as the connected account. It can change anything the account allows, so confirm with the person first.
- `connect_error=invalid_scope` when the provider refuses one of the permissions asked for.

**Changed**

- New Cloudflare connections, connect links and invites ask for every Cloudflare capability by default, `everything` included. Send `capabilities` to ask for less.
- Cloudflare accounts connected before this change keep what they had. Connect again to use the new APIs.

## 2026-11-17: Inputs on every request, and stored results for connected accounts

Every call now keeps its input with your request history, restricted APIs included, and `GET /v1/requests/{id}` returns it. Results of private-data APIs are stored like every other call's, so you can re-read them, poll for them and replay them. [Durable requests](/docs/durable-requests#stored-results) and [Connected accounts](/docs/connected-accounts) explain both.

**Added**

- `input` on `GET /v1/requests/{id}`: the input the call was made with. An input over 16 KB is replaced by `{ "_truncated": true, "bytes": <size> }`. It is `null` for calls of restricted APIs and connected accounts made before this change.
- The dashboard's request page shows the input next to the output.

**Changed**

- Restricted APIs keep their input as long as the result (24 hours after a failed call), then delete it. Before, only a one-way fingerprint of it was kept.
- Results of private-data APIs are stored for as long as your plan keeps results, then deleted. `GET /v1/results/{id}` and `read_result` return them; before, they answered `404 not_found`.
- Disconnecting an account doesn't delete results already stored; they are deleted on the normal schedule. Its monitors are still deleted.
- Private-data APIs honour `Prefer` like other APIs, so they may answer `202` for you to poll. Before, they always waited for the outcome.
- An `Idempotency-Key` retry of a private-data call works like any other: a finished call returns its stored result with `replayed: true` and no new charge, and a running one answers `202` with its snapshot instead of `409`. An API that changes the account still never runs twice for one key: a repeat after its stored result was deleted answers `409 idempotency_conflict` with `details.reason: "write_already_done"`.

## 2026-11-17: Sign in to the MCP server

MCP clients can now connect with the server URL alone. Add `https://api.primaryapi.com/mcp` to Claude Code, Cursor, Codex or another client, and it opens the browser so you can sign in, pick a workspace and approve. There is no key to copy. [MCP server](/docs/mcp-server#connect-your-client) has the set-up for each client.

**Added**

- Sign-in with OAuth on the MCP server. A request with no credentials answers `401` with a `WWW-Authenticate` header pointing to `https://api.primaryapi.com/.well-known/oauth-protected-resource/mcp` (RFC 9728), which is how clients find where to sign in.
- A sign-in acts through a key the approval creates in the workspace, listed under Settings › Connected apps. Billing, access levels, spend limits and rate limits are the same as with an API key.
- **Settings › Connected apps** in the dashboard: every app you signed in to, what it can do, what it spent, a spend limit you can change, and Revoke.

**Changed**

- Every MCP request now needs a sign-in or an API key. `search_apis`, `list_apis` and `get_api` used to answer requests that carried neither; those requests now answer `401`. If a client connected that way, sign in or add a key.

API keys work as before, in the `Authorization: Bearer` or `X-API-Key` header. The REST catalog endpoints (`GET /v1/apis`, `GET /v1/apis/{sku}`, `GET /v1/catalog`) and `POST /agent/signup` still need no key.

## 2026-11-15: IP Intelligence detects VPNs and proxies

`ip.intelligence` with `privacy: true` now answers instead of being refused. It costs the same 1 credit as a normal lookup.

**Added**

- Flags: `isResidentialProxy`, `isRelay`, `isSpam` and `isCorporateGateway`. With `privacy: true`, `isVpn`, `isProxy`, `isAbuser` and `isCrawler` are filled too.
- `security` (with `privacy: true`): VPN and proxy provider names, confidence scores and last-seen dates, bot type and operator, and a 0-100 `threatScore`.
- `hostname`, `countryInfo` (calling code, currency, languages), and more location and network detail: region code, district, accuracy radius, UTC offset, AS registry and allocation date, route, CDN and connection type.

Lookups without `privacy: true` work as before. The new fields are `null` there, and `riskScore` is worked out the same way on both kinds of lookup.

## 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: Every customer invite needs a redirect URL

`redirectUrl` is now required when you create a customer invite: the page in your product your customer lands on after connecting. There is no workspace default, and nothing is carried over from an earlier invite. [Connected accounts](/docs/connected-accounts#connect-your-customers-accounts) shows the request.

**Changed**

- `POST /v1/connections/{provider}/invites` answers `400 invalid_input` when `redirectUrl` is left out, `null` or blank, with `details[0].path` set to `["redirectUrl"]`, as it already did for an invalid one. If your code creates invites without it, add it.
- Invites created before this change keep working. Their `redirectUrl` stays `null`, and their customers see "Connected. You can close this window." when they finish.
- When a customer's account needs a new invite, the `connection_required` and `connection_needs_reauth` messages now say to send your `redirectUrl` with it.

## 2026-11-12: Webhook endpoints, attempt logs, invite redirects and retention by plan

Your workspace can register webhook endpoints that hear about its connected accounts, and every webhook delivery now keeps a log of each attempt. Customer invites can send the customer back to your product. 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), [Connected accounts](/docs/connected-accounts#send-customers-back-to-your-product), [Monitors](/docs/monitors#when-runs-keep-failing) and [Pricing and billing](/docs/pricing-and-billing#data-retention) explain each.

**Added**

- Webhook endpoints: `GET` and `POST /v1/webhook-endpoints`, `GET`, `PATCH` and `DELETE /v1/webhook-endpoints/{id}`, `POST /v1/webhook-endpoints/{id}/test`, `GET /v1/webhook-endpoints/{id}/deliveries`, `GET /v1/webhook-endpoints/{id}/deliveries/{deliveryId}` and `POST /v1/webhook-endpoints/{id}/deliveries/{deliveryId}/redeliver`. Owners, admins and full-access keys; at most 10 per workspace.
- The events `connection.connected`, `connection.needs_reauth`, `connection.disconnected` (with `deletedMonitorIds`), `connection.invite_expired` and `webhook_endpoint.test`, signed with the same secret as monitor webhooks.
- The attempt log: `attemptLog` on `GET /v1/monitors/{id}/deliveries/{deliveryId}` (new) and on the endpoint delivery route. 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.
- `redirectUrl` on customer invites, and `redirectUrl`, `inviteId` and `connectionId` on the customer's page (`GET /v1/connect/{token}`). The page sends the customer back with `status`, `connection_id`, `invite_id` and `error`; never your custom ID.
- `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.
- Expired invites are stored as `expired` within about a minute of their expiry. Revoking an expired invite leaves it `expired` instead of making it `revoked`.
- 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, and disconnected accounts

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. Disconnecting a connected account now deletes the monitors that read it. [Monitors](/docs/monitors#when-runs-keep-failing) explains both.

*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.
- The `connectionId` filter on `GET /v1/monitors`: the monitors that read one connected account.

**Changed**

- Disconnecting an account deletes its monitors, paused ones included, instead of pausing them. Their custom IDs are free again. Reconnecting doesn't bring them back.
- `pausedReason` no longer has the value `connection_revoked`, and resuming no longer answers `422 unprocessable` for a disconnected account (its monitors are gone).

## 2026-11-12: Monitor a connected account

APIs that read a connected account, such as `github.my_repos` or `gmail.search`, can now be monitored. Each monitor reads one account, and their results stay private: change detection keeps only a hash, and webhook events are stored encrypted until they are delivered. [Monitors](/docs/monitors#monitor-a-connected-account) explains it.

**Added**

- Monitors of private-data APIs. Pick the account with `input.connection` (id, custom ID, handle or name). It can be left out when only one account can run the API. The monitor keeps the account's id.
- `connection` on monitors and on webhook events: the account the monitor reads (`id`, `provider`, `label`, `name`, `customId`, `status`), or `null`.
- `pausedReason` on monitors: why we paused it (see the entry above).
- The skip reason `key_connections_access`: the monitor's key may no longer use connected accounts.

**Changed**

- Creating a monitor of a private-data API no longer answers `422 unprocessable`. API keys need access to connected accounts to create or change such a monitor (`403 forbidden`).
- Disconnecting an account deletes the monitors that read it (see the entry above).
- Redelivering an event of such a monitor after it was delivered answers `422 unprocessable` (`details.reason`: `event_body_deleted`), because its body is deleted once delivered.

## 2026-11-12: Many connected accounts, custom IDs and customer invites

A workspace can connect many accounts of the same provider, for example one Instagram account per client, and tell them apart by your own name and custom ID. Invite links let your customers connect their own accounts without a PrimaryAPI account. [Connected accounts](/docs/connected-accounts) explains both.

**Added**

- `name` and `customId` on connections: set them when connecting, or later with `PATCH /v1/connections/{id}`. A `customId` is unique among the workspace's connections that are not disconnected (`409 custom_id_taken`).
- `GET /v1/connections/{id}` and `GET /v1/connections/by-custom-id/{customId}`, and the `provider`, `customId`, `q` and `status` filters on `GET /v1/connections`.
- `connectedVia` (`member`, `link` or `invite`) and `inviteId` on connections.
- Customer invites: `POST /v1/connections/{provider}/invites`, `GET /v1/connections/invites` and `DELETE /v1/connections/invites/{id}`. An invite is a single-use link that expires after 1 to 30 days (7 by default).
- The error code `invite_unavailable` (`410`): an invite link that was used, expired or was cancelled.
- `connection` on `GET /v1/requests` items: the account a private-data call ran as.
- API keys with `full` access and access to connected accounts can create invites, rename connections and disconnect them.

**Changed**

- The `connection` input of private-data APIs also matches a connection's `customId` (exactly, right after its id) and its `name` (any case, after the handle). A handle or name that matches two accounts answers `400 invalid_input` with the candidates in `details.connections`, which now carry `name` and `customId`.
- `GET /v1/connections` no longer lists disconnected accounts unless you ask for `status=revoked`.
- Connecting another account of a provider from the same browser now asks which account to use, instead of reusing the one already signed in.

## 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.
