Economicoingestions.start
Retain a document and inspect its contents. Default propose mode creates no financial entries. Explicit auto_record mode can record eligible bills or paid receipts under an explicit recordingPolicy and current authority; unsupported or uncertain sources require review.
What it does
Retain a document and start durable inspection. Supply exact inline text/Markdown, an owned existing source document, or file metadata. Text/Markdown/JSON skips PDF/OCR. Candidate PDF extraction uses verified native conversion or full-page OCR with durable page continuations; primary images use OCR. PDF limits: 50 pages, 8 Mi embedded-image pixels summed per page, 4 Mi rendered-canvas pixels, 100,000 objects per page including form children and form nesting depth 32. OCR inputs are at most 256 KiB and output at most 8,192 tokens per page.
Borderless PDF links with no appearance, background, content or additional action/destination metadata are supported without following links. Nested forms are inventoried within the shared object and image limits before rendering. Visible borders and other annotations report unsupported outcomes. Originals remain available after extraction failure. Supplied text with an optional original remains unverified; optional attachments do not trigger extraction. Completed means classification completed.
Invoice and receipt fields are parsed independently of contract targets or confirmed business ownership; when expenseTargets are supplied, recognized structured invoices and bounded observed text/PDF buyer-invoice spans can return source-backed proposals and ordinary activity or economic-recording previews.
Invoice and receipt header values are read as source spans the kernel verifies against the extraction (invoice-fields-v4/receipt-fields-v4; retained earlier selections stay readable); row judgments use at most 64 questions per request with two concurrent calls: ordinary sources use up to four 48 KiB fast-model requests, sources above 64 money rows or 32 KiB use Clef with up to 1,024 rows and 128 requests of 64 KiB.
Uncertain fast-model judgment groups receive one Clef fallback without replacing confident groups; selections have at most 254 amount candidates per row or date/currency candidates; span headers do not enumerate unused names, identifiers or whole-document total candidates; larger sources fail explicitly. Explicit ISO currency or unambiguous € or US Dollars markers, absolute ISO/English-month dates or day-first slash dates whose day exceeds 12, delivered service evidence and complete reconciled charge lines are required; nonzero tax and unresolved facts need review.
Default propose mode creates no financial entries. Opt-in auto_record requires recordingPolicy with minimumConfidencePercent of 60–100 and frozen existing contract/activity/CID targets; it has no amount limits or currency. Registered structured vendor invoices or complete source-bound PDF/UTF-8 invoice interpretations with a matching business buyer can be eligible. Every used selection must meet the policy confidence, and frozen buyer/source/contract evidence must remain valid.
Historical interpretations without a frozen buyer, inline unverified text, primary images and incomplete/unsupported PDF receipts remain review cases. A separate durable delivery uses ordinary contracts.record under saved and freshly reloaded authority; poll execution.status and commandId for financial completion. Derived and inline text retain at most 64 KiB of UTF-8. The current classifier has a separate 64 KiB whole serialized-request budget including text, instructions and business context; larger accepted sources can fail classification with classifier_input_too_large.
File upload does not increase that classifier budget. File input returns a short-lived URL, PUT method and contentType; sending exact bytes to it starts processing automatically, without an OAuth header or second start call. One optional original has independent upload status. No financial write is authorized by ingestion alone.
Registered complete vendor_receipt JSON or supported complete source-bound PDF/UTF-8 receipt fields or receipt-spans-v1 interpretations can automatically record one bill plus its full same-time payment through receipts.record when recordingPolicy includes explicit existing fundingAccounts snapshots (financialAccountId,currency,last4,kind,glAccountCode,optional ownerPartyId/providerPartyId). Funding must uniquely match paid source evidence and remain current; a person’s own account (ownerPartyId) in the company’s currency pays a foreign receipt at the bill’s booking rate.
Unverified inline automatic sources, image originals, incomplete/unsupported PDF extraction, different or unresolved billing/payment dates, existing-bill settlement, fees and other FX require review. Receipt selection uses a receipt/purchase date and explicit full same-time payment, never invoice-only issue dates or service delivery.
Before you send it
An authorized OAuth connection may call it, including a headless client. Effective membership, application grant and token permissions still apply. Describe ingestions.start through GET /v1/catalog/commands/{name} before acting.
This command does not accept source_document_id in its envelope. Any input evidence requirements remain as documented below.
Inputs
Put these fields inside the envelope’s input object. The outer envelope names the command, a stable idempotency_key and effective_at; request and recovery rules explain those separately. Use exact minor-unit integer strings for monetary fields. Take existing IDs from prior reads or command results; choose a new identity only where the command asks for one.
Required means required within its containing object; an optional parent can be omitted.
| Field | Type | Required | Meaning and accepted values |
|---|---|---|---|
source | schema-defined | Yes | Choose a matching alternative in the exact schema below. |
mode | string | No | Choose "propose", "auto_record". Default: "propose". |
recordingPolicy | object | No | |
recordingPolicy.minimumConfidencePercent | integer | Yes | Minimum: 60. Maximum: 100. |
recordingPolicy.fundingAccounts | array | No | Items: object. Minimum items: 1. Maximum items: 20. |
recordingPolicy.fundingAccounts[].financialAccountId | string | Yes | Minimum length: 1. Maximum length: 128. |
recordingPolicy.fundingAccounts[].currency | string | Yes | Pattern: "^[A-Z]{3}$". |
recordingPolicy.fundingAccounts[].last4 | string | Yes | Pattern: "^[0-9]{4}$". |
recordingPolicy.fundingAccounts[].kind | string | Yes | Choose "checking", "savings", "card", "wallet", "other". |
recordingPolicy.fundingAccounts[].glAccountCode | number | Yes | Choose 1110, 1310, 1410, 2190, 2135. |
recordingPolicy.fundingAccounts[].ownerPartyId | string | No | Minimum length: 1. |
recordingPolicy.fundingAccounts[].providerPartyId | string | No | Minimum length: 1. |
recordingPolicy.targets | array | Yes | Items: object. Minimum items: 1. Maximum items: 20. |
recordingPolicy.targets[].contractId | string | Yes | Minimum length: 1. Maximum length: 128. |
recordingPolicy.targets[].activityKey | string | Yes | Minimum length: 1. Maximum length: 128. |
recordingPolicy.targets[].cid | string | Yes | Minimum length: 1. Maximum length: 128. |
expenseTargets | array | No | Optional bounded hints for structured vendor-invoice proposals against existing activities. Requires whole-domain document, subject, party and ledger reads, plus activity_effects report access. Automatic execution requires a separate explicit frozen recordingPolicy. Items: object. Minimum items: 1. Maximum items: 20. |
expenseTargets[].contractId | string | Yes | Minimum length: 1. Maximum length: 128. |
expenseTargets[].activityKey | string | Yes | Minimum length: 1. Maximum length: 128. |
original | object | No | Retains exact source bytes. Text/Markdown/JSON bypasses PDF/OCR. Candidate PDF/image extraction retains source-bound text before classification; supported PDFs are limited to 50 pages, with explicit unsupported/limit failures. Optional attachments do not verify supplied transcriptions. |
original.filename | string | Yes | Minimum length: 1. Maximum length: 200. |
original.contentType | string | Yes | Choose "application/pdf", "text/plain", "text/markdown", "text/csv", "application/json", "image/png", "image/jpeg", "image/webp". |
original.size | integer | Yes | Exact byte length. Images are limited to 256 KiB; other files to 10 MiB. Minimum: 1. Maximum: 10485760. |
relationship | string | No | Caller-declared relationship between primary text and an optional original; retained as unverified. Choose "transcription", "summary", "related_original". |
After acceptance
When the command emits events, its documented effects and receipt are recorded in the command transaction. The response returns commandId, replayed, the command-specific result below and emitted events with their IDs and CIDs. A command is not automatically a cash movement or revenue recognition: use the behavior above to determine what this command records.
Inspect result and the affected records or reports before continuing. Save returned identifiers for later calls. Fetch GET /v1/commands/{id} with commandId to recover the accepted receipt; retry the same intent with the same idempotency key if the response was lost. Some commands can succeed with events: [] and return a transient result and commandId without persisting a receipt. A lookup of that ID can return null; retain the returned result and verify the affected record. Retrying can re-evaluate the current state rather than replay a stored result. A domain no_change is a separate success outcome with no persisted receipt.
Result fields
Required means required within its containing object; an optional parent can be omitted.
| Field | Type | Required | Meaning and accepted values |
|---|---|---|---|
ingestionId | string | Yes | |
createdAt | string | Yes | Format: date-time. |
status | string | Yes | Choose "awaiting_upload", "queued", "processing", "completed", "failed". |
source | object | No | |
source.documentId | string | Yes | |
source.cid | string | Yes | |
source.format | string | Yes | Choose "markdown", "text", "document". |
source.provenance | string | Yes | Choose "caller_supplied_unverified", "registered_bytes". |
expenseTargets | array | No | Items: object. Minimum items: 1. Maximum items: 20. |
expenseTargets[].contractId | string | Yes | Minimum length: 1. Maximum length: 128. |
expenseTargets[].activityKey | string | Yes | Minimum length: 1. Maximum length: 128. |
mode | string | No | Choose "propose", "auto_record". |
recordingPolicy | object | No | |
recordingPolicy.minimumConfidencePercent | integer | Yes | Minimum: 60. Maximum: 100. |
recordingPolicy.fundingAccounts | array | No | Items: object. Minimum items: 1. Maximum items: 20. |
recordingPolicy.fundingAccounts[].financialAccountId | string | Yes | Minimum length: 1. Maximum length: 128. |
recordingPolicy.fundingAccounts[].currency | string | Yes | Pattern: "^[A-Z]{3}$". |
recordingPolicy.fundingAccounts[].last4 | string | Yes | Pattern: "^[0-9]{4}$". |
recordingPolicy.fundingAccounts[].kind | string | Yes | Choose "checking", "savings", "card", "wallet", "other". |
recordingPolicy.fundingAccounts[].glAccountCode | number | Yes | Choose 1110, 1310, 1410, 2190, 2135. |
recordingPolicy.fundingAccounts[].ownerPartyId | string | No | Minimum length: 1. |
recordingPolicy.fundingAccounts[].providerPartyId | string | No | Minimum length: 1. |
recordingPolicy.targets | array | Yes | Items: object. Minimum items: 1. Maximum items: 20. |
recordingPolicy.targets[].contractId | string | Yes | Minimum length: 1. Maximum length: 128. |
recordingPolicy.targets[].activityKey | string | Yes | Minimum length: 1. Maximum length: 128. |
recordingPolicy.targets[].cid | string | Yes | Minimum length: 1. Maximum length: 128. |
execution | object | No | Durable financial recording disposition and actual ordinary command receipt reference. |
execution.status | string | Yes | Choose "pending", "recorded", "already_recorded", "needs_review". |
execution.proposalRevision | integer | Yes | Minimum: 1. Maximum: 8. |
execution.commandId | string | No | Actual ordinary financial command receipt. |
execution.occurrenceId | string | No | An already recorded matching economic fact. |
execution.reason | string | No | Why automatic recording requires review. |
proposal | object | No | Frozen source-backed expense proposal. Proposal generation creates no financial entries. Choose a matching alternative in the exact schema below. |
proposal.disposition | string | Yes | Choose "ready", "needs_information", "duplicate", "unsupported". |
proposal.source | object | Yes | |
proposal.source.documentId | string | Yes | Minimum length: 1. |
proposal.source.cid | string | Yes | Minimum length: 1. |
proposal.missing | array | Yes | Items: string. Maximum items: 100. |
proposal.lines | array | Yes | Items: object. Maximum items: 500. |
proposal.lines[].index | integer | Yes | Minimum: 0. |
proposal.lines[].description | string | Yes | Minimum length: 1. |
proposal.lines[].amountMinor | string | Yes | Pattern: "^[0-9]+$". |
proposal.currency | string | No | Pattern: "^[A-Z]{3}$". |
proposal.totalMinor | string | No | Pattern: "^[0-9]+$". |
proposal.matchedOccurrenceId | string | No | An existing matching economic fact. Minimum length: 1. |
proposal.contract | object | No | |
proposal.contract.contractId | string | Yes | Minimum length: 1. |
proposal.contract.documentId | string | Yes | Minimum length: 1. |
proposal.contract.cid | string | Yes | Minimum length: 1. |
proposal.command | schema-defined | No | Choose a matching alternative in the exact schema below. |
proposal.interpretation | object | No | |
proposal.interpretation.cid | string | Yes | Minimum length: 1. |
proposal.interpretation.promptVersion | string | Yes | Minimum length: 1. |
proposal.interpretation.buyer | string | No | Exact observed buyer; historical proposals without this field remain review cases. Minimum length: 1. |
proposal.interpretation.spans | array | Yes | Items: object. Maximum items: 1000. |
proposal.interpretation.spans[].start | integer | Yes | Minimum: 0. |
proposal.interpretation.spans[].end | integer | Yes | Minimum: 1. Maximum: 65536. |
proposal.interpretation.spans[].text | string | Yes | Minimum length: 1. |
proposal.preview | schema-defined | No | Read-only ordinary activity or priced-rights preparation, when validation succeeds. |
invoiceCorrection | object | No | |
invoiceCorrection.at | string | Yes | Format: date-time. |
invoiceCorrection.principal | string | Yes | |
invoiceCorrection.provenance | string | Yes | Must be "caller_selected_source_spans". |
invoiceCorrection.choices | object | Yes | |
invoiceCorrection.choices.headers | object | Yes | |
invoiceCorrection.choices.headers.vendor | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
invoiceCorrection.choices.headers.buyer | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
invoiceCorrection.choices.headers.externalId | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
invoiceCorrection.choices.headers.date | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
invoiceCorrection.choices.headers.currency | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
invoiceCorrection.choices.headers.total | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
invoiceCorrection.choices.service | string | Yes | Choose "delivered", "not_delivered", "unclear". |
invoiceCorrection.choices.rows | array | Yes | Items: object. Maximum items: 64. |
invoiceCorrection.choices.rows[].role | string | Yes | Choose "charge", "tax", "summary", "other", "unclear". |
invoiceCorrection.choices.rows[].amount | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
proposalRevision | integer | No | Minimum: 2. Maximum: 8. |
proposalHistory | array | No | Items: object. Maximum items: 7. |
proposalHistory[].revision | integer | Yes | Minimum: 1. Maximum: 7. |
proposalHistory[].at | string | Yes | Format: date-time. |
proposalHistory[].principal | string | Yes | |
proposalHistory[].expenseTargets | array | No | Items: object. Minimum items: 1. Maximum items: 20. |
proposalHistory[].expenseTargets[].contractId | string | Yes | Minimum length: 1. Maximum length: 128. |
proposalHistory[].expenseTargets[].activityKey | string | Yes | Minimum length: 1. Maximum length: 128. |
proposalHistory[].proposal | object | No | Frozen source-backed expense proposal. Proposal generation creates no financial entries. Choose a matching alternative in the exact schema below. |
proposalHistory[].proposal.disposition | string | Yes | Choose "ready", "needs_information", "duplicate", "unsupported". |
proposalHistory[].proposal.source | object | Yes | |
proposalHistory[].proposal.source.documentId | string | Yes | Minimum length: 1. |
proposalHistory[].proposal.source.cid | string | Yes | Minimum length: 1. |
proposalHistory[].proposal.missing | array | Yes | Items: string. Maximum items: 100. |
proposalHistory[].proposal.lines | array | Yes | Items: object. Maximum items: 500. |
proposalHistory[].proposal.lines[].index | integer | Yes | Minimum: 0. |
proposalHistory[].proposal.lines[].description | string | Yes | Minimum length: 1. |
proposalHistory[].proposal.lines[].amountMinor | string | Yes | Pattern: "^[0-9]+$". |
proposalHistory[].proposal.currency | string | No | Pattern: "^[A-Z]{3}$". |
proposalHistory[].proposal.totalMinor | string | No | Pattern: "^[0-9]+$". |
proposalHistory[].proposal.matchedOccurrenceId | string | No | An existing matching economic fact. Minimum length: 1. |
proposalHistory[].proposal.contract | object | No | |
proposalHistory[].proposal.contract.contractId | string | Yes | Minimum length: 1. |
proposalHistory[].proposal.contract.documentId | string | Yes | Minimum length: 1. |
proposalHistory[].proposal.contract.cid | string | Yes | Minimum length: 1. |
proposalHistory[].proposal.command | schema-defined | No | Choose a matching alternative in the exact schema below. |
proposalHistory[].proposal.interpretation | object | No | |
proposalHistory[].proposal.interpretation.cid | string | Yes | Minimum length: 1. |
proposalHistory[].proposal.interpretation.promptVersion | string | Yes | Minimum length: 1. |
proposalHistory[].proposal.interpretation.buyer | string | No | Exact observed buyer; historical proposals without this field remain review cases. Minimum length: 1. |
proposalHistory[].proposal.interpretation.spans | array | Yes | Items: object. Maximum items: 1000. |
proposalHistory[].proposal.interpretation.spans[].start | integer | Yes | Minimum: 0. |
proposalHistory[].proposal.interpretation.spans[].end | integer | Yes | Minimum: 1. Maximum: 65536. |
proposalHistory[].proposal.interpretation.spans[].text | string | Yes | Minimum length: 1. |
proposalHistory[].proposal.preview | schema-defined | No | Read-only ordinary activity or priced-rights preparation, when validation succeeds. |
proposalHistory[].invoiceCorrection | object | No | |
proposalHistory[].invoiceCorrection.at | string | Yes | Format: date-time. |
proposalHistory[].invoiceCorrection.principal | string | Yes | |
proposalHistory[].invoiceCorrection.provenance | string | Yes | Must be "caller_selected_source_spans". |
proposalHistory[].invoiceCorrection.choices | object | Yes | |
proposalHistory[].invoiceCorrection.choices.headers | object | Yes | |
proposalHistory[].invoiceCorrection.choices.headers.vendor | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
proposalHistory[].invoiceCorrection.choices.headers.buyer | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
proposalHistory[].invoiceCorrection.choices.headers.externalId | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
proposalHistory[].invoiceCorrection.choices.headers.date | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
proposalHistory[].invoiceCorrection.choices.headers.currency | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
proposalHistory[].invoiceCorrection.choices.headers.total | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
proposalHistory[].invoiceCorrection.choices.service | string | Yes | Choose "delivered", "not_delivered", "unclear". |
proposalHistory[].invoiceCorrection.choices.rows | array | Yes | Items: object. Maximum items: 64. |
proposalHistory[].invoiceCorrection.choices.rows[].role | string | Yes | Choose "charge", "tax", "summary", "other", "unclear". |
proposalHistory[].invoiceCorrection.choices.rows[].amount | string | Yes | Pattern: "^(?:none|v[0-9]{1,3})$". |
original | object | No | |
original.documentId | string | Yes | |
original.cid | string | Yes | |
original.format | string | Yes | Choose "markdown", "text", "document". |
original.provenance | string | Yes | Choose "caller_supplied_unverified", "registered_bytes". |
failure | object | No | |
failure.reason | string | Yes | |
failure.retryable | boolean | Yes | |
lastFailure | object | No | |
lastFailure.reason | string | Yes | |
lastFailure.retryable | boolean | Yes | |
lastFailure.attempt | integer | Yes | Minimum: 1. Maximum: 12. |
lastFailure.at | string | Yes | Format: date-time. |
relationship | object | No | |
relationship.type | string | Yes | Choose "transcription", "summary", "related_original". |
relationship.declaredBy | string | Yes | |
relationship.verification | string | Yes | Must be "unverified". |
uploads | object | Yes | |
uploads.primary | object | No | |
uploads.primary.filename | string | Yes | Minimum length: 1. Maximum length: 200. |
uploads.primary.contentType | string | Yes | Choose "application/pdf", "text/plain", "text/markdown", "text/csv", "application/json", "image/png", "image/jpeg", "image/webp". |
uploads.primary.size | integer | Yes | Exact byte length. Images are limited to 256 KiB; other files to 10 MiB. Minimum: 1. Maximum: 10485760. |
uploads.primary.expiresAt | string | Yes | Format: date-time. |
uploads.primary.status | string | Yes | Choose "awaiting_upload", "uploaded", "expired". |
uploads.primary.documentId | string | No | |
uploads.primary.cid | string | No | |
uploads.primary.url | string | No | Short-lived upload credential. Send exact bytes to this URL with the returned method and contentType; no OAuth header is required. Present only in the response of the command that issued it (ingestions.start, ingestions.attach_original, ingestions.reissue_upload); replays and reads omit it, so call ingestions.reissue_upload for a fresh one. |
uploads.primary.method | string | No | Present when this response issued the upload URL. Must be "PUT". |
uploads.original | object | No | |
uploads.original.filename | string | Yes | Minimum length: 1. Maximum length: 200. |
uploads.original.contentType | string | Yes | Choose "application/pdf", "text/plain", "text/markdown", "text/csv", "application/json", "image/png", "image/jpeg", "image/webp". |
uploads.original.size | integer | Yes | Exact byte length. Images are limited to 256 KiB; other files to 10 MiB. Minimum: 1. Maximum: 10485760. |
uploads.original.expiresAt | string | Yes | Format: date-time. |
uploads.original.status | string | Yes | Choose "awaiting_upload", "uploaded", "expired". |
uploads.original.documentId | string | No | |
uploads.original.cid | string | No | |
uploads.original.url | string | No | Short-lived upload credential. Send exact bytes to this URL with the returned method and contentType; no OAuth header is required. Present only in the response of the command that issued it (ingestions.start, ingestions.attach_original, ingestions.reissue_upload); replays and reads omit it, so call ingestions.reissue_upload for a fresh one. |
uploads.original.method | string | No | Present when this response issued the upload URL. Must be "PUT". |
revisions | array | Yes | Items: object. |
revisions[].revision | integer | Yes | Minimum: 1. |
revisions[].startedAt | string | Yes | Format: date-time. |
revisions[].business | object | Yes | |
revisions[].business.name | string | Yes | |
revisions[].business.legalName | string or null | Yes | |
revisions[].completedAt | string | No | Format: date-time. |
revisions[].status | string | Yes | Choose "processing", "completed", "failed". |
revisions[].sources | array | Yes | Items: object. |
revisions[].sources[].documentId | string | Yes | |
revisions[].sources[].cid | string | Yes | |
revisions[].sources[].format | string | Yes | Choose "markdown", "text", "document". |
revisions[].sources[].provenance | string | Yes | Choose "caller_supplied_unverified", "registered_bytes". |
revisions[].sources[].role | string | Yes | Choose "primary", "original". |
revisions[].failure | object | No | |
revisions[].failure.reason | string | Yes | |
revisions[].failure.retryable | boolean | Yes | |
revisions[].invoiceSelection | object | No | Observed source-span choices, bound to the committed UTF-8 extraction. Spans versions pick candidate indices; fields versions carry verified UTF-8 spans for header and payment-identity values. Choice probability is not financial accuracy or authorization. |
revisions[].invoiceSelection.textCid | string | Yes | |
revisions[].invoiceSelection.promptVersion | string | Yes | Choose "invoice-fields-v5", "receipt-fields-v5", "invoice-spans-v1", "receipt-spans-v1", "invoice-fields-v1", "receipt-fields-v1", "invoice-fields-v2", "receipt-fields-v2", "invoice-fields-v3", "receipt-fields-v3", "invoice-fields-v4", "receipt-fields-v4". |
revisions[].invoiceSelection.headers | object | Yes | |
revisions[].invoiceSelection.headers.vendor | object | Yes | |
revisions[].invoiceSelection.headers.vendor.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.headers.vendor.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.headers.vendor.span | object | No | |
revisions[].invoiceSelection.headers.vendor.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.vendor.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.vendor.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.headers.buyer | object | Yes | |
revisions[].invoiceSelection.headers.buyer.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.headers.buyer.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.headers.buyer.span | object | No | |
revisions[].invoiceSelection.headers.buyer.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.buyer.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.buyer.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.headers.externalId | object | Yes | |
revisions[].invoiceSelection.headers.externalId.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.headers.externalId.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.headers.externalId.span | object | No | |
revisions[].invoiceSelection.headers.externalId.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.externalId.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.externalId.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.headers.date | object | Yes | |
revisions[].invoiceSelection.headers.date.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.headers.date.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.headers.date.span | object | No | |
revisions[].invoiceSelection.headers.date.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.date.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.date.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.headers.currency | object | Yes | |
revisions[].invoiceSelection.headers.currency.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.headers.currency.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.headers.currency.span | object | No | |
revisions[].invoiceSelection.headers.currency.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.currency.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.currency.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.headers.total | object | Yes | |
revisions[].invoiceSelection.headers.total.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.headers.total.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.headers.total.span | object | No | |
revisions[].invoiceSelection.headers.total.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.total.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.headers.total.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.provider | object | No | The model that chose header values and optional source-line amounts: Clef for spans versions, Clairic for fields versions. |
revisions[].invoiceSelection.provider.name | string | Yes | Choose "@cf/cloudflare/clef-flash", "@cf/cloudflare/clef", "@cf/cloudflare/clairic". |
revisions[].invoiceSelection.provider.version | string | Yes | Must be "unreported". |
revisions[].invoiceSelection.provider.inputTokens | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.provider.outputTokens | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.provider.requestBytes | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.provider.latencyMs | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.judgmentProvider | object | No | Fields versions only: the Clef model or bounded Flash-to-Clef cascade that answered currency, service, payment status and row judgments. Optional Clairic amount reads are accounted in provider. |
revisions[].invoiceSelection.judgmentProvider.name | string | Yes | Choose "@cf/cloudflare/clef-flash", "@cf/cloudflare/clef", "@cf/cloudflare/clef-flash+clef/uncertain-groups-v1". |
revisions[].invoiceSelection.judgmentProvider.version | string | Yes | Must be "unreported". |
revisions[].invoiceSelection.judgmentProvider.inputTokens | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.judgmentProvider.outputTokens | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.judgmentProvider.requestBytes | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.judgmentProvider.latencyMs | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.groupingProvider | object | No | Measured optional grouping attempt, including a failed attempt that retains physical rows. |
revisions[].invoiceSelection.groupingProvider.name | string | Yes | Choose "@cf/moonshotai/kimi-k2.6". |
revisions[].invoiceSelection.groupingProvider.version | string | Yes | Must be "unreported". |
revisions[].invoiceSelection.groupingProvider.inputTokens | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.groupingProvider.outputTokens | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.groupingProvider.requestBytes | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.groupingProvider.latencyMs | integer | Yes | Minimum: 0. |
revisions[].invoiceSelection.rowGroups | array | No | Items: object. Maximum items: 1024. |
revisions[].invoiceSelection.rowGroups[].firstRow | integer | Yes | Minimum: 0. Maximum: 1023. |
revisions[].invoiceSelection.rowGroups[].lastRow | integer | Yes | Minimum: 0. Maximum: 1023. |
revisions[].invoiceSelection.rowGroups[].anchorRow | integer | Yes | Minimum: 0. Maximum: 1023. |
revisions[].invoiceSelection.rowGroups[].description | object | No | |
revisions[].invoiceSelection.rowGroups[].description.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.rowGroups[].description.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.rowGroups[].description.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.service | object | Yes | |
revisions[].invoiceSelection.service.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.service.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.service.span | object | No | |
revisions[].invoiceSelection.service.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.service.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.service.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.payment | object | No | |
revisions[].invoiceSelection.payment.status | object | Yes | |
revisions[].invoiceSelection.payment.status.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.payment.status.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.payment.status.span | object | No | |
revisions[].invoiceSelection.payment.status.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.payment.status.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.payment.status.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.payment.externalId | object | Yes | |
revisions[].invoiceSelection.payment.externalId.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.payment.externalId.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.payment.externalId.span | object | No | |
revisions[].invoiceSelection.payment.externalId.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.payment.externalId.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.payment.externalId.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.payment.last4 | object | Yes | |
revisions[].invoiceSelection.payment.last4.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.payment.last4.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.payment.last4.span | object | No | |
revisions[].invoiceSelection.payment.last4.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.payment.last4.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.payment.last4.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.rows | array | Yes | Items: object. Maximum items: 1024. |
revisions[].invoiceSelection.rows[].role | object | Yes | |
revisions[].invoiceSelection.rows[].role.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.rows[].role.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.rows[].role.span | object | No | |
revisions[].invoiceSelection.rows[].role.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.rows[].role.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.rows[].role.span.text | string | Yes | Maximum length: 65536. |
revisions[].invoiceSelection.rows[].amount | object | Yes | |
revisions[].invoiceSelection.rows[].amount.choice | string | Yes | Maximum length: 32. |
revisions[].invoiceSelection.rows[].amount.probability | string | Yes | Pattern: "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$". |
revisions[].invoiceSelection.rows[].amount.span | object | No | |
revisions[].invoiceSelection.rows[].amount.span.start | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.rows[].amount.span.end | integer | Yes | Minimum: 0. Maximum: 65536. |
revisions[].invoiceSelection.rows[].amount.span.text | string | Yes | Maximum length: 65536. |
revisions[].extraction | object | No | |
revisions[].extraction.status | string | Yes | Choose "not_required", "extracted", "incomplete". |
revisions[].extraction.method | string | Yes | Choose "provided_text", "native_pdf", "image_ocr", "pdf_ocr". |
revisions[].extraction.text | string | No | Returned only after source-document authorization; raw history contains annex references. Maximum length: 65536. |
revisions[].extraction.textBytes | integer | Yes | Minimum: 1. Maximum: 65536. |
revisions[].extraction.source | object | Yes | |
revisions[].extraction.source.documentId | string | Yes | |
revisions[].extraction.source.cid | string | Yes | |
revisions[].extraction.source.format | string | Yes | Choose "markdown", "text", "document". |
revisions[].extraction.source.provenance | string | Yes | Choose "caller_supplied_unverified", "registered_bytes". |
revisions[].extraction.derived | object | Yes | |
revisions[].extraction.derived.cid | string | Yes | |
revisions[].extraction.pageCount | integer or null | Yes | Minimum: 1. Maximum: 50. |
revisions[].extraction.locations | array | Yes | Items: object. Maximum items: 50. |
revisions[].extraction.locations[].page | integer or null | Yes | Minimum: 1. |
revisions[].extraction.locations[].start | integer | Yes | Minimum: 0. |
revisions[].extraction.locations[].end | integer | Yes | Minimum: 0. |
revisions[].extraction.provider | object | Yes | |
revisions[].extraction.provider.name | string | Yes | |
revisions[].extraction.provider.version | string | Yes | |
revisions[].extraction.usage | object | Yes | |
revisions[].extraction.usage.inputTokens | integer | Yes | Minimum: 0. |
revisions[].extraction.usage.outputTokens | integer | Yes | Minimum: 0. |
revisions[].extraction.usage.latencyMs | integer | Yes | Minimum: 0. |
revisions[].extraction.usage.conversionTokens | integer | No | Estimated native conversion tokens, distinct from inference usage. Minimum: 0. |
revisions[].classification | object | No | |
revisions[].classification.documentType | string | Yes | Choose "invoice", "receipt", "agreement", "statement_or_remittance", "credit_or_correction", "reminder", "mixed", "other", "uncertain". |
revisions[].classification.probabilities | object | Yes | |
revisions[].classification.probabilities.invoice | string | Yes | Decimal probability between 0 and 1. |
revisions[].classification.probabilities.receipt | string | Yes | Decimal probability between 0 and 1. |
revisions[].classification.probabilities.agreement | string | Yes | Decimal probability between 0 and 1. |
revisions[].classification.probabilities.statement_or_remittance | string | Yes | Decimal probability between 0 and 1. |
revisions[].classification.probabilities.credit_or_correction | string | Yes | Decimal probability between 0 and 1. |
revisions[].classification.probabilities.reminder | string | Yes | Decimal probability between 0 and 1. |
revisions[].classification.probabilities.mixed | string | Yes | Decimal probability between 0 and 1. |
revisions[].classification.probabilities.other | string | Yes | Decimal probability between 0 and 1. |
revisions[].classification.probabilities.uncertain | string | Yes | Decimal probability between 0 and 1. |
revisions[].classification.model | string | Yes | |
revisions[].classification.modelVersion | string | Yes | |
revisions[].classification.promptVersion | string | Yes | |
revisions[].classification.confidence | string | No | Distribution confidence, not calibrated accuracy or permission to act. |
revisions[].classification.invoiceRole | object | No | |
revisions[].classification.invoiceRole.role | string | Yes | Choose "buyer", "seller", "neither", "unclear". |
revisions[].classification.invoiceRole.probabilities | object | Yes | |
revisions[].classification.invoiceRole.probabilities.buyer | string | Yes | |
revisions[].classification.invoiceRole.probabilities.seller | string | Yes | |
revisions[].classification.invoiceRole.probabilities.neither | string | Yes | |
revisions[].classification.invoiceRole.probabilities.unclear | string | Yes | |
revisions[].classification.invoiceRole.confidence | string | Yes | |
revisions[].classification.invoiceRole.promptVersion | string | Yes | |
revisions[].classification.usage | object | No | |
revisions[].classification.usage.inputTokens | integer | Yes | Minimum: 0. |
revisions[].classification.usage.outputTokens | integer | Yes | Minimum: 0. |
revisions[].classification.usage.requestBytes | integer | Yes | Minimum: 1. |
revisions[].classification.usage.latencyMs | integer | Yes | Minimum: 0. |
All commands · Operation and errors · Reusable schemas
Keep credentials out of prompts; rehearse writes only in a disposable sandbox.
Exact request schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"const": "ingestions.start"
},
"input": {
"type": "object",
"additionalProperties": false,
"properties": {
"source": {
"anyOf": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"const": "text"
},
"format": {
"enum": [
"text",
"markdown"
]
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 65536,
"description": "Retention limit is 64 KiB of UTF-8; current classification requires the whole serialized request (text, instructions and business context) to fit within 64 KiB, otherwise polling reports classifier_input_too_large."
}
},
"required": [
"type",
"format",
"text"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"const": "document"
},
"documentId": {
"type": "string",
"minLength": 1
}
},
"required": [
"type",
"documentId"
]
},
{
"type": "object",
"description": "Retains exact source bytes. Text/Markdown/JSON bypasses PDF/OCR. Candidate PDF/image extraction retains source-bound text before classification; supported PDFs are limited to 50 pages, with explicit unsupported/limit failures. Optional attachments do not verify supplied transcriptions.",
"additionalProperties": false,
"properties": {
"filename": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"contentType": {
"enum": [
"application/pdf",
"text/plain",
"text/markdown",
"text/csv",
"application/json",
"image/png",
"image/jpeg",
"image/webp"
]
},
"size": {
"type": "integer",
"minimum": 1,
"maximum": 10485760,
"description": "Exact byte length. Images are limited to 256 KiB; other files to 10 MiB."
},
"type": {
"const": "file"
}
},
"required": [
"filename",
"contentType",
"size",
"type"
]
}
]
},
"mode": {
"enum": [
"propose",
"auto_record"
],
"default": "propose"
},
"recordingPolicy": {
"type": "object",
"additionalProperties": false,
"properties": {
"minimumConfidencePercent": {
"type": "integer",
"minimum": 60,
"maximum": 100
},
"fundingAccounts": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"financialAccountId",
"currency",
"last4",
"kind",
"glAccountCode"
],
"properties": {
"financialAccountId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"last4": {
"type": "string",
"pattern": "^[0-9]{4}$"
},
"kind": {
"enum": [
"checking",
"savings",
"card",
"wallet",
"other"
]
},
"glAccountCode": {
"enum": [
1110,
1310,
1410,
2190,
2135
]
},
"ownerPartyId": {
"type": "string",
"minLength": 1
},
"providerPartyId": {
"type": "string",
"minLength": 1
}
}
}
},
"targets": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"contractId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"activityKey": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"cid": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"contractId",
"activityKey",
"cid"
]
}
}
},
"required": [
"minimumConfidencePercent",
"targets"
]
},
"expenseTargets": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"contractId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"activityKey": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"contractId",
"activityKey"
]
},
"description": "Optional bounded hints for structured vendor-invoice proposals against existing activities. Requires whole-domain document, subject, party and ledger reads, plus activity_effects report access. Automatic execution requires a separate explicit frozen recordingPolicy."
},
"original": {
"type": "object",
"description": "Retains exact source bytes. Text/Markdown/JSON bypasses PDF/OCR. Candidate PDF/image extraction retains source-bound text before classification; supported PDFs are limited to 50 pages, with explicit unsupported/limit failures. Optional attachments do not verify supplied transcriptions.",
"additionalProperties": false,
"properties": {
"filename": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"contentType": {
"enum": [
"application/pdf",
"text/plain",
"text/markdown",
"text/csv",
"application/json",
"image/png",
"image/jpeg",
"image/webp"
]
},
"size": {
"type": "integer",
"minimum": 1,
"maximum": 10485760,
"description": "Exact byte length. Images are limited to 256 KiB; other files to 10 MiB."
}
},
"required": [
"filename",
"contentType",
"size"
]
},
"relationship": {
"enum": [
"transcription",
"summary",
"related_original"
],
"description": "Caller-declared relationship between primary text and an optional original; retained as unverified."
}
},
"required": [
"source"
]
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"effective_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
}
},
"required": [
"name",
"input",
"idempotency_key",
"effective_at"
],
"additionalProperties": false
}Accepted command receipt
{
"type": "object",
"required": [
"commandId",
"replayed",
"result",
"events"
],
"properties": {
"commandId": {
"type": "string"
},
"replayed": {
"type": "boolean"
},
"imported": {
"const": true,
"description": "The command's events are history from before the business joined Economico, recorded as an import: free of monthly events."
},
"result": {
"type": "object",
"additionalProperties": false,
"properties": {
"ingestionId": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"status": {
"enum": [
"awaiting_upload",
"queued",
"processing",
"completed",
"failed"
]
},
"source": {
"type": "object",
"additionalProperties": false,
"properties": {
"documentId": {
"type": "string"
},
"cid": {
"type": "string"
},
"format": {
"enum": [
"markdown",
"text",
"document"
]
},
"provenance": {
"enum": [
"caller_supplied_unverified",
"registered_bytes"
]
}
},
"required": [
"documentId",
"cid",
"format",
"provenance"
]
},
"expenseTargets": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"contractId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"activityKey": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"contractId",
"activityKey"
]
}
},
"mode": {
"enum": [
"propose",
"auto_record"
]
},
"recordingPolicy": {
"type": "object",
"additionalProperties": false,
"properties": {
"minimumConfidencePercent": {
"type": "integer",
"minimum": 60,
"maximum": 100
},
"fundingAccounts": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"financialAccountId",
"currency",
"last4",
"kind",
"glAccountCode"
],
"properties": {
"financialAccountId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"last4": {
"type": "string",
"pattern": "^[0-9]{4}$"
},
"kind": {
"enum": [
"checking",
"savings",
"card",
"wallet",
"other"
]
},
"glAccountCode": {
"enum": [
1110,
1310,
1410,
2190,
2135
]
},
"ownerPartyId": {
"type": "string",
"minLength": 1
},
"providerPartyId": {
"type": "string",
"minLength": 1
}
}
}
},
"targets": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"contractId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"activityKey": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"cid": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"contractId",
"activityKey",
"cid"
]
}
}
},
"required": [
"minimumConfidencePercent",
"targets"
]
},
"execution": {
"type": "object",
"additionalProperties": false,
"properties": {
"status": {
"enum": [
"pending",
"recorded",
"already_recorded",
"needs_review"
]
},
"proposalRevision": {
"type": "integer",
"minimum": 1,
"maximum": 8
},
"commandId": {
"type": "string",
"description": "Actual ordinary financial command receipt."
},
"occurrenceId": {
"type": "string",
"description": "An already recorded matching economic fact."
},
"reason": {
"type": "string",
"description": "Why automatic recording requires review."
}
},
"required": [
"status",
"proposalRevision"
],
"description": "Durable financial recording disposition and actual ordinary command receipt reference."
},
"proposal": {
"type": "object",
"additionalProperties": false,
"description": "Frozen source-backed expense proposal. Proposal generation creates no financial entries.",
"required": [
"disposition",
"source",
"missing",
"lines"
],
"properties": {
"disposition": {
"enum": [
"ready",
"needs_information",
"duplicate",
"unsupported"
]
},
"source": {
"type": "object",
"additionalProperties": false,
"properties": {
"documentId": {
"type": "string",
"minLength": 1
},
"cid": {
"type": "string",
"minLength": 1
}
},
"required": [
"documentId",
"cid"
]
},
"missing": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"maxLength": 500
}
},
"lines": {
"type": "array",
"maxItems": 500,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"index": {
"type": "integer",
"minimum": 0
},
"description": {
"type": "string",
"minLength": 1
},
"amountMinor": {
"type": "string",
"pattern": "^[0-9]+$"
}
},
"required": [
"index",
"description",
"amountMinor"
]
}
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"totalMinor": {
"type": "string",
"pattern": "^[0-9]+$"
},
"matchedOccurrenceId": {
"type": "string",
"minLength": 1,
"description": "An existing matching economic fact."
},
"contract": {
"type": "object",
"additionalProperties": false,
"properties": {
"contractId": {
"type": "string",
"minLength": 1
},
"documentId": {
"type": "string",
"minLength": 1
},
"cid": {
"type": "string",
"minLength": 1
}
},
"required": [
"contractId",
"documentId",
"cid"
]
},
"command": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"description": "Complete ordinary public command envelope; present only when ready.",
"required": [
"name",
"input",
"source_document_id",
"effective_at",
"idempotency_key"
],
"properties": {
"name": {
"const": "contracts.record"
},
"source_document_id": {
"type": "string",
"minLength": 1
},
"effective_at": {
"type": "string",
"minLength": 1,
"format": "date-time"
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"input": {
"type": "object",
"additionalProperties": false,
"required": [
"contractId",
"activityKey",
"occurrenceKey",
"sourceFactId",
"effectiveAt",
"facts",
"evidence"
],
"properties": {
"contractId": {
"type": "string",
"minLength": 1
},
"activityKey": {
"type": "string",
"minLength": 1
},
"occurrenceKey": {
"type": "string",
"minLength": 1
},
"sourceFactId": {
"type": "string",
"minLength": 1
},
"effectiveAt": {
"type": "string",
"minLength": 1,
"format": "date-time"
},
"phase": {
"const": "billing"
},
"obligationKey": {
"type": "string",
"minLength": 1
},
"facts": {
"type": "object",
"maxProperties": 100,
"additionalProperties": {
"type": "string"
}
},
"evidence": {
"type": "object",
"additionalProperties": false,
"required": [
"service"
],
"properties": {
"billing": {
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"kind": {
"const": "other"
},
"ref": {
"type": "string",
"minLength": 1
}
},
"required": [
"kind",
"ref"
]
}
},
"service": {
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"kind": {
"const": "other"
},
"ref": {
"type": "string",
"minLength": 1
}
},
"required": [
"kind",
"ref"
]
}
}
}
}
}
}
}
},
{
"type": "object",
"additionalProperties": false,
"description": "Complete ordinary public command envelope; present only when ready.",
"required": [
"name",
"input",
"source_document_id",
"effective_at",
"idempotency_key"
],
"properties": {
"name": {
"const": "receipts.record"
},
"source_document_id": {
"type": "string",
"minLength": 1
},
"effective_at": {
"type": "string",
"minLength": 1,
"format": "date-time"
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"input": {
"type": "object",
"additionalProperties": false,
"required": [
"billing",
"payment"
],
"properties": {
"processing": {
"type": "object",
"additionalProperties": false,
"required": [
"rail",
"netAmount",
"evidence"
],
"properties": {
"rail": {
"enum": [
"ach",
"ach_same_day",
"fedwire",
"rtp",
"sepa",
"sepa_instant",
"swift",
"onchain",
"internal",
"card"
]
},
"netAmount": {
"type": "string",
"pattern": "^(0|-?[1-9][0-9]*)$"
},
"feeFacts": {
"type": "object",
"maxProperties": 20,
"additionalProperties": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
}
},
"evidence": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
}
}
},
"billing": {
"type": "object",
"additionalProperties": false,
"required": [
"contractId",
"activityKey",
"occurrenceKey",
"sourceFactId",
"effectiveAt",
"phase"
],
"anyOf": [
{
"type": "object",
"properties": {
"obligationKey": {
"type": "string",
"minLength": 1
}
},
"required": [
"obligationKey"
]
},
{
"type": "object",
"properties": {
"period": {
"type": "object",
"properties": {
"from": {
"type": "string",
"minLength": 1
},
"through": {
"type": "string",
"minLength": 1
}
},
"required": [
"from",
"through"
]
}
},
"required": [
"period"
]
}
],
"properties": {
"contractId": {
"type": "string",
"minLength": 1
},
"activityKey": {
"type": "string",
"minLength": 1
},
"occurrenceKey": {
"type": "string",
"minLength": 1
},
"obligationKey": {
"type": "string",
"minLength": 1
},
"sourceFactId": {
"type": "string",
"minLength": 1
},
"effectiveAt": {
"type": "string",
"format": "date-time"
},
"phase": {
"const": "billing"
},
"dueDate": {
"type": "string",
"format": "date"
},
"exchangeRate": {
"type": "object",
"additionalProperties": false,
"required": [
"base",
"quote",
"date",
"numerator",
"denominator",
"evidence"
],
"description": "An evidenced exchange rate (1 base = numerator/denominator quote), e.g. from a bank statement. It overrides the shared rate store for this command; omit it to use the store.",
"properties": {
"base": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"quote": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"date": {
"type": "string",
"format": "date"
},
"numerator": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"denominator": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"evidence": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string"
}
}
}
}
}
},
"period": {
"type": "object",
"additionalProperties": false,
"required": [
"from",
"through"
],
"properties": {
"from": {
"type": "string",
"format": "date-time"
},
"through": {
"type": "string",
"format": "date-time"
}
}
},
"facts": {
"type": "object",
"maxProperties": 100,
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "object",
"additionalProperties": false,
"required": [
"occurrenceId"
],
"properties": {
"occurrenceId": {
"type": "string",
"minLength": 1
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"claimId",
"component"
],
"properties": {
"claimId": {
"type": "string",
"minLength": 1
},
"component": {
"type": "object",
"additionalProperties": false,
"required": [
"originLedgerId",
"accountCode"
],
"properties": {
"originLedgerId": {
"type": "string",
"minLength": 1
},
"accountCode": {
"type": "integer"
}
}
}
}
}
]
}
},
"evidence": {
"type": "object",
"additionalProperties": false,
"properties": {
"billing": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
},
"service": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
},
"acceptance": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
},
"economic": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
}
}
}
}
},
"payment": {
"type": "object",
"additionalProperties": false,
"required": [
"financialAccountId",
"direction",
"amount",
"currency",
"partyId",
"effectiveAt",
"sourceFactId",
"evidence"
],
"properties": {
"financialAccountId": {
"type": "string",
"minLength": 1
},
"direction": {
"enum": [
"in",
"out"
]
},
"amount": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"currency": {
"type": "string",
"minLength": 1
},
"partyId": {
"type": "string",
"minLength": 1
},
"effectiveAt": {
"type": "string",
"format": "date-time"
},
"sourceFactId": {
"type": "string",
"minLength": 1
},
"evidence": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
}
}
}
}
}
}
}
]
},
"interpretation": {
"type": "object",
"additionalProperties": false,
"properties": {
"cid": {
"type": "string",
"minLength": 1
},
"promptVersion": {
"type": "string",
"minLength": 1
},
"buyer": {
"type": "string",
"minLength": 1,
"description": "Exact observed buyer; historical proposals without this field remain review cases."
},
"spans": {
"type": "array",
"maxItems": 1000,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"start": {
"type": "integer",
"minimum": 0
},
"end": {
"type": "integer",
"minimum": 1,
"maximum": 65536
},
"text": {
"type": "string",
"minLength": 1
}
},
"required": [
"start",
"end",
"text"
]
}
}
},
"required": [
"cid",
"promptVersion",
"spans"
]
},
"preview": {
"description": "Read-only ordinary activity or priced-rights preparation, when validation succeeds."
}
},
"oneOf": [
{
"properties": {
"disposition": {
"const": "ready"
},
"missing": {
"maxItems": 0
},
"lines": {
"minItems": 1
}
},
"required": [
"command",
"contract",
"currency",
"totalMinor"
]
},
{
"properties": {
"disposition": {
"enum": [
"needs_information",
"duplicate",
"unsupported"
]
}
},
"not": {
"required": [
"command"
]
}
}
]
},
"invoiceCorrection": {
"type": "object",
"additionalProperties": false,
"properties": {
"at": {
"type": "string",
"format": "date-time"
},
"principal": {
"type": "string"
},
"provenance": {
"const": "caller_selected_source_spans"
},
"choices": {
"type": "object",
"additionalProperties": false,
"properties": {
"headers": {
"type": "object",
"additionalProperties": false,
"properties": {
"vendor": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"buyer": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"externalId": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"date": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"currency": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"total": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
}
},
"required": [
"vendor",
"buyer",
"externalId",
"date",
"currency",
"total"
]
},
"service": {
"enum": [
"delivered",
"not_delivered",
"unclear"
]
},
"rows": {
"type": "array",
"maxItems": 64,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"role": {
"enum": [
"charge",
"tax",
"summary",
"other",
"unclear"
]
},
"amount": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
}
},
"required": [
"role",
"amount"
]
}
}
},
"required": [
"headers",
"service",
"rows"
]
}
},
"required": [
"at",
"principal",
"provenance",
"choices"
]
},
"proposalRevision": {
"type": "integer",
"minimum": 2,
"maximum": 8
},
"proposalHistory": {
"type": "array",
"maxItems": 7,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"revision": {
"type": "integer",
"minimum": 1,
"maximum": 7
},
"at": {
"type": "string",
"format": "date-time"
},
"principal": {
"type": "string"
},
"expenseTargets": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"contractId": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"activityKey": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
},
"required": [
"contractId",
"activityKey"
]
}
},
"proposal": {
"type": "object",
"additionalProperties": false,
"description": "Frozen source-backed expense proposal. Proposal generation creates no financial entries.",
"required": [
"disposition",
"source",
"missing",
"lines"
],
"properties": {
"disposition": {
"enum": [
"ready",
"needs_information",
"duplicate",
"unsupported"
]
},
"source": {
"type": "object",
"additionalProperties": false,
"properties": {
"documentId": {
"type": "string",
"minLength": 1
},
"cid": {
"type": "string",
"minLength": 1
}
},
"required": [
"documentId",
"cid"
]
},
"missing": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"maxLength": 500
}
},
"lines": {
"type": "array",
"maxItems": 500,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"index": {
"type": "integer",
"minimum": 0
},
"description": {
"type": "string",
"minLength": 1
},
"amountMinor": {
"type": "string",
"pattern": "^[0-9]+$"
}
},
"required": [
"index",
"description",
"amountMinor"
]
}
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"totalMinor": {
"type": "string",
"pattern": "^[0-9]+$"
},
"matchedOccurrenceId": {
"type": "string",
"minLength": 1,
"description": "An existing matching economic fact."
},
"contract": {
"type": "object",
"additionalProperties": false,
"properties": {
"contractId": {
"type": "string",
"minLength": 1
},
"documentId": {
"type": "string",
"minLength": 1
},
"cid": {
"type": "string",
"minLength": 1
}
},
"required": [
"contractId",
"documentId",
"cid"
]
},
"command": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"description": "Complete ordinary public command envelope; present only when ready.",
"required": [
"name",
"input",
"source_document_id",
"effective_at",
"idempotency_key"
],
"properties": {
"name": {
"const": "contracts.record"
},
"source_document_id": {
"type": "string",
"minLength": 1
},
"effective_at": {
"type": "string",
"minLength": 1,
"format": "date-time"
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"input": {
"type": "object",
"additionalProperties": false,
"required": [
"contractId",
"activityKey",
"occurrenceKey",
"sourceFactId",
"effectiveAt",
"facts",
"evidence"
],
"properties": {
"contractId": {
"type": "string",
"minLength": 1
},
"activityKey": {
"type": "string",
"minLength": 1
},
"occurrenceKey": {
"type": "string",
"minLength": 1
},
"sourceFactId": {
"type": "string",
"minLength": 1
},
"effectiveAt": {
"type": "string",
"minLength": 1,
"format": "date-time"
},
"phase": {
"const": "billing"
},
"obligationKey": {
"type": "string",
"minLength": 1
},
"facts": {
"type": "object",
"maxProperties": 100,
"additionalProperties": {
"type": "string"
}
},
"evidence": {
"type": "object",
"additionalProperties": false,
"required": [
"service"
],
"properties": {
"billing": {
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"kind": {
"const": "other"
},
"ref": {
"type": "string",
"minLength": 1
}
},
"required": [
"kind",
"ref"
]
}
},
"service": {
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"kind": {
"const": "other"
},
"ref": {
"type": "string",
"minLength": 1
}
},
"required": [
"kind",
"ref"
]
}
}
}
}
}
}
}
},
{
"type": "object",
"additionalProperties": false,
"description": "Complete ordinary public command envelope; present only when ready.",
"required": [
"name",
"input",
"source_document_id",
"effective_at",
"idempotency_key"
],
"properties": {
"name": {
"const": "receipts.record"
},
"source_document_id": {
"type": "string",
"minLength": 1
},
"effective_at": {
"type": "string",
"minLength": 1,
"format": "date-time"
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"input": {
"type": "object",
"additionalProperties": false,
"required": [
"billing",
"payment"
],
"properties": {
"processing": {
"type": "object",
"additionalProperties": false,
"required": [
"rail",
"netAmount",
"evidence"
],
"properties": {
"rail": {
"enum": [
"ach",
"ach_same_day",
"fedwire",
"rtp",
"sepa",
"sepa_instant",
"swift",
"onchain",
"internal",
"card"
]
},
"netAmount": {
"type": "string",
"pattern": "^(0|-?[1-9][0-9]*)$"
},
"feeFacts": {
"type": "object",
"maxProperties": 20,
"additionalProperties": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$"
}
},
"evidence": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
}
}
},
"billing": {
"type": "object",
"additionalProperties": false,
"required": [
"contractId",
"activityKey",
"occurrenceKey",
"sourceFactId",
"effectiveAt",
"phase"
],
"anyOf": [
{
"type": "object",
"properties": {
"obligationKey": {
"type": "string",
"minLength": 1
}
},
"required": [
"obligationKey"
]
},
{
"type": "object",
"properties": {
"period": {
"type": "object",
"properties": {
"from": {
"type": "string",
"minLength": 1
},
"through": {
"type": "string",
"minLength": 1
}
},
"required": [
"from",
"through"
]
}
},
"required": [
"period"
]
}
],
"properties": {
"contractId": {
"type": "string",
"minLength": 1
},
"activityKey": {
"type": "string",
"minLength": 1
},
"occurrenceKey": {
"type": "string",
"minLength": 1
},
"obligationKey": {
"type": "string",
"minLength": 1
},
"sourceFactId": {
"type": "string",
"minLength": 1
},
"effectiveAt": {
"type": "string",
"format": "date-time"
},
"phase": {
"const": "billing"
},
"dueDate": {
"type": "string",
"format": "date"
},
"exchangeRate": {
"type": "object",
"additionalProperties": false,
"required": [
"base",
"quote",
"date",
"numerator",
"denominator",
"evidence"
],
"description": "An evidenced exchange rate (1 base = numerator/denominator quote), e.g. from a bank statement. It overrides the shared rate store for this command; omit it to use the store.",
"properties": {
"base": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"quote": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"date": {
"type": "string",
"format": "date"
},
"numerator": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"denominator": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"evidence": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string"
}
}
}
}
}
},
"period": {
"type": "object",
"additionalProperties": false,
"required": [
"from",
"through"
],
"properties": {
"from": {
"type": "string",
"format": "date-time"
},
"through": {
"type": "string",
"format": "date-time"
}
}
},
"facts": {
"type": "object",
"maxProperties": 100,
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "object",
"additionalProperties": false,
"required": [
"occurrenceId"
],
"properties": {
"occurrenceId": {
"type": "string",
"minLength": 1
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"claimId",
"component"
],
"properties": {
"claimId": {
"type": "string",
"minLength": 1
},
"component": {
"type": "object",
"additionalProperties": false,
"required": [
"originLedgerId",
"accountCode"
],
"properties": {
"originLedgerId": {
"type": "string",
"minLength": 1
},
"accountCode": {
"type": "integer"
}
}
}
}
}
]
}
},
"evidence": {
"type": "object",
"additionalProperties": false,
"properties": {
"billing": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
},
"service": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
},
"acceptance": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
},
"economic": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
}
}
}
}
},
"payment": {
"type": "object",
"additionalProperties": false,
"required": [
"financialAccountId",
"direction",
"amount",
"currency",
"partyId",
"effectiveAt",
"sourceFactId",
"evidence"
],
"properties": {
"financialAccountId": {
"type": "string",
"minLength": 1
},
"direction": {
"enum": [
"in",
"out"
]
},
"amount": {
"type": "string",
"pattern": "^[1-9][0-9]*$"
},
"currency": {
"type": "string",
"minLength": 1
},
"partyId": {
"type": "string",
"minLength": 1
},
"effectiveAt": {
"type": "string",
"format": "date-time"
},
"sourceFactId": {
"type": "string",
"minLength": 1
},
"evidence": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"kind",
"ref"
],
"properties": {
"kind": {
"enum": [
"tap_message",
"x402_receipt",
"chain_tx",
"signed_doc",
"stripe_object",
"other"
]
},
"ref": {
"type": "string",
"minLength": 1
},
"signer": {
"type": "string",
"minLength": 1
}
}
}
}
}
}
}
}
}
}
]
},
"interpretation": {
"type": "object",
"additionalProperties": false,
"properties": {
"cid": {
"type": "string",
"minLength": 1
},
"promptVersion": {
"type": "string",
"minLength": 1
},
"buyer": {
"type": "string",
"minLength": 1,
"description": "Exact observed buyer; historical proposals without this field remain review cases."
},
"spans": {
"type": "array",
"maxItems": 1000,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"start": {
"type": "integer",
"minimum": 0
},
"end": {
"type": "integer",
"minimum": 1,
"maximum": 65536
},
"text": {
"type": "string",
"minLength": 1
}
},
"required": [
"start",
"end",
"text"
]
}
}
},
"required": [
"cid",
"promptVersion",
"spans"
]
},
"preview": {
"description": "Read-only ordinary activity or priced-rights preparation, when validation succeeds."
}
},
"oneOf": [
{
"properties": {
"disposition": {
"const": "ready"
},
"missing": {
"maxItems": 0
},
"lines": {
"minItems": 1
}
},
"required": [
"command",
"contract",
"currency",
"totalMinor"
]
},
{
"properties": {
"disposition": {
"enum": [
"needs_information",
"duplicate",
"unsupported"
]
}
},
"not": {
"required": [
"command"
]
}
}
]
},
"invoiceCorrection": {
"type": "object",
"additionalProperties": false,
"properties": {
"at": {
"type": "string",
"format": "date-time"
},
"principal": {
"type": "string"
},
"provenance": {
"const": "caller_selected_source_spans"
},
"choices": {
"type": "object",
"additionalProperties": false,
"properties": {
"headers": {
"type": "object",
"additionalProperties": false,
"properties": {
"vendor": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"buyer": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"externalId": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"date": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"currency": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
},
"total": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
}
},
"required": [
"vendor",
"buyer",
"externalId",
"date",
"currency",
"total"
]
},
"service": {
"enum": [
"delivered",
"not_delivered",
"unclear"
]
},
"rows": {
"type": "array",
"maxItems": 64,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"role": {
"enum": [
"charge",
"tax",
"summary",
"other",
"unclear"
]
},
"amount": {
"type": "string",
"pattern": "^(?:none|v[0-9]{1,3})$"
}
},
"required": [
"role",
"amount"
]
}
}
},
"required": [
"headers",
"service",
"rows"
]
}
},
"required": [
"at",
"principal",
"provenance",
"choices"
]
}
},
"required": [
"revision",
"at",
"principal"
]
}
},
"original": {
"type": "object",
"additionalProperties": false,
"properties": {
"documentId": {
"type": "string"
},
"cid": {
"type": "string"
},
"format": {
"enum": [
"markdown",
"text",
"document"
]
},
"provenance": {
"enum": [
"caller_supplied_unverified",
"registered_bytes"
]
}
},
"required": [
"documentId",
"cid",
"format",
"provenance"
]
},
"failure": {
"type": "object",
"additionalProperties": false,
"properties": {
"reason": {
"type": "string"
},
"retryable": {
"type": "boolean"
}
},
"required": [
"reason",
"retryable"
]
},
"lastFailure": {
"type": "object",
"additionalProperties": false,
"properties": {
"reason": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"attempt": {
"type": "integer",
"minimum": 1,
"maximum": 12
},
"at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"reason",
"retryable",
"attempt",
"at"
]
},
"relationship": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"enum": [
"transcription",
"summary",
"related_original"
]
},
"declaredBy": {
"type": "string"
},
"verification": {
"const": "unverified"
}
},
"required": [
"type",
"declaredBy",
"verification"
]
},
"uploads": {
"type": "object",
"additionalProperties": false,
"properties": {
"primary": {
"type": "object",
"additionalProperties": false,
"properties": {
"filename": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"contentType": {
"enum": [
"application/pdf",
"text/plain",
"text/markdown",
"text/csv",
"application/json",
"image/png",
"image/jpeg",
"image/webp"
]
},
"size": {
"type": "integer",
"minimum": 1,
"maximum": 10485760,
"description": "Exact byte length. Images are limited to 256 KiB; other files to 10 MiB."
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"status": {
"enum": [
"awaiting_upload",
"uploaded",
"expired"
]
},
"documentId": {
"type": "string"
},
"cid": {
"type": "string"
},
"url": {
"type": "string",
"description": "Short-lived upload credential. Send exact bytes to this URL with the returned method and contentType; no OAuth header is required. Present only in the response of the command that issued it (ingestions.start, ingestions.attach_original, ingestions.reissue_upload); replays and reads omit it, so call ingestions.reissue_upload for a fresh one."
},
"method": {
"const": "PUT",
"description": "Present when this response issued the upload URL."
}
},
"required": [
"filename",
"contentType",
"size",
"expiresAt",
"status"
]
},
"original": {
"type": "object",
"additionalProperties": false,
"properties": {
"filename": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"contentType": {
"enum": [
"application/pdf",
"text/plain",
"text/markdown",
"text/csv",
"application/json",
"image/png",
"image/jpeg",
"image/webp"
]
},
"size": {
"type": "integer",
"minimum": 1,
"maximum": 10485760,
"description": "Exact byte length. Images are limited to 256 KiB; other files to 10 MiB."
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"status": {
"enum": [
"awaiting_upload",
"uploaded",
"expired"
]
},
"documentId": {
"type": "string"
},
"cid": {
"type": "string"
},
"url": {
"type": "string",
"description": "Short-lived upload credential. Send exact bytes to this URL with the returned method and contentType; no OAuth header is required. Present only in the response of the command that issued it (ingestions.start, ingestions.attach_original, ingestions.reissue_upload); replays and reads omit it, so call ingestions.reissue_upload for a fresh one."
},
"method": {
"const": "PUT",
"description": "Present when this response issued the upload URL."
}
},
"required": [
"filename",
"contentType",
"size",
"expiresAt",
"status"
]
}
}
},
"revisions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"revision": {
"type": "integer",
"minimum": 1
},
"startedAt": {
"type": "string",
"format": "date-time"
},
"business": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"legalName": {
"type": [
"string",
"null"
]
}
},
"required": [
"name",
"legalName"
]
},
"completedAt": {
"type": "string",
"format": "date-time"
},
"status": {
"enum": [
"processing",
"completed",
"failed"
]
},
"sources": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"documentId": {
"type": "string"
},
"cid": {
"type": "string"
},
"format": {
"enum": [
"markdown",
"text",
"document"
]
},
"provenance": {
"enum": [
"caller_supplied_unverified",
"registered_bytes"
]
},
"role": {
"enum": [
"primary",
"original"
]
}
},
"required": [
"documentId",
"cid",
"format",
"provenance",
"role"
]
}
},
"failure": {
"type": "object",
"additionalProperties": false,
"properties": {
"reason": {
"type": "string"
},
"retryable": {
"type": "boolean"
}
},
"required": [
"reason",
"retryable"
]
},
"invoiceSelection": {
"type": "object",
"additionalProperties": false,
"description": "Observed source-span choices, bound to the committed UTF-8 extraction. Spans versions pick candidate indices; fields versions carry verified UTF-8 spans for header and payment-identity values. Choice probability is not financial accuracy or authorization.",
"properties": {
"textCid": {
"type": "string"
},
"promptVersion": {
"enum": [
"invoice-fields-v5",
"receipt-fields-v5",
"invoice-spans-v1",
"receipt-spans-v1",
"invoice-fields-v1",
"receipt-fields-v1",
"invoice-fields-v2",
"receipt-fields-v2",
"invoice-fields-v3",
"receipt-fields-v3",
"invoice-fields-v4",
"receipt-fields-v4"
]
},
"headers": {
"type": "object",
"additionalProperties": false,
"properties": {
"vendor": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
},
"buyer": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
},
"externalId": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
},
"date": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
},
"currency": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
},
"total": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
}
},
"required": [
"vendor",
"buyer",
"externalId",
"date",
"currency",
"total"
]
},
"provider": {
"type": "object",
"additionalProperties": false,
"description": "The model that chose header values and optional source-line amounts: Clef for spans versions, Clairic for fields versions.",
"properties": {
"name": {
"enum": [
"@cf/cloudflare/clef-flash",
"@cf/cloudflare/clef",
"@cf/cloudflare/clairic"
]
},
"version": {
"const": "unreported"
},
"inputTokens": {
"type": "integer",
"minimum": 0
},
"outputTokens": {
"type": "integer",
"minimum": 0
},
"requestBytes": {
"type": "integer",
"minimum": 0
},
"latencyMs": {
"type": "integer",
"minimum": 0
}
},
"required": [
"name",
"version",
"inputTokens",
"outputTokens",
"requestBytes",
"latencyMs"
]
},
"judgmentProvider": {
"type": "object",
"additionalProperties": false,
"description": "Fields versions only: the Clef model or bounded Flash-to-Clef cascade that answered currency, service, payment status and row judgments. Optional Clairic amount reads are accounted in provider.",
"properties": {
"name": {
"enum": [
"@cf/cloudflare/clef-flash",
"@cf/cloudflare/clef",
"@cf/cloudflare/clef-flash+clef/uncertain-groups-v1"
]
},
"version": {
"const": "unreported"
},
"inputTokens": {
"type": "integer",
"minimum": 0
},
"outputTokens": {
"type": "integer",
"minimum": 0
},
"requestBytes": {
"type": "integer",
"minimum": 0
},
"latencyMs": {
"type": "integer",
"minimum": 0
}
},
"required": [
"name",
"version",
"inputTokens",
"outputTokens",
"requestBytes",
"latencyMs"
]
},
"groupingProvider": {
"type": "object",
"additionalProperties": false,
"description": "Measured optional grouping attempt, including a failed attempt that retains physical rows.",
"properties": {
"name": {
"enum": [
"@cf/moonshotai/kimi-k2.6"
]
},
"version": {
"const": "unreported"
},
"inputTokens": {
"type": "integer",
"minimum": 0
},
"outputTokens": {
"type": "integer",
"minimum": 0
},
"requestBytes": {
"type": "integer",
"minimum": 0
},
"latencyMs": {
"type": "integer",
"minimum": 0
}
},
"required": [
"name",
"version",
"inputTokens",
"outputTokens",
"requestBytes",
"latencyMs"
]
},
"rowGroups": {
"type": "array",
"maxItems": 1024,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"firstRow": {
"type": "integer",
"minimum": 0,
"maximum": 1023
},
"lastRow": {
"type": "integer",
"minimum": 0,
"maximum": 1023
},
"anchorRow": {
"type": "integer",
"minimum": 0,
"maximum": 1023
},
"description": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"firstRow",
"lastRow",
"anchorRow"
]
}
},
"service": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
},
"payment": {
"type": "object",
"additionalProperties": false,
"properties": {
"status": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
},
"externalId": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
},
"last4": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
}
},
"required": [
"status",
"externalId",
"last4"
]
},
"rows": {
"type": "array",
"maxItems": 1024,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"role": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
},
"amount": {
"type": "object",
"additionalProperties": false,
"properties": {
"choice": {
"type": "string",
"maxLength": 32
},
"probability": {
"type": "string",
"pattern": "^(?:0(?:\\.[0-9]{1,15})?|1(?:\\.0{1,15})?)$"
},
"span": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"end": {
"type": "integer",
"minimum": 0,
"maximum": 65536
},
"text": {
"type": "string",
"maxLength": 65536
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
}
},
"required": [
"choice",
"probability"
]
}
},
"required": [
"role",
"amount"
]
}
}
},
"required": [
"textCid",
"promptVersion",
"headers",
"service",
"rows"
]
},
"extraction": {
"type": "object",
"additionalProperties": false,
"properties": {
"status": {
"enum": [
"not_required",
"extracted",
"incomplete"
]
},
"method": {
"enum": [
"provided_text",
"native_pdf",
"image_ocr",
"pdf_ocr"
]
},
"text": {
"type": "string",
"maxLength": 65536,
"description": "Returned only after source-document authorization; raw history contains annex references."
},
"textBytes": {
"type": "integer",
"minimum": 1,
"maximum": 65536
},
"source": {
"type": "object",
"additionalProperties": false,
"properties": {
"documentId": {
"type": "string"
},
"cid": {
"type": "string"
},
"format": {
"enum": [
"markdown",
"text",
"document"
]
},
"provenance": {
"enum": [
"caller_supplied_unverified",
"registered_bytes"
]
}
},
"required": [
"documentId",
"cid",
"format",
"provenance"
]
},
"derived": {
"type": "object",
"additionalProperties": false,
"properties": {
"cid": {
"type": "string"
}
},
"required": [
"cid"
]
},
"pageCount": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 50
},
"locations": {
"type": "array",
"maxItems": 50,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"page": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"start": {
"type": "integer",
"minimum": 0
},
"end": {
"type": "integer",
"minimum": 0
}
},
"required": [
"page",
"start",
"end"
]
}
},
"provider": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"version": {
"type": "string"
}
},
"required": [
"name",
"version"
]
},
"usage": {
"type": "object",
"additionalProperties": false,
"properties": {
"inputTokens": {
"type": "integer",
"minimum": 0
},
"outputTokens": {
"type": "integer",
"minimum": 0
},
"latencyMs": {
"type": "integer",
"minimum": 0
},
"conversionTokens": {
"type": "integer",
"minimum": 0,
"description": "Estimated native conversion tokens, distinct from inference usage."
}
},
"required": [
"inputTokens",
"outputTokens",
"latencyMs"
]
}
},
"required": [
"status",
"method",
"textBytes",
"source",
"derived",
"pageCount",
"locations",
"provider",
"usage"
]
},
"classification": {
"type": "object",
"additionalProperties": false,
"properties": {
"documentType": {
"enum": [
"invoice",
"receipt",
"agreement",
"statement_or_remittance",
"credit_or_correction",
"reminder",
"mixed",
"other",
"uncertain"
]
},
"probabilities": {
"type": "object",
"additionalProperties": false,
"properties": {
"invoice": {
"type": "string",
"description": "Decimal probability between 0 and 1."
},
"receipt": {
"type": "string",
"description": "Decimal probability between 0 and 1."
},
"agreement": {
"type": "string",
"description": "Decimal probability between 0 and 1."
},
"statement_or_remittance": {
"type": "string",
"description": "Decimal probability between 0 and 1."
},
"credit_or_correction": {
"type": "string",
"description": "Decimal probability between 0 and 1."
},
"reminder": {
"type": "string",
"description": "Decimal probability between 0 and 1."
},
"mixed": {
"type": "string",
"description": "Decimal probability between 0 and 1."
},
"other": {
"type": "string",
"description": "Decimal probability between 0 and 1."
},
"uncertain": {
"type": "string",
"description": "Decimal probability between 0 and 1."
}
},
"required": [
"invoice",
"receipt",
"agreement",
"statement_or_remittance",
"credit_or_correction",
"reminder",
"mixed",
"other",
"uncertain"
]
},
"model": {
"type": "string"
},
"modelVersion": {
"type": "string"
},
"promptVersion": {
"type": "string"
},
"confidence": {
"type": "string",
"description": "Distribution confidence, not calibrated accuracy or permission to act."
},
"invoiceRole": {
"type": "object",
"additionalProperties": false,
"properties": {
"role": {
"enum": [
"buyer",
"seller",
"neither",
"unclear"
]
},
"probabilities": {
"type": "object",
"additionalProperties": false,
"properties": {
"buyer": {
"type": "string"
},
"seller": {
"type": "string"
},
"neither": {
"type": "string"
},
"unclear": {
"type": "string"
}
},
"required": [
"buyer",
"seller",
"neither",
"unclear"
]
},
"confidence": {
"type": "string"
},
"promptVersion": {
"type": "string"
}
},
"required": [
"role",
"probabilities",
"confidence",
"promptVersion"
]
},
"usage": {
"type": "object",
"additionalProperties": false,
"properties": {
"inputTokens": {
"type": "integer",
"minimum": 0
},
"outputTokens": {
"type": "integer",
"minimum": 0
},
"requestBytes": {
"type": "integer",
"minimum": 1
},
"latencyMs": {
"type": "integer",
"minimum": 0
}
},
"required": [
"inputTokens",
"outputTokens",
"requestBytes",
"latencyMs"
]
}
},
"required": [
"documentType",
"probabilities",
"model",
"modelVersion",
"promptVersion"
]
}
},
"required": [
"revision",
"startedAt",
"business",
"status",
"sources"
]
}
}
},
"required": [
"ingestionId",
"createdAt",
"status",
"uploads",
"revisions"
],
"x-relative-urls": [
"/uploads/primary/url",
"/uploads/original/url"
]
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"cid": {
"type": "string"
}
}
}
}
}
}Example request
{
"name": "ingestions.start",
"input": {
"source": {
"type": "text",
"format": "markdown",
"text": "# Vendor invoice\nUSD 12.00"
}
},
"effective_at": "2026-09-01T00:00:00Z",
"idempotency_key": "ingestions.start-example-0"
}