{ "openapi": "3.1.0", "info": { "title": "ContextFile API", "version": "1.0.0", "summary": "Verified artifacts with signed reports, a computed trust graph, and escrowed purchases for agents.", "description": "Every REST route under /v1 is the twin of an MCP tool and runs the same pipeline: scope, input schema, Idempotency-Key on mutating calls, handler. Errors are always { code, message, remediation, retryable, docs_url }. The sandbox (POST /sandbox/agents) answers every route with test credits and a synthetic corpus. Changelog: https://contextfile.ai/docs/changelog. Deprecation policy: https://contextfile.ai/docs/deprecation.", "x-changelog": [ { "version": "1.0.0", "date": "2026-10-11", "changes": [ { "kind": "added", "text": "OpenAPI 3.1 document at /openapi.json, generated from the route and tool registries the servers dispatch from." }, { "kind": "added", "text": "Sandbox: POST /sandbox/agents issues a sandbox token with test credits; every /v1 route and the MCP endpoint answer it against the synthetic corpus." }, { "kind": "added", "text": "GET /v1/search, GET /v1/reports/{digest}, GET /v1/trust/{subject} and GET /v1/errata as REST twins of their MCP tools." }, { "kind": "added", "text": "GET /v1/orders/{order_id}/compliance-bundle: a signed bundle of the order, its report, the judge version and key id." }, { "kind": "added", "text": "Mandate judge filters: min_judge_version and reject_open_judge_errata, refused with judge_version_rejected." }, { "kind": "added", "text": "Offer documents carry the judge version and hash of the report they offer." }, { "kind": "added", "text": "GET /.well-known/report-keys on the web origin: the public report-signing key, for offline signature checks." }, { "kind": "changed", "text": "REST errors are always the typed error object { code, message, remediation, retryable, docs_url }, including authentication failures (previously wrapped in a JSON-RPC envelope)." } ] }, { "version": "0.9.0", "date": "2026-10-11", "changes": [ { "kind": "added", "text": "Commerce: POST /v1/orders, GET /v1/orders, subscriptions, POST /v1/topups, GET /v1/balance, GET /v1/ledger, GET /v1/payouts." }, { "kind": "added", "text": "Device sync under /api/sync/* for cf sync, and the OAuth device grant (/oauth/device_authorization) that issues its tokens." } ] }, { "version": "0.5.0", "date": "2026-07-18", "changes": [ { "kind": "added", "text": "Event outbox: GET /v1/events and POST /v1/events/{id}/redeliver; signed webhooks." }, { "kind": "added", "text": "OAuth 2.1 authorization server with dynamic client registration, PKCE and token exchange." } ] } ] }, "servers": [ { "url": "https://mcp.contextfile.ai", "description": "REST + MCP (production and sandbox tokens)" }, { "url": "https://contextfile.ai", "description": "Web app (sync, webhooks, account, offers)" } ], "paths": { "/v1/search": { "get": { "operationId": "search_artifacts", "summary": "Search the catalog; each result carries a trust summary and offer URLs.", "description": "Search the catalog; every result carries an inline trust summary and the offer document URL of each live listing, so no second call is needed.", "tags": [ "search" ], "security": [ { "agent": [ "read:artifact" ] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "topic", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "floor", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "max_price", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "x-mcp-tool": "search_artifacts", "x-scope": "read:artifact", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "search": { "summary": "Search the catalog by capability", "value": { "items": [ { "artifact": { "id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "type": "context_file", "contentHash": "sha256:9b1c4f0e2d8a7c6b5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a29", "manifest": { "title": "Vellmark CLAUDE.md (sandbox)" }, "ownerPrincipalId": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "sandbox": true, "createdAt": "2026-10-11T08:00:00.000Z" }, "trust": { "score": 0.5, "sampleSize": 0, "passRate": null }, "liveListingIds": [ "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f" ], "offers": [ { "listing_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "offer_url": "https://contextfile.ai/offers/3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f" } ] } ], "next_cursor": null } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/reports/{digest}": { "get": { "operationId": "get_verification_report", "summary": "Fetch a signed, content-addressed report by digest.", "description": "Fetch a signed, content-addressed report by digest.", "tags": [ "reports" ], "security": [ { "agent": [ "read:artifact" ] } ], "parameters": [ { "name": "digest", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-mcp-tool": "get_verification_report", "x-scope": "read:artifact", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "report": { "summary": "Fetch the signed report", "value": { "digest": "sha256:9b1c4f0e2d8a7c6b5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a29", "pipelineVersion": "sandbox-1", "claims": [ { "id": "vellmark-guide-c1", "text": "Vellmark's harbor office keeps a daily tide log.", "sourceId": "harbor", "locator": "passage-1", "entailment": 0.97, "state": "verified" } ], "summary": { "claimsTotal": 4, "verified": 4, "floor": 0.9, "meanEntailment": 0.965, "humanReviewed": false }, "judgeModel": "sandbox/synthetic-judge", "judgePromptVersion": "v0-dev", "judgePromptHash": "sha256:5d41402abc4b2a76b9719d911017c592ae2b5f3c6d7e8f9a0b1c2d3e4f5a6b7c", "signingKeyId": "dev-3a4b5c6d7e8f9a0b", "signature": "MEUCIQ...", "createdAt": "2026-10-11T08:00:00.000Z" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/trust/{subject}": { "get": { "operationId": "get_trust", "summary": "Computed, recency-weighted trust for a principal:, agent: or artifact: ref.", "description": "Computed, recency-weighted trust for a principal/agent/artifact ref.", "tags": [ "trust" ], "security": [ { "agent": [ "read:trust" ] } ], "parameters": [ { "name": "subject", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-mcp-tool": "get_trust", "x-scope": "read:trust", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "trust": { "summary": "Read the artifact's computed trust", "value": { "score": 0.5, "sampleSize": 0, "passRate": null } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/errata": { "get": { "operationId": "get_errata", "summary": "Errata affecting an artifact, or the caller's purchases.", "description": "Errata affecting an artifact or the caller's purchases.", "tags": [ "errata" ], "security": [ { "agent": [ "read:artifact" ] } ], "parameters": [ { "name": "artifact_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "x-mcp-tool": "get_errata", "x-scope": "read:artifact", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "errata": { "summary": "Check errata on the artifact", "value": { "items": [], "next_cursor": null } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orders": { "post": { "operationId": "purchase_artifact", "summary": "Buy a listing under the agent's mandate; escrow holds the price.", "description": "Purchase under a mandate (min_trust checked) -> escrow -> auto-refund on floor miss.", "tags": [ "orders" ], "security": [ { "agent": [ "purchase" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Required on every mutating call. A replay returns the stored result; the same key with a different body is idempotency_conflict." } ], "x-mcp-tool": "purchase_artifact", "x-scope": "purchase", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "purchase": { "summary": "Buy under the mandate; escrow holds the price", "value": { "order_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "state": "held", "escrow_cents": 300, "formats": [ "md" ], "poll": "get_orders or subscribe to order.state_changed" } }, "purchase-sabotaged": { "summary": "Buy the sabotaged edition", "value": { "order_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "state": "held", "escrow_cents": 200, "formats": [ "md" ], "poll": "get_orders or subscribe to order.state_changed" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "description": "Typed error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "mandate-exceeded": { "summary": "The mandate's per-item cap refuses the purchase", "value": { "code": "mandate_exceeded", "message": "price 300 exceeds per-item cap", "remediation": "request_mandate_increase", "retryable": false, "docs_url": "https://contextfile.ai/docs/api#mandate_exceeded" } }, "judge-version-rejected": { "summary": "The mandate's judge-version filter refuses the purchase", "value": { "code": "judge_version_rejected", "message": "report scored under judge v0-dev, below the mandate's min_judge_version v99", "remediation": "relax_judge_filter", "retryable": false, "docs_url": "https://contextfile.ai/docs/api#judge_version_rejected" } } } } } }, "404": { "description": "Typed error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "not-found": { "summary": "A listing on the other side of the sandbox line", "value": { "code": "not_found", "message": "listing 00000000-0000-4000-8000-000000000000 is not live", "remediation": "check_the_id", "retryable": false, "docs_url": "https://contextfile.ai/docs/api#not_found" } } } } } }, "409": { "description": "Typed error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "requote-required": { "summary": "The live price is above what you agreed", "value": { "code": "requote_required", "message": "price is 300 cents, above the agreed 100", "remediation": "requote", "retryable": true, "docs_url": "https://contextfile.ai/docs/api#requote_required" } } } } } }, "413": { "$ref": "#/components/responses/Error" }, "422": { "description": "Typed error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "missing-idempotency-key": { "summary": "A mutating call without an Idempotency-Key", "value": { "code": "validation_failed", "message": "mutating calls require an Idempotency-Key header", "remediation": "fix_the_request_body", "retryable": false, "docs_url": "https://contextfile.ai/docs/api#validation_failed" } }, "idempotency-conflict": { "summary": "The same key with a different body", "value": { "code": "idempotency_conflict", "message": "same key, different body", "remediation": "use_a_new_idempotency_key", "retryable": false, "docs_url": "https://contextfile.ai/docs/api#idempotency_conflict" } } } } } }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listing_id": { "type": "string" }, "formats": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "max_price_cents": { "type": "integer" } }, "required": [ "listing_id", "formats" ], "additionalProperties": false }, "examples": { "purchase": { "summary": "Buy under the mandate; escrow holds the price", "value": { "listing_id": "{{guide_listing}}", "formats": [ "md" ], "max_price_cents": 300 } }, "purchase-sabotaged": { "summary": "Buy the sabotaged edition", "value": { "listing_id": "{{sabotaged_listing}}", "formats": [ "md" ] } }, "requote-required": { "summary": "The live price is above what you agreed", "value": { "listing_id": "{{guide_listing}}", "formats": [ "md" ], "max_price_cents": 100 } }, "missing-idempotency-key": { "summary": "A mutating call without an Idempotency-Key", "value": { "listing_id": "{{guide_listing}}", "formats": [ "md" ] } }, "idempotency-conflict": { "summary": "The same key with a different body", "value": { "listing_id": "{{guide_listing}}", "formats": [ "pdf" ] } }, "not-found": { "summary": "A listing on the other side of the sandbox line", "value": { "listing_id": "00000000-0000-4000-8000-000000000000", "formats": [ "md" ] } }, "mandate-exceeded": { "summary": "The mandate's per-item cap refuses the purchase", "value": { "listing_id": "{{guide_listing}}", "formats": [ "md" ] } }, "judge-version-rejected": { "summary": "The mandate's judge-version filter refuses the purchase", "value": { "listing_id": "{{guide_listing}}", "formats": [ "md" ] } } } } } } }, "get": { "operationId": "get_orders", "summary": "The caller's orders with state.", "description": "Orders for the caller, with state.", "tags": [ "orders" ], "security": [ { "agent": [ "purchase" ] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "x-mcp-tool": "get_orders", "x-scope": "purchase", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "order-released": { "summary": "Poll the order: the report met the floor, escrow released", "value": { "items": [ { "id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "listingId": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "buyerPrincipalId": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "buyerAgentId": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "subscriptionId": null, "state": "released", "escrowCents": 300, "formats": [ "md" ], "idempotencyKey": "agent:3f2a9c1e:order-1", "priceSnapshotId": null, "runId": null, "sandbox": true, "createdAt": "2026-10-11T09:00:00.000Z", "updatedAt": "2026-10-11T09:00:05.000Z" } ], "next_cursor": null } }, "order-refunded": { "summary": "Poll again: the edition missed its floor and escrow refunded itself", "value": { "items": [ { "id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "listingId": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "buyerPrincipalId": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "buyerAgentId": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "subscriptionId": null, "state": "auto_refunded", "escrowCents": 300, "formats": [ "md" ], "idempotencyKey": "agent:3f2a9c1e:order-1", "priceSnapshotId": null, "runId": null, "sandbox": true, "createdAt": "2026-10-11T09:00:00.000Z", "updatedAt": "2026-10-11T09:00:05.000Z" }, { "id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "listingId": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "buyerPrincipalId": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "buyerAgentId": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "subscriptionId": null, "state": "released", "escrowCents": 300, "formats": [ "md" ], "idempotencyKey": "agent:3f2a9c1e:order-1", "priceSnapshotId": null, "runId": null, "sandbox": true, "createdAt": "2026-10-11T09:00:00.000Z", "updatedAt": "2026-10-11T09:00:05.000Z" } ], "next_cursor": null } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/orders/{order_id}/compliance-bundle": { "get": { "operationId": "get_compliance_bundle", "summary": "Signed compliance bundle for a settled order (report, judge version, key id, timestamps).", "description": "Signed compliance export for an order (report + judge version + key id + timestamps).", "tags": [ "orders" ], "security": [ { "agent": [ "purchase" ] } ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-mcp-tool": "get_compliance_bundle", "x-scope": "purchase", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "compliance-bundle": { "summary": "Download the signed compliance bundle", "value": { "digest": "sha256:9b1c4f0e2d8a7c6b5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a29", "body": { "bundle_version": "compliance-bundle/1", "order": { "id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "listing_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "state": "released", "escrow_cents": 300, "formats": [ "md" ], "sandbox": true, "created_at": "2026-10-11T09:00:00.000Z", "updated_at": "2026-10-11T09:00:05.000Z" }, "report": { "digest": "sha256:9b1c4f0e2d8a7c6b5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a29", "url": "https://aisourceoftruth.com/r/sha256%3A9b1c", "pipeline_version": "sandbox-1", "created_at": "2026-10-11T08:00:00.000Z", "signing_key_id": "dev-3a4b5c6d7e8f9a0b", "signature": "MEUCIQ..." }, "judge": { "model": "sandbox/synthetic-judge", "prompt_version": "v0-dev", "prompt_hash": "sha256:5d41402abc4b2a76b9719d911017c592ae2b5f3c6d7e8f9a0b1c2d3e4f5a6b7c" }, "outcome": { "kind": "cleared_escrow", "recorded_at": "2026-10-11T09:00:05.000Z" }, "issued_at": "2026-10-11T09:01:00.000Z" }, "signature": { "keyId": "dev-3a4b5c6d7e8f9a0b", "alg": "ES256", "value": "MEUCIQ..." } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/subscriptions": { "post": { "operationId": "subscribe_listing", "summary": "Subscribe to a living-artifact listing.", "description": "Subscribe to a living-artifact listing (offer billing != null). Each cycle is a normal escrowed purchase; a failed cycle never bills; 3 consecutive failures auto-pause. Subscribing again resumes a paused subscription.", "tags": [ "subscriptions" ], "security": [ { "agent": [ "purchase" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Required on every mutating call. A replay returns the stored result; the same key with a different body is idempotency_conflict." } ], "x-mcp-tool": "subscribe_listing", "x-scope": "purchase", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "listing_id": { "type": "string" } }, "required": [ "listing_id" ], "additionalProperties": false } } } } }, "get": { "operationId": "get_subscriptions", "summary": "The caller's subscriptions.", "description": "The caller's subscriptions with state (active | paused | canceled), billing, failure count and next cycle.", "tags": [ "subscriptions" ], "security": [ { "agent": [ "purchase" ] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "x-mcp-tool": "get_subscriptions", "x-scope": "purchase", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/subscriptions/{subscription_id}/cancel": { "post": { "operationId": "cancel_subscription", "summary": "Cancel a subscription (buyer or seller). Terminal.", "description": "Cancel a subscription (buyer or seller). Terminal.", "tags": [ "subscriptions" ], "security": [ { "agent": [ "purchase" ] } ], "parameters": [ { "name": "subscription_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Required on every mutating call. A replay returns the stored result; the same key with a different body is idempotency_conflict." } ], "x-mcp-tool": "cancel_subscription", "x-scope": "purchase", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false } } } } } }, "/v1/topups": { "post": { "operationId": "top_up", "summary": "Top up credits off-session (sandbox: test credits, no payment).", "description": "Top up credits off-session with the card the principal saved at Checkout (Stripe PaymentIntent). Credits land when Stripe confirms; watch topup.credited.", "tags": [ "topups" ], "security": [ { "agent": [ "purchase" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Required on every mutating call. A replay returns the stored result; the same key with a different body is idempotency_conflict." } ], "x-mcp-tool": "top_up", "x-scope": "purchase", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "topup": { "summary": "Top up (sandbox: test credits, no payment taken)", "value": { "status": "credited", "amount_cents": 500, "sandbox": true } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credits": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "credits" ], "additionalProperties": false }, "examples": { "topup": { "summary": "Top up (sandbox: test credits, no payment taken)", "value": { "credits": 5 } } } } } } } }, "/v1/balance": { "get": { "operationId": "get_balance", "summary": "Credit balance for the calling principal.", "description": "Credit balance for the calling principal.", "tags": [ "balance" ], "security": [ { "agent": [ "read:artifact" ] } ], "parameters": [], "x-mcp-tool": "get_balance", "x-scope": "read:artifact", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "balance": { "summary": "Check the balance", "value": { "balance_cents": 10000, "currency": "credit" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "description": "Typed error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthorized": { "summary": "No bearer token", "value": { "code": "unauthorized", "message": "missing Bearer token", "remediation": "authenticate", "retryable": false, "docs_url": "https://contextfile.ai/docs/api#unauthorized" } } } } } }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/ledger": { "get": { "operationId": "get_ledger", "summary": "Credit ledger, newest first.", "description": "Credit ledger, cursor-paginated; each debit links to its run.", "tags": [ "ledger" ], "security": [ { "agent": [ "read:artifact" ] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "x-mcp-tool": "get_ledger", "x-scope": "read:artifact", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/payouts": { "get": { "operationId": "get_payouts", "summary": "Payout history and whether payouts are enabled.", "description": "Payout history.", "tags": [ "payouts" ], "security": [ { "agent": [ "read:artifact" ] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "x-mcp-tool": "get_payouts", "x-scope": "read:artifact", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/healthz": { "get": { "operationId": "get_healthz", "summary": "Liveness probe for uptime monitors.", "tags": [ "operations" ], "security": [], "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/openapi.json": { "get": { "operationId": "get_openapi_json", "summary": "This document.", "tags": [ "operations" ], "security": [], "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/.well-known/oauth-authorization-server": { "get": { "operationId": "get_well_known_oauth_authorization_server", "summary": "OAuth 2.1 authorization server metadata (RFC 8414).", "tags": [ "oauth" ], "security": [], "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/.well-known/oauth-protected-resource": { "get": { "operationId": "get_well_known_oauth_protected_resource", "summary": "Protected resource metadata (RFC 9728).", "tags": [ "oauth" ], "security": [], "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/oauth/register": { "post": { "operationId": "post_oauth_register", "summary": "Dynamic client registration (RFC 7591) with the principal's initial access token.", "tags": [ "oauth" ], "security": [ { "session": [] } ], "parameters": [], "responses": { "201": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_name": { "type": "string" }, "redirect_uris": { "type": "array", "items": { "type": "string" } }, "grant_types": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "string" } }, "required": [] } } } } } }, "/oauth/authorize": { "get": { "operationId": "get_oauth_authorize", "summary": "Authorization endpoint (code + PKCE S256); redirects to the consent screen.", "tags": [ "oauth" ], "security": [], "parameters": [ { "name": "response_type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "code_challenge", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "code_challenge_method", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "resource", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/oauth/authorize/decision": { "post": { "operationId": "post_oauth_authorize_decision", "summary": "The consent screen's decision call (web server only, short-lived principal token).", "tags": [ "oauth" ], "security": [ { "session": [] } ], "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/oauth/device_authorization": { "post": { "operationId": "post_oauth_device_authorization", "summary": "Device authorization grant (RFC 8628) for cf login.", "tags": [ "oauth" ], "security": [], "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "scope": { "type": "string" } }, "required": [ "client_id" ] } } } } } }, "/oauth/token": { "post": { "operationId": "post_oauth_token", "summary": "Token endpoint: authorization_code, refresh_token, token exchange (RFC 8693), device_code.", "tags": [ "oauth" ], "security": [], "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string" } }, "required": [ "grant_type" ] } } } } } }, "/sandbox/agents": { "post": { "operationId": "post_sandbox_agents", "summary": "Register a sandbox agent: a token with test credits, an active test mandate and the synthetic catalog. No human step.", "tags": [ "sandbox" ], "security": [], "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "register": { "summary": "Register a sandbox agent (no human, test credits)", "value": { "access_token": "eyJhbGciOiJIUzI1NiJ9.example.signature", "token_type": "Bearer", "expires_in": 3600, "scope": "read:wiki read:artifact read:trust write:doc write:wiki build:image purchase delete", "sandbox": true, "principal_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "agent_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "mandate_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "credits_cents": 10000, "agent_name": "example-agent", "sandbox_catalog": { "vellmark-guide": { "listing_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "artifact_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "report_digest": "sha256:9b1c4f0e2d8a7c6b5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a29", "title": "Vellmark harbor guide (sandbox)", "price_cents": 300, "sabotaged": false }, "vellmark-context": { "listing_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "artifact_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "report_digest": "sha256:9b1c4f0e2d8a7c6b5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a29", "title": "Vellmark harbor guide (sandbox)", "price_cents": 150, "sabotaged": false }, "vellmark-sabotaged": { "listing_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "artifact_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "report_digest": "sha256:9b1c4f0e2d8a7c6b5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a29", "title": "Vellmark harbor guide (sandbox)", "price_cents": 200, "sabotaged": true } } } }, "register-low-cap": { "summary": "Register a second agent with a tight per-item cap", "value": { "access_token": "eyJhbGciOiJIUzI1NiJ9.example.signature", "token_type": "Bearer", "expires_in": 3600, "scope": "read:wiki read:artifact read:trust write:doc write:wiki build:image purchase delete", "sandbox": true, "principal_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "agent_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "mandate_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "credits_cents": 10000, "agent_name": "capped-agent", "sandbox_catalog": { "vellmark-guide": { "listing_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "artifact_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "report_digest": "sha256:9b1c4f0e2d8a7c6b5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a29", "title": "Vellmark harbor guide (sandbox)", "price_cents": 300, "sabotaged": false }, "vellmark-context": { "listing_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "artifact_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "report_digest": "sha256:9b1c4f0e2d8a7c6b5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a29", "title": "Vellmark harbor guide (sandbox)", "price_cents": 150, "sabotaged": false }, "vellmark-sabotaged": { "listing_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "artifact_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "report_digest": "sha256:9b1c4f0e2d8a7c6b5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a29", "title": "Vellmark harbor guide (sandbox)", "price_cents": 200, "sabotaged": true } } } }, "register-strict-judge": { "summary": "Register an agent that only buys reports scored under judge v99 or later", "value": { "access_token": "eyJhbGciOiJIUzI1NiJ9.example.signature", "token_type": "Bearer", "expires_in": 3600, "scope": "read:wiki read:artifact read:trust write:doc write:wiki build:image purchase delete", "sandbox": true, "principal_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "agent_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "mandate_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "credits_cents": 10000, "agent_name": "strict-agent", "sandbox_catalog": { "vellmark-guide": { "listing_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "artifact_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "report_digest": "sha256:9b1c4f0e2d8a7c6b5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a29", "title": "Vellmark harbor guide (sandbox)", "price_cents": 300, "sabotaged": false }, "vellmark-context": { "listing_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "artifact_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "report_digest": "sha256:9b1c4f0e2d8a7c6b5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a29", "title": "Vellmark harbor guide (sandbox)", "price_cents": 150, "sabotaged": false }, "vellmark-sabotaged": { "listing_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "artifact_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f", "report_digest": "sha256:9b1c4f0e2d8a7c6b5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a29", "title": "Vellmark harbor guide (sandbox)", "price_cents": 200, "sabotaged": true } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "purchasing": { "type": "object", "properties": { "per_item_max_cents": { "type": "integer", "exclusiveMinimum": 0 }, "min_trust": { "type": "number", "minimum": 0, "maximum": 1 }, "min_judge_version": { "type": "string", "pattern": "^v\\d+(?:[.-][0-9A-Za-z.-]+)?$" }, "reject_open_judge_errata": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false }, "examples": { "register": { "summary": "Register a sandbox agent (no human, test credits)", "value": { "name": "example-agent" } }, "register-low-cap": { "summary": "Register a second agent with a tight per-item cap", "value": { "name": "capped-agent", "purchasing": { "per_item_max_cents": 100 } } }, "register-strict-judge": { "summary": "Register an agent that only buys reports scored under judge v99 or later", "value": { "name": "strict-agent", "purchasing": { "min_judge_version": "v99" } } } } } } } } }, "/mcp": { "post": { "operationId": "post_mcp", "summary": "MCP Streamable HTTP: JSON-RPC (initialize, tools/list, tools/call). Also served at /.", "tags": [ "mcp" ], "security": [ { "agent": [] } ], "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "id": {}, "method": { "type": "string" }, "params": { "type": "object" } }, "required": [ "jsonrpc", "method" ] } } } } }, "get": { "operationId": "get_mcp", "summary": "MCP server-to-client SSE stream for an initialized session.", "tags": [ "mcp" ], "security": [ { "agent": [] } ], "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "delete_mcp", "summary": "End an MCP session.", "tags": [ "mcp" ], "security": [ { "agent": [] } ], "parameters": [], "responses": { "204": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/events": { "get": { "operationId": "get_v1_events", "summary": "Poll the caller's events (every webhook event is also pollable).", "tags": [ "events" ], "security": [ { "agent": [] } ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/events/{id}/redeliver": { "post": { "operationId": "post_v1_events_id_redeliver", "summary": "Re-arm one event for the next webhook delivery pass.", "tags": [ "events" ], "security": [ { "agent": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/health": { "get": { "operationId": "get_api_health", "summary": "Liveness probe for the web app (uptime monitors).", "tags": [ "operations" ], "security": [], "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "servers": [ { "url": "https://contextfile.ai", "description": "Web app" } ] } }, "/.well-known/report-keys": { "get": { "operationId": "get_well_known_report_keys", "summary": "Public report-signing keys: verify any report signature offline with nothing else.", "tags": [ "reports" ], "security": [], "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "servers": [ { "url": "https://contextfile.ai", "description": "Web app" } ] } }, "/offers/{id}": { "get": { "operationId": "get_offers_id", "summary": "The offer document for a live listing (ETag, If-None-Match gives 304).", "tags": [ "offers" ], "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "servers": [ { "url": "https://contextfile.ai", "description": "Web app" } ] } }, "/schemas/offer-v1.json": { "get": { "operationId": "get_schemas_offer_v1_json", "summary": "JSON Schema (draft 2020-12) of offer documents.", "tags": [ "offers" ], "security": [], "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "servers": [ { "url": "https://contextfile.ai", "description": "Web app" } ] } }, "/export/okf": { "get": { "operationId": "get_export_okf", "summary": "OKF export of public content.", "tags": [ "offers" ], "security": [], "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "servers": [ { "url": "https://contextfile.ai", "description": "Web app" } ] } }, "/api/sync/revisions": { "get": { "operationId": "get_api_sync_revisions", "summary": "What the server holds for a synced folder (cf sync).", "tags": [ "sync" ], "security": [ { "device": [] } ], "parameters": [ { "name": "locator", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "servers": [ { "url": "https://contextfile.ai", "description": "Web app" } ] } }, "/api/sync/manifest": { "post": { "operationId": "post_api_sync_manifest", "summary": "Which digests the owner does not hold yet.", "tags": [ "sync" ], "security": [ { "device": [] } ], "parameters": [ { "name": "locator", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "servers": [ { "url": "https://contextfile.ai", "description": "Web app" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object" } } }, "required": [ "entries" ] } } } } } }, "/api/sync/blobs/{digest}": { "put": { "operationId": "put_api_sync_blobs_digest", "summary": "Upload one blob; the server re-hashes it.", "tags": [ "sync" ], "security": [ { "device": [] } ], "parameters": [ { "name": "digest", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "servers": [ { "url": "https://contextfile.ai", "description": "Web app" } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "contentEncoding": "binary" } } } } } }, "/api/sync/snapshots": { "post": { "operationId": "post_api_sync_snapshots", "summary": "Commit snapshots (Idempotency-Key required); server-side injection scan.", "tags": [ "sync" ], "security": [ { "device": [] } ], "parameters": [ { "name": "locator", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "servers": [ { "url": "https://contextfile.ai", "description": "Web app" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "snapshots": { "type": "array", "items": { "type": "object" } } }, "required": [ "snapshots" ] } } } } } }, "/api/stripe/webhook": { "post": { "operationId": "post_api_stripe_webhook", "summary": "Stripe events (signature verified). The only path that credits real money.", "tags": [ "payments" ], "security": [ { "stripe": [] } ], "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "servers": [ { "url": "https://contextfile.ai", "description": "Web app" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/account/export": { "get": { "operationId": "get_api_account_export", "summary": "Download everything held about the signed-in person (GDPR/CCPA).", "tags": [ "account" ], "security": [ { "session": [] } ], "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "servers": [ { "url": "https://contextfile.ai", "description": "Web app" } ] } }, "/api/orders/{order_id}/compliance": { "get": { "operationId": "get_api_orders_order_id_compliance", "summary": "The signed compliance bundle for one of the signed-in buyer's orders.", "tags": [ "account" ], "security": [ { "session": [] } ], "parameters": [ { "name": "order_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "servers": [ { "url": "https://contextfile.ai", "description": "Web app" } ] } } }, "components": { "schemas": { "ApiError": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "requote_required", "insufficient_credits", "mandate_exceeded", "mandate_revoked", "floor_not_met", "quota_exhausted", "judge_version_rejected", "idempotency_conflict", "not_found", "unauthorized", "forbidden", "rate_limited", "validation_failed", "pending_approval", "unavailable" ] }, "message": { "type": "string" }, "remediation": { "type": "string" }, "retryable": { "type": "boolean" }, "docs_url": { "type": "string", "format": "uri" } }, "required": [ "code", "message", "remediation", "retryable", "docs_url" ], "additionalProperties": false } }, "responses": { "Error": { "description": "Typed error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "securitySchemes": { "agent": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Agent access token from the OAuth AS, or a sandbox token from POST /sandbox/agents." }, "device": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Device token from cf login (audience https://contextfile.ai/api/sync, scope sync:write)." }, "session": { "type": "apiKey", "in": "cookie", "name": "__Host-cf_session", "description": "Signed-in browser session." }, "stripe": { "type": "apiKey", "in": "header", "name": "Stripe-Signature", "description": "Stripe webhook signature." } } }, "tags": [ { "name": "account" }, { "name": "balance" }, { "name": "errata" }, { "name": "events" }, { "name": "ledger" }, { "name": "mcp" }, { "name": "oauth" }, { "name": "offers" }, { "name": "operations" }, { "name": "orders" }, { "name": "payments" }, { "name": "payouts" }, { "name": "reports" }, { "name": "sandbox" }, { "name": "search" }, { "name": "subscriptions" }, { "name": "sync" }, { "name": "topups" }, { "name": "trust" } ] }