From 505b0c2a8660da8d6776ba3b62b6eae228cab7c0 Mon Sep 17 00:00:00 2001 From: Becky Conning Date: Wed, 9 Sep 2026 10:13:53 +0100 Subject: [PATCH 1/2] Document POST /document-extractions Synchronous single-document extraction: one PDF plus a prompts object in the same multipart request, answered with one value per prompted field. Covers the validation and failure statuses (400/401/413/415/502), the statelessness contract, and the shared upload size bound. Co-Authored-By: Claude Fable 5 --- reference/public-http-api.yaml | 78 ++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/reference/public-http-api.yaml b/reference/public-http-api.yaml index 53c89fa..256b0c7 100644 --- a/reference/public-http-api.yaml +++ b/reference/public-http-api.yaml @@ -2035,6 +2035,84 @@ paths: description: Not Found '410': description: Gone — the file is tombstoned + /document-extractions: + post: + summary: Extract Document + operationId: post-document-extractions + description: >- + Synchronous single-document extraction: OCRs one PDF and answers one + value per prompt, in the same request. The document goes in a form + part named `file` (its part `Content-Type` must be + `application/pdf`); the prompts go in a form part named `prompts` — a + JSON object mapping each field to emit to the question answering it, + with at least one field. The 200 body is a JSON object holding + exactly the prompted fields, `null` where the document does not + answer. Nothing is stored: the document does not enter the tenant + file store, no pipeline is involved, and the same document can be + re-sent with different prompts — repeated extraction of identical + content skips re-OCR via a content-checksum cache, so re-asking is + fast. Documents that should feed a destination on every upload + belong in `POST /files` with a pipeline instead. The size bound is + the same one uploads get, so a document extractable here is also + uploadable and vice versa. + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + file: + type: string + format: binary + description: The PDF to extract from. + prompts: + type: string + description: >- + JSON object mapping each field to emit to the question + answering it, e.g. + `{"total_amount": "What is the total amount due?"}`. + Every value must be a string; at least one field is + required. + required: + - file + - prompts + responses: + '200': + description: >- + The extracted values, one per prompted field, `null` where the + document does not answer. + content: + application/json: + schema: + type: object + additionalProperties: true + examples: + example-1: + value: + invoice_number: INV-2026-0342 + vendor: Meridian Cooling Services Ltd + total_amount: USD 4,875.50 + execution_date: null + '400': + description: >- + Bad Request — a form part is missing, the `prompts` part is not a + JSON object of string questions, or it names no fields; the body + names the problem. + '401': + description: Unauthorized + '413': + description: >- + Payload Too Large — the document exceeds the deployment's upload + byte limit. + '415': + description: >- + Unsupported Media Type — the `file` part's `Content-Type` is not + `application/pdf`. + '502': + description: >- + Bad Gateway — the OCR or extraction service failed; the body + carries the reason. components: schemas: connector: From be43ac53ab23d7f06780b6222cbad18dbf0d5124 Mon Sep 17 00:00:00 2001 From: Becky Conning Date: Wed, 9 Sep 2026 17:08:45 +0100 Subject: [PATCH 2/2] Document the schema part on POST /document-extractions Co-Authored-By: Claude Fable 5 --- reference/public-http-api.yaml | 44 ++++++++++++++++++++++++---------- 1 file changed, 31 insertions(+), 13 deletions(-) diff --git a/reference/public-http-api.yaml b/reference/public-http-api.yaml index 256b0c7..0b42396 100644 --- a/reference/public-http-api.yaml +++ b/reference/public-http-api.yaml @@ -2040,14 +2040,19 @@ paths: summary: Extract Document operationId: post-document-extractions description: >- - Synchronous single-document extraction: OCRs one PDF and answers one - value per prompt, in the same request. The document goes in a form + Synchronous single-document extraction: OCRs one PDF and answers the + requested fields, in the same request. The document goes in a form part named `file` (its part `Content-Type` must be - `application/pdf`); the prompts go in a form part named `prompts` — a - JSON object mapping each field to emit to the question answering it, - with at least one field. The 200 body is a JSON object holding - exactly the prompted fields, `null` where the document does not - answer. Nothing is stored: the document does not enter the tenant + `application/pdf`), accompanied by exactly one of two shapes: a + `prompts` part — a JSON object mapping each field to emit to the + question answering it, with at least one field, answered as a JSON + object holding exactly the prompted fields with `null` where the + document does not answer — or a `schema` part — a JSON Schema for an + object with at least one property, whose `description`s carry the + questions, answered with a JSON object conforming to that schema + (enforced by the extraction model's strict structured-output mode). + The schema shape makes the endpoint request-compatible with the + studio document-extractions contract. Nothing is stored: the document does not enter the tenant file store, no pipeline is involved, and the same document can be re-sent with different prompts — repeated extraction of identical content skips re-OCR via a content-checksum cache, so re-asking is @@ -2073,10 +2078,20 @@ paths: answering it, e.g. `{"total_amount": "What is the total amount due?"}`. Every value must be a string; at least one field is + required. Exactly one of `prompts` and `schema` is required. + schema: + type: string + description: >- + JSON Schema (serialized, at most 5000 bytes) for an + object with at least one property; property + `description`s carry the extraction questions and the + response conforms to this schema. Exactly one of + `prompts` and `schema` is required. Deployments without + a structured-output provider configured answer schema + requests with 502. required: - file - - prompts responses: '200': description: >- @@ -2096,9 +2111,11 @@ paths: execution_date: null '400': description: >- - Bad Request — a form part is missing, the `prompts` part is not a - JSON object of string questions, or it names no fields; the body - names the problem. + Bad Request — a form part is missing, both or neither of + `prompts` and `schema` were sent, the `prompts` part is not a + JSON object of string questions or names no fields, or the + `schema` part is not a JSON Schema for a non-empty object or + exceeds 5000 bytes; the body names the problem. '401': description: Unauthorized '413': @@ -2111,8 +2128,9 @@ paths: `application/pdf`. '502': description: >- - Bad Gateway — the OCR or extraction service failed; the body - carries the reason. + Bad Gateway — the OCR or extraction service failed, or a + `schema` request reached a deployment with no structured-output + provider configured; the body carries the reason. components: schemas: connector: