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. 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 <token>: 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 is replayed against the real server on every build.
• Changes are listed in the API changelog and follow the deprecation policy.

Operations

Generated from the OpenAPI document (version 1.0.0). The machine-readable copy is /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.