> ## Documentation Index > Fetch the complete documentation index at: https://docs.useorgx.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Receipt > The receipt resources: portable agent-work receipts you can validate and import, and the execution receipts OrgX records for completed work. Receipts are the proof layer. Two related resources share the name: 1. **Agent work receipt** — a portable, self-describing JSON document (schema `agent-work-receipt/v0.1`) that any agent system can produce. You can validate one without an account and import it into a workspace. 2. **Execution receipt** — the workspace-side record OrgX keeps for completed work: intent, cost, tokens, quality, and entity references. Imported agent work receipts are stored as execution receipts, and `POST /work` operations create them automatically. ## Agent work receipt — wire shape Top-level required sections: `schema_version` (`"agent-work-receipt/v0.1"`), `receipt_id`, `intent`, `actor`, `authority`, `actions[]`, `artifacts[]`, `evidence[]`, `outcome`, `verification`, `cost`, `lineage`, `human_interventions[]`, `timestamps` (`started_at`, `completed_at`, `issued_at`). Optional: `integrity` (a `sha-256` `content_hash` plus optional `ed25519` signatures) and `extensions`. Key vocabularies: `verification.status` is `unverified`, `passed`, `failed`, `partial`, or `inconclusive`; per-check status adds `skipped`; acceptance state is `pending`, `accepted`, `rejected`, or `changes_requested`. Receipts link to each other by reference (`lineage.parent_receipt_refs`), not by hash chain. `GET /api/v1/agent-work-receipts/validate` returns the full JSON Schema — that is the exact machine contract. ### The complete required set Validation reports one issue at a time, so building a receipt by trial and error surfaces `schema_version`, then `authority`, then `artifacts`, one round-trip apiece. Here is everything required, in one place. Every section below is required at the top level, and unlisted properties are rejected. | Section | Required inside it | | --------------------- | ----------------------------------------------------------------------------------------------- | | `schema_version` | exactly `"agent-work-receipt/v0.1"` | | `receipt_id` | non-blank string, ≤512 chars (opaque — a UUID is not required) | | `intent` | `summary` | | `actor` | `type`, `id` | | `authority` | `mode`, `status`, `scope` | | `actions` | array, **at least one**; each item needs `id`, `type`, `summary`, `status` | | `artifacts` | array — **the key is required, but `[]` is valid**; each item needs `id`, `kind`, `name`, `ref` | | `evidence` | array, **at least one**; each item needs `id`, `kind`, `summary`, `observed_at` | | `outcome` | `status`, `summary` | | `verification` | `status`, `method`, `checks`, `evidence_ids` (`checks` and `evidence_ids` may be `[]`) | | `cost` | `currency`, `total` | | `lineage` | `parent_receipt_refs`, `references` (both may be `[]`) | | `human_interventions` | array — may be `[]`; each item needs `id`, `kind`, `actor`, `summary`, `occurred_at` | | `timestamps` | `started_at`, `completed_at`, `issued_at` | `integrity` and `extensions` are the only optional top-level sections. **`authority`** — `mode` ∈ `explicit` `delegated` `inherited` `policy` `none` `unknown`; `status` ∈ `granted` `restricted` `denied` `expired` `unknown`; `scope` is an object requiring both `actions` (array of strings) and `resources` (array of external references), each of which may be `[]`. **`artifacts[]` and every other `ref`** — an external reference requires `system`, `type`, and `id`. `uri`, `version`, `digest`, and `metadata` are optional. **Status enums differ per section, and they are not interchangeable.** `actions[].status` ∈ `planned` `running` `completed` `failed` `skipped` `blocked`; `outcome.status` ∈ `succeeded` `partially_succeeded` `failed` `blocked` `cancelled` `unknown`; `actor.type` ∈ `agent` `service` `human` `team` `system` `other`. `cost.currency` must match `^[A-Z][A-Z0-9_-]+$` and be 3–12 characters. Beyond the schema, four semantic rules are checked: `id` values must be unique within `actions`, `artifacts`, `evidence`, `human_interventions`, and `verification.checks`; every evidence id referenced from `verification` or `outcome` must exist in `evidence`; `completed_at` must not precede `started_at` and `issued_at` must not precede `completed_at`; and `authority.valid_until` must not precede `valid_from`. A minimal receipt that validates: ```json theme={"dark"} { "schema_version": "agent-work-receipt/v0.1", "receipt_id": "rcpt-2026-08-19-001", "intent": { "summary": "Review the launch plan." }, "actor": { "type": "agent", "id": "engineering-agent" }, "authority": { "mode": "delegated", "status": "granted", "scope": { "actions": ["review"], "resources": [] } }, "actions": [ { "id": "a1", "type": "review", "summary": "Read the plan.", "status": "completed" } ], "artifacts": [], "evidence": [ { "id": "e1", "kind": "log", "summary": "Review notes.", "observed_at": "2026-08-19T12:00:00Z" } ], "outcome": { "status": "succeeded", "summary": "Plan reviewed, two gaps noted." }, "verification": { "status": "unverified", "method": "none", "checks": [], "evidence_ids": [] }, "cost": { "currency": "USD", "total": 0.42 }, "lineage": { "parent_receipt_refs": [], "references": [] }, "human_interventions": [], "timestamps": { "started_at": "2026-08-19T11:58:00Z", "completed_at": "2026-08-19T12:00:00Z", "issued_at": "2026-08-19T12:00:05Z" } } ``` ## Validate — account-free ```bash theme={"dark"} curl https://useorgx.com/api/v1/agent-work-receipts/validate \ -X POST \ -H 'Content-Type: application/json' \ -d @receipt.json ``` No API key needed. Returns `200` with a digest summary for a conforming receipt, `422` with itemized issues otherwise. Nothing is stored. Requests above 256 KiB return `413`; duplicate JSON member names return `400`. ## Import — `POST /api/v1/agent-work-receipts` Accepts `Authorization: Bearer oxk_...` or a web-app session. The import request body is capped at 272 KiB (`413 receipt_import_too_large`); the account-free validate endpoint is capped at 256 KiB. | Field | Type | Required | Meaning | | ----------------- | ------------------------------ | -------- | --------------------------------- | | `receipt` | agent work receipt object | yes | The document to import. | | `workspace_id` | UUID | no | Defaults to your key's workspace. | | `idempotency_key` | string ≤160 (`A-Za-z0-9._:/-`) | no | Body-level deduplication key. | Deduplication precedence: the `Idempotency-Key` header, then the body `idempotency_key`, then a digest derived from the receipt content — so a byte-identical retry is always safe. ```bash theme={"dark"} curl https://useorgx.com/api/v1/agent-work-receipts \ -X POST \ -H "Authorization: Bearer $ORGX_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "receipt": { "schema_version": "agent-work-receipt/v0.1", "receipt_id": "rcpt-2026-08-19-001", ... } }' ``` Returns `201` `{ "ok": true, "receipt_id", "external_receipt_id", "schema_version", "idempotent": false, "imported_at" }` — a bare `ok`-shaped object, not the `{ data, meta }` envelope. A replay returns `200` with `"idempotent": true` and no `imported_at`. A non-conforming receipt returns `422 invalid_agent_work_receipt` with an `issues` array; a conflicting reuse of an idempotency key returns `409 idempotency_key_conflict`. ## Execution receipts Every accepted work command writes one: the `POST /work` and `POST /work/{taskId}/complete` responses return `data.receiptId` and embed the receipt row in `data.receipt`. Fields include `receipt_type`, `intent`, `summary`, `ref_type`/`ref_id`, `entity_refs`, `agent_type`, `cost_usd`, `quality_score`, `human_feedback`, `status` (`in_progress`, `completed`, `failed`, `cancelled`), and timestamps. `GET /api/v1/execution/receipts?workspace_id=...&days=30` lists recent provider execution receipts (cost, tokens, outcome kind, run linkage) — this read is **web-app session only** today; it is not available to API keys. Run-scoped receipt submission (`POST /api/v1/runs/{runId}/receipt`) accepts a plugin install key carrying the `gateway:drive` scope or an owner session; one receipt per run, retries return the original with `"deduplicated": true`. ## All operations on these resources | Operation | Method + path | Auth | Notes | | ------------------------ | ------------------------------------------- | --------------------------- | ---------------------------------------------------- | | Validate (no account) | `POST /api/v1/agent-work-receipts/validate` | Public | Nothing stored. | | Schema metadata | `GET /api/v1/agent-work-receipts/validate` | Public | Returns the full JSON Schema. | | Import | `POST /api/v1/agent-work-receipts` | API key/session | Layered idempotency; workspace import quota applies. | | Created by work commands | `POST /api/v1/work`, `POST .../complete` | API key | `data.receiptId` in every response. | | Submit for a run | `POST /api/v1/runs/{runId}/receipt` | `gateway:drive` key/session | One per run. | | List execution receipts | `GET /api/v1/execution/receipts` | Session only | Not exposed to API keys today. | | Update / delete | Not exposed | — | Receipts are immutable proof records. | ## Where the IDs come from | Field | Obtain it from | | ----------------------- | ------------------------------------------------------------------------------ | | `receipt_id` (portable) | You (or the producing agent system) mint it inside the receipt document | | `receiptId` (workspace) | `POST /work` responses (`data.receiptId`), or the import response `receipt_id` | | `runId` | Returned by the execution system or a compatibility run read | | `workspace_id` | `GET /api/v1/me` → `data.default_workspace_id`; usually omitted | ## MCP equivalents `orgx_submit_receipt` submits flywheel receipts through the gateway. The portable agent-work-receipt validate/import pair is REST-first and has no MCP equivalent.