Examples

The full agent lifecycle, from sign-up to refund, as real requests and responses from the sandbox: register, fund, search, check the report, buy under a mandate, poll the order, download the compliance bundle, and watch the sabotaged edition refund itself. A test replays every one of them, in this order, against the real server and database on every build. Ids, digests and timestamps differ per run; codes, states and field names do not.

{{name}} in a request marks a value taken from an earlier response.

The lifecycle

Register a sandbox agent (no human, test credits)

The sandbox's only sign-up step. The token works on every REST route and on the MCP endpoint. The catalog lists the synthetic listings, including the one built to miss its floor.

POST /sandbox/agents

{
  "name": "example-agent"
}

Response 201:

{
  "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
    }
  }
}

Check the balance

GET /v1/balance
Authorization: Bearer {{token}}

Response 200:

{
  "balance_cents": 10000,
  "currency": "credit"
}

Top up (sandbox: test credits, no payment taken)

In production this charges the card saved at Checkout and credits on Stripe's webhook. In the sandbox it never reaches Stripe.

POST /v1/topups
Authorization: Bearer {{token}}
Idempotency-Key: topup-1

{
  "credits": 5
}

Response 201:

{
  "status": "credited",
  "amount_cents": 500,
  "sandbox": true
}

Search the catalog by capability

GET /v1/search?type=context_file
Authorization: Bearer {{token}}

Response 200:

{
  "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
}

Fetch the signed report

Check the signature against https://contextfile.ai/.well-known/report-keys before you buy.

GET /v1/reports/{{guide_report}}
Authorization: Bearer {{token}}

Response 200:

{
  "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"
}

Read the artifact's computed trust

GET /v1/trust/artifact:{{guide_artifact}}
Authorization: Bearer {{token}}

Response 200:

{
  "score": 0.5,
  "sampleSize": 0,
  "passRate": null
}

Buy under the mandate; escrow holds the price

POST /v1/orders
Authorization: Bearer {{token}}
Idempotency-Key: order-1

{
  "listing_id": "{{guide_listing}}",
  "formats": [
    "md"
  ],
  "max_price_cents": 300
}

Response 201:

{
  "order_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
  "state": "held",
  "escrow_cents": 300,
  "formats": [
    "md"
  ],
  "poll": "get_orders or subscribe to order.state_changed"
}

Poll the order: the report met the floor, escrow released

After the worker has swept held orders (it fulfils them within seconds):

GET /v1/orders
Authorization: Bearer {{token}}

Response 200:

{
  "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
}

Download the signed compliance bundle

GET /v1/orders/{{order_id}}/compliance-bundle
Authorization: Bearer {{token}}

Response 200:

{
  "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..."
  }
}

Buy the sabotaged edition

POST /v1/orders
Authorization: Bearer {{token}}
Idempotency-Key: order-2

{
  "listing_id": "{{sabotaged_listing}}",
  "formats": [
    "md"
  ]
}

Response 201:

{
  "order_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
  "state": "held",
  "escrow_cents": 200,
  "formats": [
    "md"
  ],
  "poll": "get_orders or subscribe to order.state_changed"
}

Poll again: the edition missed its floor and escrow refunded itself

After the worker has swept held orders (it fulfils them within seconds):

GET /v1/orders
Authorization: Bearer {{token}}

Response 200:

{
  "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
}

Check errata on the artifact

GET /v1/errata?artifact_id={{guide_artifact}}
Authorization: Bearer {{token}}

Response 200:

{
  "items": [],
  "next_cursor": null
}

Unhappy paths

The live price is above what you agreed

POST /v1/orders
Authorization: Bearer {{token}}
Idempotency-Key: order-3

{
  "listing_id": "{{guide_listing}}",
  "formats": [
    "md"
  ],
  "max_price_cents": 100
}

Response 409:

{
  "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"
}

A mutating call without an Idempotency-Key

POST /v1/orders
Authorization: Bearer {{token}}

{
  "listing_id": "{{guide_listing}}",
  "formats": [
    "md"
  ]
}

Response 422:

{
  "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"
}

The same key with a different body

POST /v1/orders
Authorization: Bearer {{token}}
Idempotency-Key: order-1

{
  "listing_id": "{{guide_listing}}",
  "formats": [
    "pdf"
  ]
}

Response 422:

{
  "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"
}

A listing on the other side of the sandbox line

Sandbox tokens see only sandbox listings, and production tokens only real ones. Both answer exactly like a listing that does not exist.

POST /v1/orders
Authorization: Bearer {{token}}
Idempotency-Key: order-4

{
  "listing_id": "00000000-0000-4000-8000-000000000000",
  "formats": [
    "md"
  ]
}

Response 404:

{
  "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"
}

No bearer token

GET /v1/balance

Response 401:

{
  "code": "unauthorized",
  "message": "missing Bearer token",
  "remediation": "authenticate",
  "retryable": false,
  "docs_url": "https://contextfile.ai/docs/api#unauthorized"
}

Register a second agent with a tight per-item cap

POST /sandbox/agents

{
  "name": "capped-agent",
  "purchasing": {
    "per_item_max_cents": 100
  }
}

Response 201:

{
  "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
    }
  }
}

The mandate's per-item cap refuses the purchase

POST /v1/orders
Authorization: Bearer {{capped_token}}
Idempotency-Key: order-5

{
  "listing_id": "{{guide_listing}}",
  "formats": [
    "md"
  ]
}

Response 403:

{
  "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"
}

Register an agent that only buys reports scored under judge v99 or later

POST /sandbox/agents

{
  "name": "strict-agent",
  "purchasing": {
    "min_judge_version": "v99"
  }
}

Response 201:

{
  "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
    }
  }
}

The mandate's judge-version filter refuses the purchase

POST /v1/orders
Authorization: Bearer {{strict_token}}
Idempotency-Key: order-6

{
  "listing_id": "{{guide_listing}}",
  "formats": [
    "md"
  ]
}

Response 403:

{
  "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"
}

Version 1, updated 2026-10-11.

This page as markdown · llms.txt

Built for agents to read first.

Examples

The lifecycle

Register a sandbox agent (no human, test credits)

Check the balance

Top up (sandbox: test credits, no payment taken)

Search the catalog by capability

Fetch the signed report

Read the artifact's computed trust

Buy under the mandate; escrow holds the price

Poll the order: the report met the floor, escrow released

Download the signed compliance bundle

Buy the sabotaged edition

Poll again: the edition missed its floor and escrow refunded itself

Check errata on the artifact

Unhappy paths

The live price is above what you agreed

A mutating call without an Idempotency-Key

The same key with a different body

A listing on the other side of the sandbox line

No bearer token

Register a second agent with a tight per-item cap

The mandate's per-item cap refuses the purchase

Register an agent that only buys reports scored under judge v99 or later

The mandate's judge-version filter refuses the purchase