Changelog
Changes to the API, the MCP server, the agent files and these docs, newest first.
Last updated
On this page
- 2026-11-17: Full access for signed-in apps
- 2026-11-17: Full access for Cloudflare connections
- 2026-11-17: Inputs on every request, and stored results for connected accounts
- 2026-11-17: Sign in to the MCP server
- 2026-11-15: IP Intelligence detects VPNs and proxies
- 2026-11-15: Accounts are called workspaces everywhere
- 2026-11-12: Every customer invite needs a redirect URL
- 2026-11-12: Webhook endpoints, attempt logs, invite redirects and retention by plan
- 2026-11-12: Monitors that keep failing, and disconnected accounts
- 2026-11-12: Monitor a connected account
- 2026-11-12: Many connected accounts, custom IDs and customer invites
- 2026-11-09: Monitors and webhooks
- 2026-11-09: Auto top-up and spend alerts
- 2026-11-09: Credits replace the dollar balance
- 2026-11-05: API-level reliability, provider-free responses
- 2026-10-30: API v1 and documentation
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 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 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 lists the capabilities and what each one unlocks.
Added
- Cloudflare capabilities
zones_manage(add sites, see your accounts) andeverything(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_scopewhen the provider refuses one of the permissions asked for.
Changed
- New Cloudflare connections, connect links and invites ask for every Cloudflare capability by default,
everythingincluded. Sendcapabilitiesto 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 and Connected accounts explain both.
Added
inputonGET /v1/requests/{id}: the input the call was made with. An input over 16 KB is replaced by{ "_truncated": true, "bytes": <size> }. It isnullfor 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}andread_resultreturn them; before, they answered404 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
Preferlike other APIs, so they may answer202for you to poll. Before, they always waited for the outcome. - An
Idempotency-Keyretry of a private-data call works like any other: a finished call returns its stored result withreplayed: trueand no new charge, and a running one answers202with its snapshot instead of409. An API that changes the account still never runs twice for one key: a repeat after its stored result was deleted answers409 idempotency_conflictwithdetails.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 has the set-up for each client.
Added
- Sign-in with OAuth on the MCP server. A request with no credentials answers
401with aWWW-Authenticateheader pointing tohttps://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_apisandget_apiused to answer requests that carried neither; those requests now answer401. 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,isSpamandisCorporateGateway. Withprivacy: true,isVpn,isProxy,isAbuserandisCrawlerare filled too. security(withprivacy: true): VPN and proxy provider names, confidence scores and last-seen dates, bot type and operator, and a 0-100threatScore.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/accountis nowGET /v1/workspace, andPOST /v1/account/restricted-termsis nowPOST /v1/workspace/restricted-terms. The old paths answer 404.- Request fields named
accountIdare nowworkspaceId(POST /v1/agent/claim/{token}/approve). A request that still sendsaccountIdis refused with 400. - The dashboard's workspace header is
X-Workspace-Id;X-Account-Idis 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 shows the request.
Changed
POST /v1/connections/{provider}/invitesanswers400 invalid_inputwhenredirectUrlis left out,nullor blank, withdetails[0].pathset 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
redirectUrlstaysnull, and their customers see "Connected. You can close this window." when they finish. - When a customer's account needs a new invite, the
connection_requiredandconnection_needs_reauthmessages now say to send yourredirectUrlwith 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, Connected accounts, Monitors and Pricing and billing explain each.
Added
- Webhook endpoints:
GETandPOST /v1/webhook-endpoints,GET,PATCHandDELETE /v1/webhook-endpoints/{id},POST /v1/webhook-endpoints/{id}/test,GET /v1/webhook-endpoints/{id}/deliveries,GET /v1/webhook-endpoints/{id}/deliveries/{deliveryId}andPOST /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(withdeletedMonitorIds),connection.invite_expiredandwebhook_endpoint.test, signed with the same secret as monitor webhooks. - The attempt log:
attemptLogonGET /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. redirectUrlon customer invites, andredirectUrl,inviteIdandconnectionIdon the customer's page (GET /v1/connect/{token}). The page sends the customer back withstatus,connection_id,invite_idanderror; never your custom ID.consecutiveFailureson monitors, and onmonitorPausedin 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 unprocessablewithdetails.reason: "event_body_deleted", for every event. It used to answer404 not_foundfor 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
expiredwithin about a minute of their expiry. Revoking an expired invite leaves itexpiredinstead of making itrevoked. - 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 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
failingSinceon monitors: when the current run of failures began, ornull.pausedReason: "failing": every run failed for 7 days, so we paused the monitor. Resuming clears it andfailingSince.monitorPaused(reason,failingSince) on themonitor.run.failedevent of the run that paused the monitor. It is left out of every other event.- The
connectionIdfilter onGET /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.
pausedReasonno longer has the valueconnection_revoked, and resuming no longer answers422 unprocessablefor 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 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. connectionon monitors and on webhook events: the account the monitor reads (id,provider,label,name,customId,status), ornull.pausedReasonon 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 explains both.
Added
nameandcustomIdon connections: set them when connecting, or later withPATCH /v1/connections/{id}. AcustomIdis unique among the workspace's connections that are not disconnected (409 custom_id_taken).GET /v1/connections/{id}andGET /v1/connections/by-custom-id/{customId}, and theprovider,customId,qandstatusfilters onGET /v1/connections.connectedVia(member,linkorinvite) andinviteIdon connections.- Customer invites:
POST /v1/connections/{provider}/invites,GET /v1/connections/invitesandDELETE /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. connectiononGET /v1/requestsitems: the account a private-data call ran as.- API keys with
fullaccess and access to connected accounts can create invites, rename connections and disconnect them.
Changed
- The
connectioninput of private-data APIs also matches a connection'scustomId(exactly, right after its id) and itsname(any case, after the handle). A handle or name that matches two accounts answers400 invalid_inputwith the candidates indetails.connections, which now carrynameandcustomId. GET /v1/connectionsno longer lists disconnected accounts unless you ask forstatus=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 and Webhooks explain both.
Added
POST /v1/monitors,GET /v1/monitors(status,skuandcustomIdfilters),GET,PATCHandDELETE /v1/monitors/{id}, andGET /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;202while the API is still working),POST /v1/monitors/{id}/test(a freemonitor.testevent),GET /v1/monitors/{id}/runsandGET /v1/monitors/{id}/deliveries, andPOST /v1/monitors/{id}/deliveries/{deliveryId}/redeliver.GET /v1/webhooks/secretandPOST /v1/webhooks/secret/rotate: the workspace's signing secret, for owners, admins and keys with full access.- Webhook events
monitor.run.succeeded,monitor.run.failedandmonitor.test, with thePrimaryAPI-Signature,PrimaryAPI-Event-Id,PrimaryAPI-Event-Type,PrimaryAPI-Delivery-IdandPrimaryAPI-Delivery-Attemptheaders. - The error code
custom_id_taken(409): another monitor of the workspace already uses thatcustomId. - 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 explains how they work.
Added
GET /v1/billing/auto-topup(key with view or full access, or the dashboard) andPUT /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/setupopens Stripe's page to save a card;DELETE /v1/billing/cardforgets it and turns auto top-up off. Both are dashboard-only.sourceonGET /v1/billing/ordersitems:checkout,autoordev.
Changed
GET /v1/billing/orderslists 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, soexpireditems 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 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→creditson the run envelope, stored results (GET /v1/results/{id}), request snapshots (GET /v1/requests/{id}) andGET /v1/requestsitems. It is a whole number of credits,0when nothing was charged.POST /v1/quote/{sku}:costUsdandmaxCostUsd→creditsandmaxCredits. The quote is{ sku, credits, maxCredits, unit, inputValid }.- The routing control
maxCostUsd→maxCredits, a whole number of credits, in REST bodies and in MCPrun_api. A request that still sendsmaxCostUsdnow answers400 invalid_inputnamingmaxCredits, instead of running without the cap. A cap that the input cannot fit answers400 invalid_inputwithdetails{ maxCredits, cheapestCredits }. - Catalog prices:
fromPer1kUsdandmaxPer1kUsd→fromCreditsandmaxCreditsonGET /v1/apisandGET /v1/apis/{sku}, in credits per call, or per result for per-result APIs.priceModelis nowper_callorper_result(it wasflatorper_result), andpriceis{ "model": "per_call", "credits" }or{ "model": "per_result", "creditsPerResult", "minCredits" }.GET /v1/platformsitems carryfromCredits, andGET /v1/catalogentries carrypricing: { from, maxCredits }. GET /v1/balancereturns credits:{ credits, paidCredits, promoCredits, promoExpiresAt, includedCredits, includedExpiry, creditPriceUsd }, replacingcurrency,balanceUsd,paidUsdandpromoUsd.GET /v1/accountcarriesbalanceCreditsandpromoCredits, and MCPget_balancereports credits.- Billing:
POST /v1/billing/checkouttakes{ "credits": N }(a pack, or any amount from 1,000 to 1,000,000 in steps of 100) instead ofamountUsd.GET /v1/billing/packslists credit packs, ledger entries carrycreditsandbalanceAfterCredits, and orders carrycreditsnext to theamountUsdpaid. - API keys:
limitUsd,spentInWindowUsdandspentTotalUsd→limitCredits,spentInWindowCreditsandspentTotalCredits. Spend limits are whole credits. - Usage:
GET /v1/usageandGET /v1/api-keys/{id}/usagereporttodayCredits,thisWeekCredits,thisMonthCreditsandtotalCredits, andcreditsper API, per day and per member. - Agents:
capUsd→capCreditsonPOST /agent/signup. The claim receipt reportsspentCredits,capCreditsandcreditsfor each recent call, and approving a key takeslimitCredits. Connected apps' spend limits (OAuth grants) arelimitCreditstoo. - Error
detailsthat carried amounts now carry credits, for examplebalanceCreditsonworkspace_has_balance. The codesinsufficient_balance,key_limit_reachedandtrial_cap_reachedare 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)
sourcefrom the run envelope, from stored results (GET /v1/results/{id}, request snapshots) and fromGET /v1/requestsitems.providerstays and is alwaysPrimaryAPI.lanesfromPOST /v1/quote/{sku}: the quote is{ sku, costUsd, maxCostUsd, unit, inputValid }.laneCountfrom API summaries (GET /v1/apis),lanesfromGET /v1/apis/{sku}andGET /v1/catalog, andtotals.lanesfrom the catalog snapshot.GET /v1/status/lanes. UseGET /v1/status/apisinstead.detailsonall_sources_failed,timeout,unprocessableand upstream-rejectedinvalid_inputerrors (they used to list each attempt's source). Quote therequestIdto support instead.
Retired, still accepted
- The
source,allowFallbacksandignoreSourcesrouting controls are retired. In a REST request body they are accepted and ignored, so existing requests keep working; MCPrun_apino longer offers them (its arguments are strict). UsemaxCostUsdto cap a call's price.source_unavailableis no longer returned.
Added
healthonGET /v1/apis/{sku}andGET /v1/catalog:{ window, status, successPct, uptimePct, latencyP50Ms, latencyP95Ms, requests }, withstatusone ofoperational,degraded,outage,unknown. Alsoavailable(whether the API can be served right now) andprice(the headline price) onGET /v1/apis/{sku}.GET /v1/status/apis(optional?sku=):[{ sku, available, health }]for every visible API. See Routing and failover.- MCP
get_apireturnspricingandhealthinstead 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
Preferheader (respond-async,wait=Nup to 90 seconds),202withLocation,GET /v1/requests/{id}, stored results for at least 24 hours withGET /v1/results/{id}. Idempotency-Keyon runs, with replays, conflict detection and safe retries after temporary failures.- Response trimming with
fields,max_itemsandsummary. - API keys with
full,runandviewaccess, 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/mcpwith 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.