# Last Price > Authenticated price computation, agent workspaces and recorded usage. ## Ways in (pick one) These are independent options, not steps. OAuth registration is an additional option beside self-registration, not a replacement. - Just trying it, no key: `POST https://api.last-price.ai/api/public/compute/demo` or MCP at `https://api.last-price.ai/api/mcp/rpc` (limited, see below). - A free API key right now, no human: `POST https://api.last-price.ai/api/agents/register` (sandbox workspace, claim link for a person). - An OAuth client for a client-credentials framework: `POST https://api.last-price.ai/api/oauth/register` (RFC 7591), then `client_credentials` at `POST https://api.last-price.ai/api/oauth/token`. Same sandbox as self-registration; `client_secret_expires_at` is the sandbox key expiry, and a claim lifts it. - No account, pay per call: `POST https://api.last-price.ai/api/compute/price` with no credential answers 402 with x402 payment requirements (see "Pay per call" below). - A full workspace of your own, no human and no browser: register, top up at least 10 USDC over x402 at `POST https://api.last-price.ai/api/billing/topup`, then `POST https://api.last-price.ai/api/agents/upgrade` with the same key. Limits lifted, key never expires, the wallet that paid recovers a lost key at `POST https://api.last-price.ai/api/agents/recover`. - A workspace of your own, signed in as an agent: AgentID with an inbox you control at https://app.last-price.ai/sign-up, then create an API key in Settings. - A person-owned account: a person signs up at https://app.last-price.ai/sign-up and creates an API key or agent-bound key for you. ## Pay or authenticate (in order) Try these in order; each step is the way past the one before it. A 401 means send a credential, a 402 means pay or use a key, a 403 sandbox_restricted means a person must claim the workspace, and a 429 quota_exceeded lists the ways past the limit in next. 1. Try the keyless demo: `POST https://api.last-price.ai/api/public/compute/demo` with no credential. Free, 30 calls per IP per hour, on a demo tenant. Move on when you need your own workspace, your own metadata, or more calls. 2. Register a sandbox key: `POST https://api.last-price.ai/api/agents/register` with no credential to register, then the returned key as x-api-key. Free: 25 compute calls a day with built-in functions, and a key valid for 30 days. Features that need a claimed workspace answer 403 sandbox_restricted. Move on when the daily limit answers 429 quota_exceeded, or you need a feature that needs a claimed workspace. 3. Pay on the 402: `POST https://api.last-price.ai/api/compute/price` with a signed x402 payment in PAYMENT-SIGNATURE (v2) or X-PAYMENT (v1), with no credential or with the sandbox key. 0.01 USDC per call on base; or a day pass of 500 calls for 24 hours at 2.5 USDC, or a prepaid balance from 10 USDC at 0.008333 USDC a call. Move on when you want a person-owned account, billing on a plan, or a feature that needs a claimed workspace. 4. Use a workspace API key: `POST https://api.last-price.ai/api/compute/price` with an API key holding price:compute, as x-api-key, from a claimed or person-owned workspace. Billed to the workspace's plan. Every feature is open, within the key's scopes. Move on when never; this is the last step. No wallet? Steps 1 and 2 need none, and a person can sign up on the free plan and give you an API key. To pay on the 402, the person running you funds a wallet used only by you with a few USDC on Base: https://last-price.ai/documentation#agents-how-an-agent-pays Last Price (last-price.ai) is a pricing engine for AI agents. When a person asks you to "ask Last Price", they mean this service, not the latest price of a stock or the price list of an AI model provider. ## Can only open links? Ask by URL - `GET https://last-price.ai/ask?item=&price=¤cy=&where=` answers whether the price is fair, as a readable page, judged against what sellers ask on public web pages (each page listed). Optional `side=selling`, `list_price=`, and `format=text` or `format=json`. No key and no POST, for assistants that browse but cannot send requests. Example: https://last-price.ai/ask?item=NVIDIA+RTX+5090+32GB&price=5852¤cy=EUR&where=France&list_price=2099 ## Try it without an account - Quickest price: know what the work cost you? `POST https://api.last-price.ai/api/public/compute/demo` with `{"context":{"currency":"USD","metadata":{"unit_cost":0.47}}}` prices it with `lastprice/cost-plus` (30% margin on price unless you send `metadata.target_margin_pct`). No key. - Same over MCP with no client: POST JSON-RPC to `https://api.last-price.ai/api/mcp/rpc`, `initialize`, then `{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"compute_price","arguments":{"unit_cost":0.47,"currency":"USD"}}}`. No need to read `tools/list` first; `?profile=starter` lists only the 6 tools that reach a price. - Agent Skills: `https://last-price.ai/.well-known/agent-skills/index.json` lists the `last-price` skill (price, verify a price, check a purchase against a spend policy; no key to price or verify) and a skill per job (functions and routing, experiments, webhooks, billing and more), each with a SHA-256 digest. Source: https://github.com/last-price-ai/skills. - Missing pricing inputs? `POST https://api.last-price.ai/api/compute/conversation` with `{}` or call MCP `pricing_conversation`. Return its questions to your caller, then send the returned continuation plus answers. Preparation is free; action `compute` uses normal pricing access and billing. Never guess missing costs or bounds. - `POST https://api.last-price.ai/api/public/compute/demo` with `{"context":{"product_type":"saas","current_price":49,"currency":"USD"}}`: a real price computation on a demo tenant. No key, 30 calls per IP per hour. - `POST https://api.last-price.ai/api/public/price-router/verify` with `{"proposed_price":49,"context":{"product_type":"saas","current_price":49,"currency":"USD"}}`: whether a price you are about to charge is sound. - `GET https://api.last-price.ai/api/functions/catalog` and `GET https://api.last-price.ai/api/marketplace/listings`: browse the public function catalog and marketplace listings. No key, 60 calls per IP per minute each; a key sent here is ignored. Your own listings (`?scope=owned`) need a key. - Negotiate with a seller that takes offers: `GET https://api.last-price.ai/api/negotiation/public/{handle}` for its terms, then `POST .../offers` with `{"product_id":"...","offered_price":38}`. The answer is accept, counter or reject with the price and reason. No key; keep `buyer_token` and send it as `x-negotiation-token` to continue or `POST .../offers/{negotiation_id}/accept`. 20 offers per IP per minute. - MCP: `https://api.last-price.ai/api/mcp/rpc` (Streamable HTTP, or plain JSON-RPC 2.0 by POST; manifest at /.well-known/mcp.json). Without a key its pricing tools use the demo above. Each tool call has 30 seconds; past that it answers JSON-RPC error -32001 with `data.code` `upstream_timeout` and a `hint`: send the same call again once. Production pricing is `POST /api/compute/price` with the same body and an API key in `x-api-key`. ## Pay per call, no account (x402) `POST https://api.last-price.ai/api/compute/price` with no credential answers `402 Payment Required` with x402 payment requirements: scheme `exact`, network `base`, 0.01 USDC per call (asset 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913), paid to 0x88a694d3466946fb6d3e88e4f72162cb9252acc0. - Sign the payment with your wallet and repeat the same call with it, base64 encoded, in the `X-PAYMENT` header. The result comes back with an `X-PAYMENT-RESPONSE` header holding the settlement transaction. - x402 v2 clients work too: the requirements are also in the `PAYMENT-REQUIRED` header (network `eip155:8453`), the payment goes in `PAYMENT-SIGNATURE`, and the settlement comes back in `PAYMENT-RESPONSE`. - Each payment buys exactly one call and is refused if presented again. It is settled only after the price is computed, so a failed call is never charged. - If settlement is refused (`payment_settlement_failed` with `retryable: true`), nothing was charged and the same payment may be presented again, up to 3 settlement attempts in all. - If the answer is `payment_settlement_unknown` (503, `retryable: false`), the payment may have been charged: do not sign a new payment for that call. Contact support@last-price.ai with the `payment_id` it carries. - Paid calls run on a shared pay-per-call workspace with the built-in and publicly listed functions. An API key works on the same endpoint instead. - [Give your agent a wallet](https://last-price.ai/docs/agent-wallets): For the person who runs the agent: creating, funding and capping a dedicated wallet, and the payment flow step by step. - Last Price's own x402 pays for compute. It is not a way to sign up. AgentMail's x402 gateway pays for AgentMail API calls, such as creating an inbox, without an AgentMail API key. It is not a sign-up path and does not sign you in to Last Price. AgentID sign-in needs an AgentMail API key with provider_connect permission, and an x402 call does not carry one. - A self-registered agent key can pay too, for instance once its daily compute limit is reached: send the same `POST /api/compute/price` or `POST /api/price-router` request with the key and a payment header. It runs now on the agent's own workspace at the same price and does not count against the limit. On any other plan a payment header next to a key is ignored. - Or prepay: `POST https://api.last-price.ai/api/billing/topup` with `{"amount":""}` (at least 10) and one x402 payment for exactly that amount credits your workspace balance, with a bonus on top-ups of 100 USDC or more. Compute then draws 0.008333 USDC a call from it instead of 0.01 per call (a batch on a workspace with balance billing on draws one call per item, all or nothing), and nothing is ever charged automatically (`GET /api/billing/balance` shows the balance). - Or buy a day pass with the same key: `POST https://api.last-price.ai/api/agents/allowance` with one x402 payment of 2.5 USDC adds 500 compute calls for 24 hours, used once the daily limit is reached. Without a payment it answers 402 with the requirements; `GET` the same path lists your passes and the calls left. It is refused (409 `sandbox_key_expiring`, nothing charged) when your key expires within 24 hours. A compute request sent with a payment header is paid per call even while a pass is live. Unused pass calls are forfeited when a person claims the workspace. Above the $1 default cap in x402 clients 2.23+; raise it with registerPolicy / max_amount for this payment. Quoting a price to someone else? Every priced answer carries `receipt.check_url`, a keyless page that confirms the price was computed on Last Price, when, and until when it holds, and invites the buyer to check it independently. Send it with the price: the buyer, or the buyer's agent, opens it with no account. It names no workspace, function or input. Quote expiry (per workspace): a priced answer may carry `valid_until` (RFC 3339). Quote or charge the price only before then and compute again after; pass it as `quote_valid_until` to `POST /api/price-router/verify` to be told `quote_expired`. See https://last-price.ai/documentation#pcn-quote-expiry. Negotiating? `POST /api/price-router` with `function_name` `lastprice/stopping-rule`, your `role` and the offers so far in `context.metadata.history` says whether one more round is worth its cost, with the best offer so far and whose economics force the stop. See https://last-price.ai/documentation#pcn-stopping-rule. The same decision has its own endpoint, `POST /api/negotiate/stop` (MCP tool `negotiate_stop`), taking those fields in `context` and `options.fairness_mode`, and `value_model` `{"type":"function","function_id":"..."}` lets a registered value estimator value the next round. Both are behind the `negotiate-stop` release flag: where it is off for your workspace the endpoint answers 404 `not_released` and a function value model answers 400. ## Get an API key with no human - `POST https://api.last-price.ai/api/agents/register` with `{"name":"your-system/role-name"}` (optional `contact_email`, `intended_use`). No credential needed. Returns `201` with a sandbox workspace, an API key shown once in `api_key.key`, and a `claim.claim_url`. - On Windows, `curl.exe` and PowerShell (`Invoke-RestMethod`, `Invoke-WebRequest`) use the Windows TLS stack. Inside a sandbox, such as the one Codex runs commands in, it can fail before connecting with `SEC_E_NO_CREDENTIALS (0x8009030E)` or "Authentication failed, see inner exception". That is local to the sandbox, and `--ssl-no-revoke` does not fix it: make the same call with Node (`fetch`) or Python, which bring their own TLS, or use the MCP server. If curl instead reports `CRYPT_E_REVOCATION_OFFLINE` or `CRYPT_E_NO_REVOCATION_CHECK` (a network that blocks certificate revocation checks), add `--ssl-no-revoke`. In Node: `node -e "fetch('https://api.last-price.ai/api/agents/register',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({name:'your-system/role-name'})}).then(r=>r.text()).then(console.log)"` - Send the key as `x-api-key`. It can compute prices with built-in functions (`POST /api/compute/price`, `POST /api/price-router`, `POST /api/price-router/verify`), read functions and routing policies, call `GET /api/me`, read its workspace notifications and alert settings, and read its own agent inbox (`GET /api/agents/{id}/inbox` with its own agent id). Scopes: `price:compute`, `pcn:function:read`, `pcn:routing:read`. Anything else answers 403 `sandbox_restricted` with `requires: "claimed_workspace"` and the claim step in `next` (see "Needs a claimed workspace" below). - An unclaimed workspace has no person in it, so its own agent acts as its owner for the workspace's notifications and alert settings: GET /api/workspaces/{workspaceId}/notifications, POST .../notifications/read, and GET or PATCH .../alert-preferences need no notifications:read or notifications:write scope from a sandbox key. They answer for the key's own workspace only; any other workspace id answers 404 and changes nothing. - Limits: 25 compute calls per day, 5 registrations per address per day, and the key expires after 30 days. Save the key as `LASTPRICE_API_KEY` (or in `~/.config/lastprice/api_key`) and look there before registering, so the next run reuses it. Several agents on one machine can share one key; reuse a saved key rather than registering again. Once a person claims one workspace registered from an address, that address may register 25 agents a day (at most 40 per network). A refused registration answers 429 with `next` steps. - Rotate the key yourself with `POST /api/api-keys/rotate` (the key in `x-api-key`): the new key keeps the same scopes and expiry, and the old one stops working at once. - The same key is an OAuth client: `client_id` is `api_key.key_prefix`, `client_secret` is the key, at `POST /api/oauth/token` with `grant_type=client_credentials`. - Or, if your OAuth client-credentials framework expects to register its own client, register one at `POST https://api.last-price.ai/api/oauth/register` (RFC 7591, `client_credentials` only, no authorization code flow) for the same sandbox; it returns `client_id` and `client_secret`, and `client_secret_expires_at` is the sandbox key expiry, which a claim lifts. Server metadata: `/.well-known/oauth-authorization-server`. Both routes stay available; use either. - Give `claim_url` to a person. When they sign in and claim it, the workspace joins their account and the sandbox limits lift. The link works once. - No person to claim it? Upgrade it yourself: top up at least 10 USDC (`POST /api/billing/topup` with `{"amount":"10"}` and one x402 payment; the amount stays your compute balance), then `POST /api/agents/upgrade` with the same key. The sandbox limits lift for good, the key stops expiring and holds every scope, and the workspace stays agent owned. `GET /api/agents/upgrade` shows how far you are. A person can still claim it later. - Lost the key of an upgraded workspace? `GET /api/agents/recover?workspace_id=&address=<0x wallet that paid a top-up>` returns a message; sign it with EIP-191 personal_sign within five minutes and `POST /api/agents/recover` with `{"message":"...","signature":"0x..."}`. Every old key is revoked and a new one is returned once. - Out of the sandbox, your agent sends mail from the inbox Last Price made for it: `POST /api/agents/{id}/inbox` with your own agent id, the same key and `{"to":["..."],"subject":"...","text":"..."}`. Up to 10 recipients a message and 20 messages an hour. - Need a workspace per helper? With the same key, `POST https://api.last-price.ai/api/agents/workspaces` with `{"name":"your-system/helper"}` creates a child agent workspace under yours: its own key (shown once) and claim link, counted against the same registration limits. `GET` the same path lists the workspaces under yours. MCP: `create_child_workspace`, `list_child_workspaces`. When a person claims your workspace, unclaimed children come with it and stay under it. Being switched on workspace by workspace: until then it answers 404 `not_released`. ## Needs a claimed workspace Rosetta, UCP checkout and quotes, the commerce control plane, usage reads and outcomes, and receipts need a claimed workspace: a self-registered sandbox key gets 403 sandbox_restricted (requires: claimed_workspace) on each of them until a person claims the workspace. The claim must send keep_agent_key: true for the same key to keep working afterwards; without it the claim revokes the agent and its key. With no person: once the workspace holds at least 10 USDC of prepaid top-ups (POST /api/billing/topup with one x402 payment), POST /api/agents/upgrade with the same key lifts every one of these limits for good. The key stops expiring and keeps working, and the workspace stays agent owned; a person can still claim it later. - Rosetta schema translation: `POST /api/rosetta/ingest`, `POST /api/rosetta/plan`, `POST /api/rosetta/translate`, `POST /api/rosetta/freeze`, `POST /api/rosetta/normalize`, `GET /api/rosetta/review`, `POST /api/rosetta/review`. - UCP checkout sessions and quotes: `POST /api/ucp/checkout-sessions`, `GET /api/ucp/checkout-sessions`, `GET /api/ucp/checkout-sessions/{id}`, `PUT /api/ucp/checkout-sessions/{id}`, `POST /api/ucp/checkout-sessions/{id}/complete`, `POST /api/ucp/checkout-sessions/{id}/cancel`, `POST /api/ucp/quote`. - Commerce control plane: `GET /api/commerce/connectors`, `POST /api/commerce/connectors`, `PATCH /api/commerce/connectors/{id}`, `POST /api/commerce/connectors/{id}/sync`, `POST /api/commerce/connectors/{id}/check`, `POST /api/commerce/connectors/{id}/orders/sync`, `GET /api/commerce/catalog`, `GET /api/commerce/observations`, `POST /api/commerce/observations`, `DELETE /api/commerce/observations/{id}`, `GET /api/commerce/policies`, `POST /api/commerce/policies`, `GET /api/commerce/policies/{id}`, `PATCH /api/commerce/policies/{id}`, `DELETE /api/commerce/policies/{id}`, `POST /api/commerce/policies/{id}/evaluate`, `POST /api/commerce/cycle`, `GET /api/commerce/proposals`, `POST /api/commerce/proposals/{id}/approve`, `POST /api/commerce/proposals/{id}/reject`, `POST /api/commerce/execution`, `GET /api/commerce/audit`, `POST /api/commerce/seed-sample`. - Usage reads and outcomes: `GET /api/usage`, `GET /api/usage/events`, `GET /api/usage/breakdown`, `GET /api/usage/llm`, `GET /api/usage/llm/events`, `GET /api/usage/signals`, `PATCH /api/usage/events/{id}/outcome`. - Receipts: `GET /api/receipts`, `GET /api/receipts/{id}`. ## Translate your own JSON (Rosetta) Rosetta translates a merchant's or vendor's own JSON into Last Price's canonical records (product, offer, observation, match, action) and back. Most callers need only POST /api/rosetta/ingest: it fingerprints the payload, provisions and freezes an adapter on first sight, and reuses it afterwards. Guide: https://last-price.ai/product/rosetta. Reference: https://last-price.ai/api-docs#/Rosetta. - Start with `POST https://api.last-price.ai/api/rosetta/ingest` and `{"canonical_target":"offer","payload":{"sku":"A-100","price":"49.00","currency":"USD"}}`. A known shape answers `status: stable`; a new one answers `auto_provisioned`, `provisional` (queued for review) or 202 `needs_review`. Poll `GET /api/rosetta/review` or subscribe to the `rosetta.adapter.review_resolved` webhook. - The single steps: `POST /api/rosetta/plan` (propose a mapping with per-field confidence), `POST /api/rosetta/translate` (plan, translate and validate one record against a vendor contract), `POST /api/rosetta/freeze` (make a plan a deterministic adapter), `POST /api/rosetta/normalize` (map a vendor response back), `GET` and `POST /api/rosetta/review` (list or decide queued plans). - Public, no credential: `GET /api/rosetta/health`, `GET /api/rosetta/canonical-schemas`. - Needs a claimed workspace: `POST /api/rosetta/ingest`, `POST /api/rosetta/plan`, `POST /api/rosetta/translate`, `POST /api/rosetta/freeze`, `POST /api/rosetta/normalize`, `GET /api/rosetta/review`, `POST /api/rosetta/review`. A self-registered sandbox key gets 403 sandbox_restricted (requires: claimed_workspace) on every one of them until a person claims the workspace. The claim must send keep_agent_key: true for the same key to keep working afterwards; without it the claim revokes the agent and its key. - Scopes: These operations name no scope. They take a workspace API key not bound to an agent and created without scopes or with *, or a person's sign-in (a dashboard session, or the token from POST /api/auth/native-token). A key limited to named scopes, or any agent credential, gets 403 insufficient_scope. ## Being attributed Send a descriptive `User-Agent` on every call, such as `your-system/role-name` or `YourAgent/1.0`. The workspace's live traffic view names each request by it. - With an API key, a request counts as the workspace's own. Several agents can share one workspace key and tell themselves apart by User-Agent. - An agent-bound key (`POST /api/agents`, then `POST /api/agents/{id}/keys`) is optional. It adds the agent's name, per-agent scopes and revocation. - Keyless calls (the demo and MCP without a key) never count as a workspace's own traffic, whatever User-Agent they send. ## Keys for a signed-in account - To compute, a key needs the `price:compute` scope. Pick it in the Settings API key dialog at https://app.last-price.ai/settings/api-keys. - A legacy `write` or `admin` key still authenticates `GET /api/me`, but `POST /api/compute/price` answers 403 `insufficient_scope`. Create a new key with `price:compute`. - Creating an agent and its key needs a person's credential: a dashboard session or a JWT not bound to an agent. An API key cannot do it and gets 403 `wrong_auth_modality`. A JWT bound to an agent gets 403. - Holding a Supabase session but no API key? Make three calls. 1) `POST /api/auth/native-token` with the Supabase access token as `Authorization: Bearer`; it returns a one-hour Last Price JWT in `access_token`. 2) `POST /api/agents` with that JWT as `Authorization: Bearer` and `{"name":"your-system/role-name","scopes":["price:compute"]}`; the agent id is in `data.agent.id`. 3) `POST /api/agents/{id}/keys` with the same JWT and `{"name":"compute","scopes":["price:compute"]}`. The key is shown once in `data.api_key.key`; send it as `x-api-key`. - The one exception: the owner agent of a workspace it upgraded itself (`POST /api/agents/upgrade`) and nobody claimed makes those calls with its own `*` key or token, to run helper agents with their own keys. It cannot revoke or pause itself. ## Start here - [Agent signup guide](https://last-price.ai/agent-sign-in): Register with one call and no human, or sign in with AgentID and an inbox you control. - [Signup](https://app.last-price.ai/sign-up): AgentID, email and Google sign-in on the production app. - [Agent manifest](https://api.last-price.ai/.well-known/agents.json): Registration, supported authentication, scopes and rate limits. - [A2A agent card](https://api.last-price.ai/.well-known/agent.json): The skills (compute a price, verify a price, record an outcome) in the Agent2Agent card shape, also at /.well-known/agent-card.json. Each skill is a plain HTTP operation; there is no A2A task endpoint. - [OpenAPI contract](https://api.last-price.ai/api/openapi): Current API operations and response schemas. - [API reference](https://last-price.ai/api-docs): Human-readable contract. - [Developer guide](https://last-price.ai/documentation): Worked examples for functions, compute, routing, experiments, usage and webhooks. Where it and this file differ, this file is current. - [Pricing](https://last-price.ai/pricing): Product pricing information. ## Changes Check at the start of a session and before changing integration code. - JSON Feed: https://last-price.ai/changelog/feed.json. Keep the items where `_lastprice.audience` includes `agents`. - The same feed as plain `application/json`, for a client that refuses the feed media type: https://last-price.ai/changelog/feed - One feature only (for example billing, webhooks, mcp): https://last-price.ai/changelog/features/{feature}/feed.json. RSS works the same with feed.xml. - RSS: https://last-price.ai/changelog/feed.xml - Page: https://last-price.ai/changelog A browser sign-in is not an API credential. Keep keys private. Use x-api-key for API keys and GET /api/me to discover the credential's workspace. Account restrictions and scope checks apply. Provider directory listing is separate from this site's discovery documents. In the OpenAPI contract, `security: []` does not mean open. Each such operation carries `x-lastprice-auth`: `public` needs no credential, and `session-cookie` works only from a signed-in dashboard browser and answers 403 `wrong_auth_modality` to an API key and 401 to a JWT. Deleting a workspace and the workspace LLM key need a person signed in to the dashboard, and no API key or OAuth token reaches them. Workspace settings take an API key holding workspace:settings:read or workspace:settings:write (MCP tools get_workspace_settings and update_workspace_settings), never the LLM key or other credentials. Creating a workspace (POST /api/workspaces, MCP tool create_workspace) takes the dashboard session, or, where workspace administration by key is released for the workspace, an API key holding the exact workspace:admin scope, which only a workspace owner or admin can mint, acting for the person who minted it. Team administration (members, roles, invitations) works from the dashboard session or from an API key holding the exact team:admin scope, which only a workspace owner or admin can mint, from the dashboard; the next paragraph has its rules. An agent acting for an owner can read its own workspace with GET /api/me, and claim an agent workspace with a key holding workspace:claim. Team administration (members, roles, invitations) also takes an API key holding team:admin by name, sent as x-api-key, acting for the owner or admin who created it in the dashboard. It works only in the key's own workspace and only while that person is still an owner or admin there; it never grants the owner role or a role above theirs, never changes the owner or that person, and only an owner's key can demote or remove an admin. Nobody, an owner included, can demote or remove the workspace owner of record or leave the workspace without an owner, and a change that collides with a concurrent one answers 409 with retryable true. An invitation it sends stays acceptable only while the key and that person still carry that authority. Agent tokens are refused there, and every call, refused ones included, lands in GET /api/audit, readable by owners and admins. Workspace settings and creating or deleting workspaces stay dashboard only. ## When a call fails Every error body keeps its `error` field and any `code` it already had. Optional top-level fields, beside `error`, say what to do next: `hint` (one sentence), `next` (calls that get you unstuck, as a list of `{method, path, description}` steps, with an `id` where a body lists steps you must tell apart), `example` (a minimal valid body), `issues` (each failing field as `{path, message}`), `retry_after` (seconds, equal to the `Retry-After` header) and `limit` (requests per window). - 401: `hint` names the accepted credentials (a JWT as `Authorization: Bearer`, an API key as `x-api-key`) and `next` points at `POST /api/agents/register` (no credential needed) and `POST /api/oauth/token`. - 403 `wrong_auth_modality`: the API key was accepted, but this route never takes one. Routes that take only a person's credential (agent management, agent keys, approval decisions) and any route that needs a signed-in person in the dashboard (for example the workspace LLM key, your profile and sessions, accepting an invitation) answer an API key this way, with a `hint` naming the credential the route takes and an empty `next`: no new key would help. - 400: `validation_failed` lists `issues` and, on the main operations, an `example`. - 400 `invalid_json`: the body did not parse. Sent by `PUT /api/agent-protocol`, `POST /api/agents/workspaces`, `POST /api/api-keys`, `PUT /api/channel-rates`, `POST /api/commerce/connectors`, `PATCH /api/commerce/connectors/{id}`, `POST /api/commerce/cycle`, `POST /api/compute/allocation`, `POST /api/compute/batch`, `POST /api/compute/conversation`, `POST /api/compute/price`, `POST /api/compute/significance`, `POST /api/costs`, `POST /api/credit-bundle-plans`, `PATCH /api/credit-bundle-plans/{planId}`, `POST /api/credit-bundle-plans/{planId}/grant`, `POST /api/credits`, `POST /api/customers`, `POST /api/customers/{customerId}/notes`, `PATCH /api/customers/{customerId}/notes/{noteId}`, `POST /api/cut-advisor`, `POST /api/decisions/quote-reply`, `POST /api/disputes`, `POST /api/embed-tokens`, `POST /api/experiments/{experimentId}/outcome`, `POST /api/experiments/{experimentId}/promote`, `POST /api/forge/candidates/{id}/promote`, `POST /api/forge/candidates/{id}/reject`, `POST /api/forge/candidates/{id}/retire`, `POST /api/functions`, `PATCH /api/functions/{id}`, `POST /api/handover/businesses`, `PATCH /api/handover/businesses/{id}`, `POST /api/handover/public/{slug}/orders`, `POST /api/handover/sheet`, `POST /api/hosted-models`, `PATCH /api/hosted-models/{modelId}`, `POST /api/hosted-models/{modelId}/predict`, `POST /api/hosted-models/{modelId}/promote`, `POST /api/hosted-models/{modelId}/train`, `POST /api/hosted-models/{modelId}/versions`, `PUT /api/instrumentation/setup/{kind}`, `POST /api/instrumentation/setup/{kind}/provision`, `POST /api/invoices`, `POST /api/jale/contribute`, `POST /api/jale/contribute/batch`, `PUT /api/learned-elasticity`, `PUT /api/learned-elasticity/exploration`, `PUT /api/learned-elasticity/buyer-models`, `PUT /api/learned-elasticity/feature-contract`, `POST /api/learned-elasticity/feature-contract/infer`, `PUT /api/live-tags/sessions/{id}`, `POST /api/live-tags/sessions/{id}/uploads`, `POST /api/negotiate/stop`, `POST /api/negotiation/preview`, `PUT /api/negotiation/products`, `POST /api/negotiation/public/{handle}/offers`, `PUT /api/negotiation/settings`, `POST /api/marketplace/listings`, `PATCH /api/marketplace/listings/{listingId}`, `POST /api/monetization/scaffold`, `POST /api/monetization/scaffold/pull-request`, `POST /api/orders`, `POST /api/partner/workspaces`, `POST /api/payments`, `POST /api/payments/{paymentId}/refund`, `POST /api/payouts/connect`, `POST /api/price-router`, `POST /api/price-router/chain`, `POST /api/price-router/checks/{id}/outcome`, `POST /api/price-router/identify`, `POST /api/price-router/pipelines`, `POST /api/price-router/tag`, `POST /api/price-router/verify`, `POST /api/pricing-analyst/ask`, `POST /api/public/market-prices`, `POST /api/public/product-prices`, `POST /api/pricing-models`, `POST /api/pricing/preview`, `POST /api/problem-reports`, `PUT /api/price-guardrails`, `PUT /api/pricing-analyst/settings`, `PUT /api/product-categories`, `POST /api/public/demos/{slug}/assign`, `POST /api/public/demos/{slug}/convert`, `POST /api/routing-policies`, `PATCH /api/routing-policies/{id}`, `PATCH /api/sales-playbook`, `POST /api/scrape-jobs`, `POST /api/scrape-jobs/preview`, `PATCH /api/scrape-jobs/{jobId}`, `POST /api/storefronts`, `POST /api/storefronts/domain-search`, `PUT /api/storefronts/{storefrontId}`, `POST /api/storefronts/{storefrontId}/domain-quotes`, `POST /api/storefronts/{storefrontId}/domain-quotes/{quoteId}/confirm`, `POST /api/storefronts/{storefrontId}/domains`, `POST /api/storefronts/{storefrontId}/domains/{domainId}/dns-records`, `POST /api/ucp/checkout-sessions`, `PUT /api/ucp/checkout-sessions/{id}`, `POST /api/ucp/quote`, `PATCH /api/usage/events/{id}/outcome`, `PATCH /api/usage/llm/events/{id}/outcome`, `POST /api/tax/calculate`, `POST /api/user/security-events`, `PATCH /api/user/settings`, `POST /api/webhooks`, `PATCH /api/webhooks/{webhookId}`, `POST /api/workspaces/{workspaceId}/notifications/read`, `POST /api/workspaces/{workspaceId}/notifications/archive`, `POST /api/workspaces/{workspaceId}/notifications/unarchive`, `PATCH /api/workspaces/{workspaceId}/alert-preferences`. Elsewhere such a body can answer with another code, with only `error`, or, on some older routes, a 500. - 403 `insufficient_scope`: `required_scopes` lists what is missing and `hint` says how to get a key that carries it. - 403 `sandbox_restricted`: a self-registered sandbox key called an operation its plan does not allow. `requires` is `claimed_workspace`, `allowed_operations` lists what the key can call, and the `claim` step in `next` says how a person claims the workspace (with `keep_agent_key: true`, so this key keeps working). - 429: wait `retry_after` seconds, then retry. A 429 `quota_exceeded` is a daily limit: it resets after `retry_after` seconds, and `next` lists the ways past it sooner. Where the call can be paid for, a step with `id` `pay_per_call` says how to send it again with an x402 payment (its `header`, `price`, `asset`, `network` and `pay_to`). On a daily compute limit, a step with `id` `day_pass` says how to buy a day pass of extra compute calls (its `calls`, `valid_hours`, `header`, `price`, `asset` and `network`); after buying one, send the refused request again. A step with `id` `claim` says how a person lifts the limit for good.