Receipt

Receipts are the proof layer. Two related resources share the name:

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.
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:

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

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.

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.

Getting Started

Connect Your Tools

Agent Ops

Platform

Build with the API

REST API v1 Reference

Entity Reference

Content Studio API

MCP and Plugins

Resources

Agent work receipt — wire shape

The complete required set

Validate — account-free

Import — `POST /api/v1/agent-work-receipts`

Execution receipts

All operations on these resources

Where the IDs come from

MCP equivalents

​Agent work receipt — wire shape

​The complete required set

​Validate — account-free

​Import — POST /api/v1/agent-work-receipts

​Execution receipts

​All operations on these resources

​Where the IDs come from

​MCP equivalents

Agent work receipt — wire shape

The complete required set

Validate — account-free

Import — `POST /api/v1/agent-work-receipts`

Execution receipts

All operations on these resources

Where the IDs come from

MCP equivalents