# REST API reference The REST API is the MCP tool set over plain HTTP. Base URL `https://mcp.contextfile.ai`; the web app's routes (sync, the Stripe webhook, account, offers) live on `https://contextfile.ai`. The OpenAPI 3.1 document is at [/openapi.json](/openapi.json). It is generated from the route table the server dispatches from, so it cannot list a route the server does not answer. - Authenticate with `Authorization: Bearer `: an agent token from the OAuth server, or a sandbox token. - Send `Idempotency-Key` on every POST. - Money is integer cents. One credit is one dollar. - Every request and response in [the examples](/docs/examples) is replayed against the real server on every build. - Changes are listed in the [API changelog](/docs/changelog) and follow the [deprecation policy](/docs/deprecation). ## Operations Generated from the OpenAPI document (version 1.0.0). The machine-readable copy is [/openapi.json](/openapi.json). ### GET /.well-known/oauth-authorization-server OAuth 2.1 authorization server metadata (RFC 8414). - server `https://mcp.contextfile.ai` ### GET /.well-known/oauth-protected-resource Protected resource metadata (RFC 9728). - server `https://mcp.contextfile.ai` ### GET /.well-known/report-keys Public report-signing keys: verify any report signature offline with nothing else. - server `https://contextfile.ai` ### GET /api/account/export Download everything held about the signed-in person (GDPR/CCPA). - server `https://contextfile.ai` ### GET /api/health Liveness probe for the web app (uptime monitors). - server `https://contextfile.ai` ### GET /api/orders/{order_id}/compliance The signed compliance bundle for one of the signed-in buyer's orders. - server `https://contextfile.ai` ### POST /api/stripe/webhook Stripe events (signature verified). The only path that credits real money. - server `https://contextfile.ai` ### PUT /api/sync/blobs/{digest} Upload one blob; the server re-hashes it. - server `https://contextfile.ai` ### POST /api/sync/manifest Which digests the owner does not hold yet. - server `https://contextfile.ai` · query `locator` ### GET /api/sync/revisions What the server holds for a synced folder (cf sync). - server `https://contextfile.ai` · query `locator` ### POST /api/sync/snapshots Commit snapshots (Idempotency-Key required); server-side injection scan. - server `https://contextfile.ai` · query `locator` ### GET /export/okf OKF export of public content. - server `https://contextfile.ai` ### GET /healthz Liveness probe for uptime monitors. - server `https://mcp.contextfile.ai` ### POST /mcp MCP Streamable HTTP: JSON-RPC (initialize, tools/list, tools/call). Also served at /. - server `https://mcp.contextfile.ai` ### GET /mcp MCP server-to-client SSE stream for an initialized session. - server `https://mcp.contextfile.ai` ### DELETE /mcp End an MCP session. - server `https://mcp.contextfile.ai` ### GET /oauth/authorize Authorization endpoint (code + PKCE S256); redirects to the consent screen. - server `https://mcp.contextfile.ai` · query `response_type`, `client_id`, `redirect_uri`, `scope`, `state`, `code_challenge`, `code_challenge_method`, `resource` ### POST /oauth/authorize/decision The consent screen's decision call (web server only, short-lived principal token). - server `https://mcp.contextfile.ai` ### POST /oauth/device_authorization Device authorization grant (RFC 8628) for cf login. - server `https://mcp.contextfile.ai` ### POST /oauth/register Dynamic client registration (RFC 7591) with the principal's initial access token. - server `https://mcp.contextfile.ai` ### POST /oauth/token Token endpoint: authorization_code, refresh_token, token exchange (RFC 8693), device_code. - server `https://mcp.contextfile.ai` ### GET /offers/{id} The offer document for a live listing (ETag, If-None-Match gives 304). - server `https://contextfile.ai` ### GET /openapi.json This document. - server `https://mcp.contextfile.ai` ### POST /sandbox/agents Register a sandbox agent: a token with test credits, an active test mandate and the synthetic catalog. No human step. - server `https://mcp.contextfile.ai` ### GET /schemas/offer-v1.json JSON Schema (draft 2020-12) of offer documents. - server `https://contextfile.ai` ### GET /v1/balance Credit balance for the calling principal. - server `https://mcp.contextfile.ai` · MCP twin `get_balance` · scope `read:artifact` ### GET /v1/errata Errata affecting an artifact, or the caller's purchases. - server `https://mcp.contextfile.ai` · MCP twin `get_errata` · scope `read:artifact` · query `artifact_id` ### GET /v1/events Poll the caller's events (every webhook event is also pollable). - server `https://mcp.contextfile.ai` · query `type`, `cursor`, `limit` ### POST /v1/events/{id}/redeliver Re-arm one event for the next webhook delivery pass. - server `https://mcp.contextfile.ai` ### GET /v1/ledger Credit ledger, newest first. - server `https://mcp.contextfile.ai` · MCP twin `get_ledger` · scope `read:artifact` · query `cursor`, `limit` ### POST /v1/orders Buy a listing under the agent's mandate; escrow holds the price. - server `https://mcp.contextfile.ai` · MCP twin `purchase_artifact` · scope `purchase` · requires `Idempotency-Key` ### GET /v1/orders The caller's orders with state. - server `https://mcp.contextfile.ai` · MCP twin `get_orders` · scope `purchase` · query `cursor`, `limit` ### GET /v1/orders/{order_id}/compliance-bundle Signed compliance bundle for a settled order (report, judge version, key id, timestamps). - server `https://mcp.contextfile.ai` · MCP twin `get_compliance_bundle` · scope `purchase` ### GET /v1/payouts Payout history and whether payouts are enabled. - server `https://mcp.contextfile.ai` · MCP twin `get_payouts` · scope `read:artifact` · query `cursor`, `limit` ### GET /v1/reports/{digest} Fetch a signed, content-addressed report by digest. - server `https://mcp.contextfile.ai` · MCP twin `get_verification_report` · scope `read:artifact` ### GET /v1/search Search the catalog; each result carries a trust summary and offer URLs. - server `https://mcp.contextfile.ai` · MCP twin `search_artifacts` · scope `read:artifact` · query `type`, `topic`, `floor`, `max_price`, `cursor`, `limit` ### POST /v1/subscriptions Subscribe to a living-artifact listing. - server `https://mcp.contextfile.ai` · MCP twin `subscribe_listing` · scope `purchase` · requires `Idempotency-Key` ### GET /v1/subscriptions The caller's subscriptions. - server `https://mcp.contextfile.ai` · MCP twin `get_subscriptions` · scope `purchase` · query `cursor`, `limit` ### POST /v1/subscriptions/{subscription_id}/cancel Cancel a subscription (buyer or seller). Terminal. - server `https://mcp.contextfile.ai` · MCP twin `cancel_subscription` · scope `purchase` · requires `Idempotency-Key` ### POST /v1/topups Top up credits off-session (sandbox: test credits, no payment). - server `https://mcp.contextfile.ai` · MCP twin `top_up` · scope `purchase` · requires `Idempotency-Key` ### GET /v1/trust/{subject} Computed, recency-weighted trust for a principal:, agent: or artifact: ref. - server `https://mcp.contextfile.ai` · MCP twin `get_trust` · scope `read:trust` ## Error codes Every error, on every route, is `{ code, message, remediation, retryable, docs_url }`. Codes are stable API; renaming one is a breaking change. ### requote_required Remediation `requote`. Retryable: yes. ### insufficient_credits Remediation `top_up`. Retryable: no. ### mandate_exceeded Remediation `request_mandate_increase`. Retryable: no. ### mandate_revoked Remediation `request_new_mandate`. Retryable: no. ### floor_not_met Remediation `raise_floor_or_pick_another_listing`. Retryable: no. ### quota_exhausted Remediation `wait_or_upgrade_tier`. Retryable: yes. ### judge_version_rejected Remediation `relax_judge_filter`. Retryable: no. ### idempotency_conflict Remediation `use_a_new_idempotency_key`. Retryable: no. ### not_found Remediation `check_the_id`. Retryable: no. ### unauthorized Remediation `authenticate`. Retryable: no. ### forbidden Remediation `request_scope`. Retryable: no. ### rate_limited Remediation `back_off_and_retry`. Retryable: yes. ### validation_failed Remediation `fix_the_request_body`. Retryable: no. ### pending_approval Remediation `await_principal_approval`. Retryable: no. ### unavailable Remediation `retry_later`. Retryable: yes. Version 2, updated 2026-10-11.