{ "openapi": "3.1.0", "info": { "title": "AIDE Gateway", "description": "AIDE Gateway — proxy surface + Temporal job surface.", "version": "1.0.0" }, "paths": { "/v2/parse": { "post": { "tags": [ "Parse" ], "summary": "ADE Parse", "description": "Parse a document and return the parse response inline.", "operationId": "parse_run_sync", "responses": { "200": { "description": "The parse response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseResponse" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "206": { "description": "Partial success (some pages failed to parse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseResponse" } } } } }, "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "document": { "type": "string", "format": "binary", "description": "The file to parse. The file must be a PDF or image; see the list of [supported file types](https://docs.landing.ai/dpt3/file-types). Provide either `document` or `document_url`, not both." }, "document_url": { "type": "string", "description": "A publicly accessible URL to the file to parse. The file must be a PDF or image; see the list of [supported file types](https://docs.landing.ai/dpt3/file-types). Provide either `document` or `document_url`, not both." }, "model": { "type": "string", "description": "The DPT-3 model snapshot to use for this request. Accepts a dated snapshot (for example, `dpt-3-pro-20260710`), the `dpt-3-pro-latest` alias, or the bare `dpt-3-pro` family name (equivalent to `dpt-3-pro-latest`). Defaults to the latest DPT-3 Pro snapshot." }, "options": { "additionalProperties": false, "properties": { "pages": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Pages" }, "blocks": { "$ref": "#/components/schemas/BlocksOptions" }, "atomic_grounding": { "default": true, "description": "Include the fine-grained `atomic_grounding` array on leaf elements. Set `false` to omit the field entirely from every node.", "title": "Atomic Grounding", "type": "boolean" }, "inline_markdown": { "default": false, "description": "Include each node's slice of the document `markdown` inline as a `markdown` field on every structure node: the document root, each page, and each element (including table cells). `atomic_grounding` entries do not carry it.", "title": "Inline Markdown", "type": "boolean" }, "password": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Password for encrypted PDFs. Not currently supported — providing a value returns a 422 error; decrypt the file before uploading.", "title": "Password" } }, "title": "ParseOptions", "type": "object", "description": "Optional object that customizes the parse. Use it to select which pages to process, adjust how content appears in the Markdown, or control how much detail the response includes. Sent as a JSON-serialized string in form data." } } } } } } } }, "/v2/parse/jobs": { "post": { "tags": [ "Parse" ], "summary": "ADE Parse Jobs", "operationId": "parse_create_job", "responses": { "202": { "description": "Job created", "content": { "application/json": { "schema": { "type": "object", "required": [ "job_id", "status", "created_at" ], "properties": { "job_id": { "type": "string", "description": "The unique identifier for the created parse job. Poll ``GET /v2/parse/jobs/{job_id}`` for its status and result. Format: ``-<26-character Crockford base32 ULID>`` matching ``^(parse|extract)-[0-9a-hjkmnp-tv-z]{26}$``. Opaque, server-minted, and stable for the life of the job — the same id is returned on the sync response, the async 202, and every poll. Treat it as opaque; older id formats remain accepted indefinitely and are never re-issued." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "description": "The job's status at creation — normally ``pending`` (a just-created job that is still running is reported as ``pending``), but may already be a terminal ``completed`` / ``failed`` if the job finished before the create response was rendered." }, "created_at": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp for when the job was created." } } } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Parse a document asynchronously. Returns a job ID; use it to poll for the job's status and retrieve the parse result once processing completes.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "document": { "type": "string", "format": "binary", "description": "The file to parse. The file must be a PDF or image; see the list of [supported file types](https://docs.landing.ai/dpt3/file-types). Provide either `document` or `document_url`, not both." }, "document_url": { "type": "string", "description": "A publicly accessible URL to the file to parse. The file must be a PDF or image; see the list of [supported file types](https://docs.landing.ai/dpt3/file-types). Provide either `document` or `document_url`, not both." }, "model": { "type": "string", "description": "The DPT-3 model snapshot to use for this request. Accepts a dated snapshot (for example, `dpt-3-pro-20260710`), the `dpt-3-pro-latest` alias, or the bare `dpt-3-pro` family name (equivalent to `dpt-3-pro-latest`). Defaults to the latest DPT-3 Pro snapshot." }, "options": { "additionalProperties": false, "properties": { "pages": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Pages" }, "blocks": { "$ref": "#/components/schemas/BlocksOptions" }, "atomic_grounding": { "default": true, "description": "Include the fine-grained `atomic_grounding` array on leaf elements. Set `false` to omit the field entirely from every node.", "title": "Atomic Grounding", "type": "boolean" }, "inline_markdown": { "default": false, "description": "Include each node's slice of the document `markdown` inline as a `markdown` field on every structure node: the document root, each page, and each element (including table cells). `atomic_grounding` entries do not carry it.", "title": "Inline Markdown", "type": "boolean" }, "password": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Password for encrypted PDFs. Not currently supported — providing a value returns a 422 error; decrypt the file before uploading.", "title": "Password" } }, "title": "ParseOptions", "type": "object", "description": "Optional object that customizes the parse. Use it to select which pages to process, adjust how content appears in the Markdown, or control how much detail the response includes. Sent as a JSON-serialized string in form data." }, "output_save_url": { "type": "string", "description": "Public URL the full response is delivered to; the API response then carries ``output_url`` instead of inline data." }, "service_tier": { "type": "string", "enum": [ "standard", "priority" ], "description": "Async service tier (``POST /jobs`` only). ``priority`` runs in the fast lane at the sync billing rate; absent → ``standard``." } } } } } } }, "get": { "tags": [ "Parse" ], "summary": "ADE List Parse Jobs", "operationId": "parse_list_jobs", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Page number (0-indexed).", "default": 0, "title": "Page" }, "description": "Page number (0-indexed)." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of items per page.", "default": 10, "title": "Page Size" }, "description": "Number of items per page." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by job status.", "title": "Status" }, "description": "Filter by job status." } ], "responses": { "200": { "description": "The caller's jobs, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "description": "The caller's parse jobs for this page, newest first.", "items": { "type": "object", "properties": { "job_id": { "type": "string", "description": "The unique identifier for the parse job. Format: ``-<26-character Crockford base32 ULID>`` matching ``^(parse|extract)-[0-9a-hjkmnp-tv-z]{26}$``. Opaque, server-minted, and stable for the life of the job — the same id is returned on the sync response, the async 202, and every poll. Treat it as opaque; older id formats remain accepted indefinitely and are never re-issued." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "description": "The job's current status: ``pending``, ``processing``, ``completed``, or ``failed``." }, "created_at": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp for when the job was created." }, "completed_at": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp for when the job finished, if terminal." }, "model_version": { "type": [ "string", "null" ], "description": "The model snapshot used to parse the document." }, "failure_reason": { "type": [ "string", "null" ], "description": "The reason the job failed. Present only when ``status`` is ``failed``." } } } }, "page": { "type": "integer", "description": "The 0-indexed page number." }, "page_size": { "type": "integer", "description": "Items per page." }, "has_more": { "type": "boolean", "description": "Whether more jobs exist beyond this page; request the next ``page`` to fetch them." } } } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/parse/jobs/{job_id}": { "get": { "tags": [ "Parse" ], "summary": "ADE Get Parse Jobs", "description": "Get the status of an async parse job. Once the job has ``completed``, ``result`` carries the parse response (or ``output_url`` when ``output_save_url`` was set). Partial success (some pages failed) is reported in ``result.metadata.failed_pages``.", "operationId": "parse_get_job", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The identifier of the job to retrieve, as returned by the create-job request.", "title": "Job Id" }, "description": "The identifier of the job to retrieve, as returned by the create-job request." } ], "responses": { "200": { "description": "Job status / result", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "The unique identifier for this parse job. Format: ``-<26-character Crockford base32 ULID>`` matching ``^(parse|extract)-[0-9a-hjkmnp-tv-z]{26}$``. Opaque, server-minted, and stable for the life of the job — the same id is returned on the sync response, the async 202, and every poll. Treat it as opaque; older id formats remain accepted indefinitely and are never re-issued." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "description": "The job's current status: ``pending``, ``processing``, ``completed``, or ``failed``." }, "created_at": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp for when the job was created." }, "completed_at": { "type": "string", "description": "ISO-8601 timestamp; present once the job is terminal." }, "progress": { "type": "number", "description": "Job completion as a decimal from 0 (not started) to 1 (complete). Present while ``processing``." }, "result": { "anyOf": [ { "$ref": "#/components/schemas/ParseResponse" }, { "type": "null" } ], "description": "The parse response, present once the job has ``completed`` and ``output_save_url`` was not set. When ``output_save_url`` was set, the result is delivered there and ``output_url`` is returned instead." }, "output_url": { "type": [ "string", "null" ], "description": "The URL the result was delivered to. Present once the job has ``completed`` and ``output_save_url`` was set, instead of inline ``result``." }, "error": { "type": "object", "description": "Present once the job has ``failed`` — the failure code + message.", "properties": { "code": { "type": "string", "description": "Stable error code." }, "message": { "type": "string" } } } } } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/extract": { "post": { "tags": [ "Extract" ], "summary": "ADE Extract", "description": "Extract structured data from a Markdown document according to a JSON schema, with character-span grounding into the source Markdown. Runs synchronously and returns the result inline.", "operationId": "v2-extract_run_sync", "responses": { "200": { "description": "v2-extract result", "content": { "application/json": { "schema": { "description": "Result returned by V2ExtractOperationWorkflow — the ``/v2/extract``\nresponse body (``docs/extract-v2-proposal.md`` → Response).\n\n``extraction`` and ``extraction_metadata`` mirror each other structurally:\nleaf values in ``extraction`` are replaced by ``ExtractionFieldMetadata``\nobjects in ``extraction_metadata``.", "properties": { "extraction": { "additionalProperties": true, "description": "Extracted values conforming to the request ``schema``.", "title": "Extraction", "type": "object" }, "extraction_metadata": { "additionalProperties": true, "description": "Per-field metadata, mirroring ``extraction`` with leaf values replaced by ``{value, ranges}`` objects.", "title": "Extraction Metadata", "type": "object" }, "markdown": { "description": "Echoed input markdown.", "title": "Markdown", "type": "string" }, "metadata": { "$ref": "#/components/schemas/V2ExtractMetadata", "description": "Request metadata (job_id, model_version, duration_ms, doc_id, billing)." }, "schema_violation_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Set when ``options.strict`` is false and the schema contained fields the model could not extract — the extraction is partial.", "title": "Schema Violation Error" }, "warnings": { "description": "Non-fatal warnings emitted during extraction.", "items": { "additionalProperties": true, "type": "object" }, "title": "Warnings", "type": "array" } }, "required": [ "extraction", "extraction_metadata", "markdown", "metadata" ], "title": "V2ExtractResult", "type": "object" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Input to V2ExtractOperationWorkflow.\n\nProvide the markdown as an inline ``markdown`` string, as a multipart file\npart named ``markdown`` (for large inputs — the gateway stages the upload\ninternally), or via a public ``markdown_url``. Exactly one source must be\nsupplied.", "properties": { "schema": { "additionalProperties": true, "description": "JSON Schema describing the fields to extract. The schema must be an object type with a ``properties`` map of field names to their types and descriptions.", "example": { "properties": { "revenue": { "description": "Q1 revenue figure", "type": "string" }, "summary": { "description": "Executive summary", "type": "string" } }, "type": "object" }, "title": "Schema", "type": "object" }, "markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Markdown string to extract from, or a multipart FILE part carrying the markdown (large inputs — uploads are staged by the gateway). Can come from any source — LandingAI parse output, a third-party parser, or hand-authored text. When the markdown was produced by ``POST /v2/parse``, it ends with a ```` comment that the service reads automatically and echoes as ``metadata.doc_id``.", "title": "Markdown" }, "markdown_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to fetch the markdown from. Must be a public http(s) URL; private/loopback IPs are rejected at submit time.", "title": "Markdown Url" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The version of the model to use for extraction. Use ``extract-latest`` to use the latest version.", "title": "Model" }, "options": { "anyOf": [ { "$ref": "#/components/schemas/V2ExtractOptions" }, { "type": "null" } ], "default": null, "description": "Extraction options (``strict``). Omit for defaults." } }, "required": [ "schema" ], "title": "V2ExtractRequest", "type": "object" } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "schema": { "additionalProperties": true, "description": "JSON Schema describing the fields to extract. The schema must be an object type with a ``properties`` map of field names to their types and descriptions. JSON-serialized string in form data.", "example": { "properties": { "revenue": { "description": "Q1 revenue figure", "type": "string" }, "summary": { "description": "Executive summary", "type": "string" } }, "type": "object" }, "title": "Schema", "type": "object" }, "markdown": { "anyOf": [ { "type": "string", "description": "Markdown string to extract from, or a multipart FILE part carrying the markdown (large inputs — uploads are staged by the gateway). Can come from any source — LandingAI parse output, a third-party parser, or hand-authored text. When the markdown was produced by ``POST /v2/parse``, it ends with a ```` comment that the service reads automatically and echoes as ``metadata.doc_id``." }, { "type": "string", "format": "binary", "description": "File upload." } ] }, "markdown_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to fetch the markdown from. Must be a public http(s) URL; private/loopback IPs are rejected at submit time. JSON-serialized string in form data.", "title": "Markdown Url" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The version of the model to use for extraction. Use ``extract-latest`` to use the latest version. JSON-serialized string in form data.", "title": "Model" }, "options": { "anyOf": [ { "$ref": "#/components/schemas/V2ExtractOptions" }, { "type": "null" } ], "default": null, "description": "Extraction options (``strict``). Omit for defaults. JSON-serialized string in form data." } }, "required": [ "schema" ] } } } } } }, "/v2/extract/jobs": { "post": { "tags": [ "Extract" ], "summary": "ADE Extract Jobs", "operationId": "v2-extract_create_job", "responses": { "202": { "description": "Job created", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "The unique identifier for this v2-extract job. Format: ``extract-<26-character Crockford base32 ULID>`` (``[0-9a-hjkmnp-tv-z]{26}`` tail). Opaque, server-minted, and stable for the life of the job — the same id is returned on the sync response, the async 202, and every poll. Treat it as opaque; older id formats remain accepted indefinitely and are never re-issued." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "created_at": { "type": [ "string", "null" ] } } } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Extract structured data from a Markdown document according to a JSON schema, with character-span grounding into the source Markdown. Runs asynchronously and returns a job ID; use it to poll for status and retrieve the result once processing completes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Input to V2ExtractOperationWorkflow.\n\nProvide the markdown as an inline ``markdown`` string, as a multipart file\npart named ``markdown`` (for large inputs — the gateway stages the upload\ninternally), or via a public ``markdown_url``. Exactly one source must be\nsupplied.", "properties": { "schema": { "additionalProperties": true, "description": "JSON Schema describing the fields to extract. The schema must be an object type with a ``properties`` map of field names to their types and descriptions.", "example": { "properties": { "revenue": { "description": "Q1 revenue figure", "type": "string" }, "summary": { "description": "Executive summary", "type": "string" } }, "type": "object" }, "title": "Schema", "type": "object" }, "markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Markdown string to extract from, or a multipart FILE part carrying the markdown (large inputs — uploads are staged by the gateway). Can come from any source — LandingAI parse output, a third-party parser, or hand-authored text. When the markdown was produced by ``POST /v2/parse``, it ends with a ```` comment that the service reads automatically and echoes as ``metadata.doc_id``.", "title": "Markdown" }, "markdown_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to fetch the markdown from. Must be a public http(s) URL; private/loopback IPs are rejected at submit time.", "title": "Markdown Url" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The version of the model to use for extraction. Use ``extract-latest`` to use the latest version.", "title": "Model" }, "options": { "anyOf": [ { "$ref": "#/components/schemas/V2ExtractOptions" }, { "type": "null" } ], "default": null, "description": "Extraction options (``strict``). Omit for defaults." }, "output_save_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to save the result to — e.g. a presigned S3 PUT URL. Async jobs only. When set, the finished result is delivered (HTTP PUT) to this URL and the completed job reports ``output_url`` instead of an inline ``result``. Must be a public http(s) URL; private/loopback IPs are rejected at submit time.", "title": "Output Save Url" }, "service_tier": { "anyOf": [ { "type": "string", "enum": [ "standard", "priority" ] }, { "type": "null" } ], "description": "Async service tier. ``priority`` runs in the fast lane at the sync billing rate; absent → ``standard``." } }, "required": [ "schema" ], "title": "V2ExtractRequest", "type": "object" } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "schema": { "additionalProperties": true, "description": "JSON Schema describing the fields to extract. The schema must be an object type with a ``properties`` map of field names to their types and descriptions. JSON-serialized string in form data.", "example": { "properties": { "revenue": { "description": "Q1 revenue figure", "type": "string" }, "summary": { "description": "Executive summary", "type": "string" } }, "type": "object" }, "title": "Schema", "type": "object" }, "markdown": { "anyOf": [ { "type": "string", "description": "Markdown string to extract from, or a multipart FILE part carrying the markdown (large inputs — uploads are staged by the gateway). Can come from any source — LandingAI parse output, a third-party parser, or hand-authored text. When the markdown was produced by ``POST /v2/parse``, it ends with a ```` comment that the service reads automatically and echoes as ``metadata.doc_id``." }, { "type": "string", "format": "binary", "description": "File upload." } ] }, "markdown_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to fetch the markdown from. Must be a public http(s) URL; private/loopback IPs are rejected at submit time. JSON-serialized string in form data.", "title": "Markdown Url" }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The version of the model to use for extraction. Use ``extract-latest`` to use the latest version. JSON-serialized string in form data.", "title": "Model" }, "options": { "anyOf": [ { "$ref": "#/components/schemas/V2ExtractOptions" }, { "type": "null" } ], "default": null, "description": "Extraction options (``strict``). Omit for defaults. JSON-serialized string in form data." }, "output_save_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to save the result to — e.g. a presigned S3 PUT URL. Async jobs only. When set, the finished result is delivered (HTTP PUT) to this URL and the completed job reports ``output_url`` instead of an inline ``result``. Must be a public http(s) URL; private/loopback IPs are rejected at submit time. JSON-serialized string in form data.", "title": "Output Save Url" }, "service_tier": { "anyOf": [ { "type": "string", "enum": [ "standard", "priority" ] }, { "type": "null" } ], "description": "Async service tier. ``priority`` runs in the fast lane at the sync billing rate; absent → ``standard``." } }, "required": [ "schema" ] } } } } }, "get": { "tags": [ "Extract" ], "summary": "ADE List Extract Jobs", "operationId": "v2-extract_list_jobs", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Page number (0-indexed).", "default": 0, "title": "Page" }, "description": "Page number (0-indexed)." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of items per page.", "default": 10, "title": "Page Size" }, "description": "Number of items per page." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by job status.", "title": "Status" }, "description": "Filter by job status." } ], "responses": { "200": { "description": "The caller's jobs, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "job_id": { "type": "string", "description": "The unique identifier for this v2-extract job. Format: ``extract-<26-character Crockford base32 ULID>`` (``[0-9a-hjkmnp-tv-z]{26}`` tail). Opaque, server-minted, and stable for the life of the job — the same id is returned on the sync response, the async 202, and every poll. Treat it as opaque; older id formats remain accepted indefinitely and are never re-issued." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "created_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "model_version": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] } } } }, "page": { "type": "integer" }, "page_size": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "List your Extract jobs, newest first." } }, "/v2/extract/jobs/{job_id}": { "get": { "tags": [ "Extract" ], "summary": "ADE Get Extract Jobs", "description": "Get the status of an async Extract job, including its result once the job has completed.", "operationId": "v2-extract_get_job", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The identifier of the job to retrieve, as returned by the create-job request.", "title": "Job Id" }, "description": "The identifier of the job to retrieve, as returned by the create-job request." } ], "responses": { "200": { "description": "Job status / result", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "The unique identifier for this v2-extract job. Format: ``extract-<26-character Crockford base32 ULID>`` (``[0-9a-hjkmnp-tv-z]{26}`` tail). Opaque, server-minted, and stable for the life of the job — the same id is returned on the sync response, the async 202, and every poll. Treat it as opaque; older id formats remain accepted indefinitely and are never re-issued." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "created_at": { "type": [ "string", "null" ] }, "completed_at": { "type": "string", "description": "Present once the job is terminal." }, "progress": { "type": "number", "minimum": 0, "maximum": 1, "description": "Job completion as a decimal from 0 (not started) to 1 (complete). Present while ``processing``." }, "result": { "anyOf": [ { "description": "Result returned by V2ExtractOperationWorkflow — the ``/v2/extract``\nresponse body (``docs/extract-v2-proposal.md`` → Response).\n\n``extraction`` and ``extraction_metadata`` mirror each other structurally:\nleaf values in ``extraction`` are replaced by ``ExtractionFieldMetadata``\nobjects in ``extraction_metadata``.", "properties": { "extraction": { "additionalProperties": true, "description": "Extracted values conforming to the request ``schema``.", "title": "Extraction", "type": "object" }, "extraction_metadata": { "additionalProperties": true, "description": "Per-field metadata, mirroring ``extraction`` with leaf values replaced by ``{value, ranges}`` objects.", "title": "Extraction Metadata", "type": "object" }, "markdown": { "description": "Echoed input markdown.", "title": "Markdown", "type": "string" }, "metadata": { "$ref": "#/components/schemas/V2ExtractMetadata", "description": "Request metadata (job_id, model_version, duration_ms, doc_id, billing)." }, "schema_violation_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Set when ``options.strict`` is false and the schema contained fields the model could not extract — the extraction is partial.", "title": "Schema Violation Error" }, "warnings": { "description": "Non-fatal warnings emitted during extraction.", "items": { "additionalProperties": true, "type": "object" }, "title": "Warnings", "type": "array" } }, "required": [ "extraction", "extraction_metadata", "markdown", "metadata" ], "title": "V2ExtractResult", "type": "object" }, { "type": "null" } ], "description": "Present once status is ``completed`` and ``output_save_url`` was not set. When ``output_save_url`` was set, the result is delivered there and ``output_url`` is returned instead." }, "error": { "type": "object", "description": "Present once status is ``failed``.", "properties": { "code": { "type": "string", "description": "Stable error code (``internal_error`` when unmapped)." }, "message": { "type": "string" } } }, "output_url": { "type": [ "string", "null" ], "description": "The URL the result was delivered to. Present once the job has ``completed`` and ``output_save_url`` was set, instead of inline ``result``." } } } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found (e.g. no such job).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/workflow": { "post": { "tags": [ "v2-workflow" ], "summary": "Run v2-workflow (sync)", "description": "Run synchronously and return the result inline.\n\nAccepts ``application/json`` (the request fields as the body) or\n``multipart/form-data`` (file fields are staged automatically).\n\nReturns **504** if the work does not finish within the wait\nwindow — long-running work belongs on the async ``POST\n{path}/jobs`` route, which returns 202 immediately and is polled\nvia ``GET {path}/jobs/{job_id}``. On a 504 the workflow is\nCANCELLED (a sync caller can never collect the result); a retry\nstarts the work over as a fresh job.", "operationId": "v2-workflow_run_sync", "responses": { "200": { "description": "v2-workflow result", "content": { "application/json": { "schema": { "description": "Result returned by V2WorkflowOperationWorkflow.\n\n``output`` is keyed by step name (or by caller-chosen projection keys when\n``output`` was provided in the request). For the ``\"parse-extract\"`` pipeline\nwith no projection, the keys are ``\"parse-extract\"`` → ``{parse, extract, ground}``:\n\n* ``output[\"parse-extract\"][\"parse\"]`` — full parse response (markdown,\n structure with per-node grounding inline, metadata).\n* ``output[\"parse-extract\"][\"extract\"]`` — extraction + ``extraction_metadata``\n with ``{value, ranges}`` leaves.\n* ``output[\"parse-extract\"][\"ground\"]`` — a tree MIRRORING\n ``extraction_metadata``: each ``{value, ranges}`` leaf is replaced by its\n resolved block-hit list (``[{block_id, type, parent_id?, grounding,\n atomic_grounding?}]`` — the same shape ``/v2/ground`` returns; see\n ``V2GroundResult.grounding`` for the full field-level contract), or\n ``null`` for a synthesised value. Nested objects and arrays keep their\n shape, so ``ground.issuer.name`` parallels\n ``extraction_metadata.issuer.name``. Resolved server-side — no\n client-side span lookup needed.\n\nReferences into the results use the ``$output.....`` grammar\n(see ``output`` field of the request).", "properties": { "output": { "additionalProperties": true, "description": "Step results keyed by step name, or a caller-defined projection. For ``parse-extract`` with no projection: ``{\"parse-extract\": {parse, extract, ground}}``.", "title": "Output", "type": "object" }, "metadata": { "$ref": "#/components/schemas/V2WorkflowMetadata", "description": "Request metadata (job_id, duration_ms, billing)." } }, "required": [ "output", "metadata" ], "title": "V2WorkflowResult", "type": "object" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Input to V2WorkflowOperationWorkflow.\n\nPhase 1 API design (``docs/pipeline-v2-proposal.md``):\n\n``inputs`` declares named document sources. Each entry binds a logical name\nto a binary upload (via ``document``, the multipart field name) or a URL\n(via ``document_url``). The gateway stages uploads internally before the\nworkflow runs.\n\n``steps`` is a one-element array containing a prebuilt step. Its ``document``\nfield references an entry from ``inputs`` (``\"$inputs.\"``). The ``schema``\nfield carries the JSON Schema for the extract stage.\n\n``output`` is an optional projection map. Each key maps to a ``$output.``\nreference into the step results. Omitted → the full results tree is returned\nunder ``output``.\n\nExample — minimal request (parse-extract, default options)::\n\n inputs = {\"report\": {\"document\": \"report_pdf\"}}\n steps = [{\"name\": \"parse-extract\", \"document\": \"$inputs.report\",\n \"schema\": {\"type\": \"object\", \"properties\": {\"revenue\": {\"type\": \"string\"}}}}]\n report_pdf = [binary]", "properties": { "inputs": { "additionalProperties": { "$ref": "#/components/schemas/WorkflowDocumentInput" }, "description": "Named document sources. Each key is a logical name referenced from steps as ``\"$inputs.\"``. The gateway stages binary multipart uploads internally before the workflow runs.", "example": { "report": { "document": "report_pdf" } }, "title": "Inputs", "type": "object" }, "steps": { "description": "Phase 1: a single prebuilt-pipeline step (name must be ``\"parse-extract\"``). Its result appears in ``output`` under the step's name.", "example": [ { "document": "$inputs.report", "name": "parse-extract", "schema": { "properties": { "revenue": { "type": "string" } }, "type": "object" } } ], "items": { "$ref": "#/components/schemas/PrebuiltWorkflowStep" }, "title": "Steps", "type": "array" }, "output": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional projection map. Keys are caller-chosen response field names; values are ``$output.....`` references. Omitted → full results tree returned under ``output``.", "example": { "revenue": "$output.parse-extract.extract.extraction.revenue", "revenue_blocks": "$output.parse-extract.ground.revenue" }, "title": "Output" } }, "required": [ "inputs", "steps" ], "title": "V2WorkflowRequest", "type": "object" } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "inputs": { "additionalProperties": { "$ref": "#/components/schemas/WorkflowDocumentInput" }, "description": "Named document sources. Each key is a logical name referenced from steps as ``\"$inputs.\"``. The gateway stages binary multipart uploads internally before the workflow runs. JSON-serialized string in form data.", "example": { "report": { "document": "report_pdf" } }, "title": "Inputs", "type": "object" }, "steps": { "description": "Phase 1: a single prebuilt-pipeline step (name must be ``\"parse-extract\"``). Its result appears in ``output`` under the step's name. JSON-serialized string in form data.", "example": [ { "document": "$inputs.report", "name": "parse-extract", "schema": { "properties": { "revenue": { "type": "string" } }, "type": "object" } } ], "items": { "$ref": "#/components/schemas/PrebuiltWorkflowStep" }, "title": "Steps", "type": "array" }, "output": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional projection map. Keys are caller-chosen response field names; values are ``$output.....`` references. Omitted → full results tree returned under ``output``. JSON-serialized string in form data.", "example": { "revenue": "$output.parse-extract.extract.extraction.revenue", "revenue_blocks": "$output.parse-extract.ground.revenue" }, "title": "Output" } }, "required": [ "inputs", "steps" ] } } } } } }, "/v2/workflow/jobs": { "post": { "tags": [ "v2-workflow" ], "summary": "Create v2-workflow job", "operationId": "v2-workflow_create_job", "responses": { "202": { "description": "Job created", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "The unique identifier for this v2-workflow job. Format: ``v2-workflow-<26-character Crockford base32 ULID>`` (``[0-9a-hjkmnp-tv-z]{26}`` tail). Opaque, server-minted, and stable for the life of the job — the same id is returned on the sync response, the async 202, and every poll. Treat it as opaque; older id formats remain accepted indefinitely and are never re-issued." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "created_at": { "type": [ "string", "null" ] } } } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Input to V2WorkflowOperationWorkflow.\n\nPhase 1 API design (``docs/pipeline-v2-proposal.md``):\n\n``inputs`` declares named document sources. Each entry binds a logical name\nto a binary upload (via ``document``, the multipart field name) or a URL\n(via ``document_url``). The gateway stages uploads internally before the\nworkflow runs.\n\n``steps`` is a one-element array containing a prebuilt step. Its ``document``\nfield references an entry from ``inputs`` (``\"$inputs.\"``). The ``schema``\nfield carries the JSON Schema for the extract stage.\n\n``output`` is an optional projection map. Each key maps to a ``$output.``\nreference into the step results. Omitted → the full results tree is returned\nunder ``output``.\n\nExample — minimal request (parse-extract, default options)::\n\n inputs = {\"report\": {\"document\": \"report_pdf\"}}\n steps = [{\"name\": \"parse-extract\", \"document\": \"$inputs.report\",\n \"schema\": {\"type\": \"object\", \"properties\": {\"revenue\": {\"type\": \"string\"}}}}]\n report_pdf = [binary]", "properties": { "inputs": { "additionalProperties": { "$ref": "#/components/schemas/WorkflowDocumentInput" }, "description": "Named document sources. Each key is a logical name referenced from steps as ``\"$inputs.\"``. The gateway stages binary multipart uploads internally before the workflow runs.", "example": { "report": { "document": "report_pdf" } }, "title": "Inputs", "type": "object" }, "steps": { "description": "Phase 1: a single prebuilt-pipeline step (name must be ``\"parse-extract\"``). Its result appears in ``output`` under the step's name.", "example": [ { "document": "$inputs.report", "name": "parse-extract", "schema": { "properties": { "revenue": { "type": "string" } }, "type": "object" } } ], "items": { "$ref": "#/components/schemas/PrebuiltWorkflowStep" }, "title": "Steps", "type": "array" }, "output": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional projection map. Keys are caller-chosen response field names; values are ``$output.....`` references. Omitted → full results tree returned under ``output``.", "example": { "revenue": "$output.parse-extract.extract.extraction.revenue", "revenue_blocks": "$output.parse-extract.ground.revenue" }, "title": "Output" }, "service_tier": { "anyOf": [ { "type": "string", "enum": [ "standard", "priority" ] }, { "type": "null" } ], "description": "Async service tier. ``priority`` runs in the fast lane at the sync billing rate; absent → ``standard``." } }, "required": [ "inputs", "steps" ], "title": "V2WorkflowRequest", "type": "object" } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "inputs": { "additionalProperties": { "$ref": "#/components/schemas/WorkflowDocumentInput" }, "description": "Named document sources. Each key is a logical name referenced from steps as ``\"$inputs.\"``. The gateway stages binary multipart uploads internally before the workflow runs. JSON-serialized string in form data.", "example": { "report": { "document": "report_pdf" } }, "title": "Inputs", "type": "object" }, "steps": { "description": "Phase 1: a single prebuilt-pipeline step (name must be ``\"parse-extract\"``). Its result appears in ``output`` under the step's name. JSON-serialized string in form data.", "example": [ { "document": "$inputs.report", "name": "parse-extract", "schema": { "properties": { "revenue": { "type": "string" } }, "type": "object" } } ], "items": { "$ref": "#/components/schemas/PrebuiltWorkflowStep" }, "title": "Steps", "type": "array" }, "output": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Optional projection map. Keys are caller-chosen response field names; values are ``$output.....`` references. Omitted → full results tree returned under ``output``. JSON-serialized string in form data.", "example": { "revenue": "$output.parse-extract.extract.extraction.revenue", "revenue_blocks": "$output.parse-extract.ground.revenue" }, "title": "Output" }, "service_tier": { "anyOf": [ { "type": "string", "enum": [ "standard", "priority" ] }, { "type": "null" } ], "description": "Async service tier. ``priority`` runs in the fast lane at the sync billing rate; absent → ``standard``." } }, "required": [ "inputs", "steps" ] } } } } }, "get": { "tags": [ "v2-workflow" ], "summary": "List v2-workflow jobs", "operationId": "v2-workflow_list_jobs", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Page number (0-indexed).", "default": 0, "title": "Page" }, "description": "Page number (0-indexed)." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of items per page.", "default": 10, "title": "Page Size" }, "description": "Number of items per page." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by job status.", "title": "Status" }, "description": "Filter by job status." } ], "responses": { "200": { "description": "The caller's jobs, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "job_id": { "type": "string", "description": "The unique identifier for this v2-workflow job. Format: ``v2-workflow-<26-character Crockford base32 ULID>`` (``[0-9a-hjkmnp-tv-z]{26}`` tail). Opaque, server-minted, and stable for the life of the job — the same id is returned on the sync response, the async 202, and every poll. Treat it as opaque; older id formats remain accepted indefinitely and are never re-issued." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "created_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "model_version": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] } } } }, "page": { "type": "integer" }, "page_size": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/workflow/jobs/{job_id}": { "get": { "tags": [ "v2-workflow" ], "summary": "Get v2-workflow job", "description": "Poll a job.\n\nReturns ``{job_id, status, created_at}`` plus ``completed_at`` and\n``result`` (on ``completed``) or ``error: {code, message}`` (on\n``failed``). Statuses: ``pending`` → ``processing`` →\n``completed`` | ``failed``.", "operationId": "v2-workflow_get_job", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The identifier of the job to retrieve, as returned by the create-job request.", "title": "Job Id" }, "description": "The identifier of the job to retrieve, as returned by the create-job request." } ], "responses": { "200": { "description": "Job status / result", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "The unique identifier for this v2-workflow job. Format: ``v2-workflow-<26-character Crockford base32 ULID>`` (``[0-9a-hjkmnp-tv-z]{26}`` tail). Opaque, server-minted, and stable for the life of the job — the same id is returned on the sync response, the async 202, and every poll. Treat it as opaque; older id formats remain accepted indefinitely and are never re-issued." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "created_at": { "type": [ "string", "null" ] }, "completed_at": { "type": "string", "description": "Present once the job is terminal." }, "progress": { "type": "number", "minimum": 0, "maximum": 1, "description": "Job completion as a decimal from 0 (not started) to 1 (complete). Present while ``processing``." }, "result": { "anyOf": [ { "description": "Result returned by V2WorkflowOperationWorkflow.\n\n``output`` is keyed by step name (or by caller-chosen projection keys when\n``output`` was provided in the request). For the ``\"parse-extract\"`` pipeline\nwith no projection, the keys are ``\"parse-extract\"`` → ``{parse, extract, ground}``:\n\n* ``output[\"parse-extract\"][\"parse\"]`` — full parse response (markdown,\n structure with per-node grounding inline, metadata).\n* ``output[\"parse-extract\"][\"extract\"]`` — extraction + ``extraction_metadata``\n with ``{value, ranges}`` leaves.\n* ``output[\"parse-extract\"][\"ground\"]`` — a tree MIRRORING\n ``extraction_metadata``: each ``{value, ranges}`` leaf is replaced by its\n resolved block-hit list (``[{block_id, type, parent_id?, grounding,\n atomic_grounding?}]`` — the same shape ``/v2/ground`` returns; see\n ``V2GroundResult.grounding`` for the full field-level contract), or\n ``null`` for a synthesised value. Nested objects and arrays keep their\n shape, so ``ground.issuer.name`` parallels\n ``extraction_metadata.issuer.name``. Resolved server-side — no\n client-side span lookup needed.\n\nReferences into the results use the ``$output.....`` grammar\n(see ``output`` field of the request).", "properties": { "output": { "additionalProperties": true, "description": "Step results keyed by step name, or a caller-defined projection. For ``parse-extract`` with no projection: ``{\"parse-extract\": {parse, extract, ground}}``.", "title": "Output", "type": "object" }, "metadata": { "$ref": "#/components/schemas/V2WorkflowMetadata", "description": "Request metadata (job_id, duration_ms, billing)." } }, "required": [ "output", "metadata" ], "title": "V2WorkflowResult", "type": "object" }, { "type": "null" } ], "description": "Present once status is ``completed``." }, "error": { "type": "object", "description": "Present once status is ``failed``.", "properties": { "code": { "type": "string", "description": "Stable error code (``internal_error`` when unmapped)." }, "message": { "type": "string" } } } } } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found (e.g. no such job).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/ground": { "post": { "tags": [ "Ground" ], "summary": "ADE Ground", "description": "Map extracted fields to the document blocks they were quoted from. Takes the extraction_metadata from an extract call and the structure tree from the parse call the markdown came from, and returns, for every extracted field, the overlapping blocks with their ids, page numbers, and bounding boxes. Runs synchronously and returns the result inline.", "operationId": "v2-ground_run_sync", "responses": { "200": { "description": "v2-ground result", "content": { "application/json": { "schema": { "description": "Result returned by V2GroundOperationWorkflow — the ``/v2/ground``\nresponse body.\n\n``grounding`` MIRRORS the ``extraction_metadata`` tree: nested objects and\narrays keep their shape, and each ``{value, ranges}`` leaf is replaced by\nthe list of structure blocks its ranges overlap (the block-hit shape\ndocumented on the field). It is NOT a flat map — a nested schema field like\n``issuer.name`` resolves to ``grounding[\"issuer\"][\"name\"]``.", "properties": { "grounding": { "additionalProperties": true, "description": "A tree mirroring ``extraction_metadata``: nested objects and arrays keep their shape, and each ``{value, ranges}`` leaf is replaced by the list of blocks its ranges overlap, in reading order. Each entry carries ``block_id`` and ``type`` identifying the matched ``structure`` block, ``parent_id`` naming the enclosing block for nested blocks (table cells), and the block's own ``grounding`` object (``{page, range, box}``) verbatim. When the block itself carries ``atomic_grounding``, the entry also lists the overlapping subset as ``{index, page, range, box}`` objects, where ``index`` is the position in the block's own ``atomic_grounding`` array; ``[]`` means the block matched but no individual entry did, and the key is omitted for blocks that carry no ``atomic_grounding``. A leaf is ``null`` when its ``ranges`` was ``null`` (a synthesised value, with no supporting passage to look up) and ``[]`` when valid ranges overlapped no block (which usually indicates a mismatched extraction/structure pair).", "example": { "invoice_number": [ { "atomic_grounding": [], "block_id": "text-1", "grounding": { "box": { "xmax": 0.42, "xmin": 0.1, "ymax": 0.15, "ymin": 0.12 }, "page": 1, "range": { "end": 31, "start": 13 } }, "type": "text" } ] }, "title": "Grounding", "type": "object" }, "metadata": { "$ref": "#/components/schemas/V2GroundMetadata", "description": "Request metadata (job_id, duration_ms, credit_usage)." } }, "required": [ "grounding", "metadata" ], "title": "V2GroundResult", "type": "object" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Input to V2GroundOperationWorkflow — the ``/v2/ground`` request body.\n\nA pure, stateless join: each ``extraction_metadata`` leaf's ``ranges``\n(char offsets into the markdown both artifacts were produced from) is\noverlapped against the ``grounding.range`` carried on every ``structure``\nblock, and the matching blocks are returned. Nothing is stored server-side,\nso block ids in the response resolve only against the ``structure`` tree\nsupplied here — pairing an extraction with the parse result it actually\ncame from is the caller's responsibility.", "properties": { "extraction_metadata": { "additionalProperties": true, "description": "The ``extraction_metadata`` object returned by ``POST /v2/extract`` (or the pipeline's extract step): a tree mirroring your extraction schema whose leaves are ``{value, ranges}`` objects, where ``ranges`` are ``{start, end}`` Unicode code point offsets into the parse markdown.", "example": { "invoice_number": { "ranges": [ { "end": 31, "start": 13 } ], "value": "INV-042" } }, "title": "Extraction Metadata", "type": "object" }, "structure": { "additionalProperties": true, "description": "The ``structure`` tree from the parse response the extraction was produced from. Every block in the tree carries its ``grounding`` (``{page, range, box}``) inline; block ids in the response resolve against this exact tree.", "title": "Structure", "type": "object" } }, "required": [ "extraction_metadata", "structure" ], "title": "V2GroundRequest", "type": "object" } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "extraction_metadata": { "additionalProperties": true, "description": "The ``extraction_metadata`` object returned by ``POST /v2/extract`` (or the pipeline's extract step): a tree mirroring your extraction schema whose leaves are ``{value, ranges}`` objects, where ``ranges`` are ``{start, end}`` Unicode code point offsets into the parse markdown. JSON-serialized string in form data.", "example": { "invoice_number": { "ranges": [ { "end": 31, "start": 13 } ], "value": "INV-042" } }, "title": "Extraction Metadata", "type": "object" }, "structure": { "additionalProperties": true, "description": "The ``structure`` tree from the parse response the extraction was produced from. Every block in the tree carries its ``grounding`` (``{page, range, box}``) inline; block ids in the response resolve against this exact tree. JSON-serialized string in form data.", "title": "Structure", "type": "object" } }, "required": [ "extraction_metadata", "structure" ] } } } } } }, "/v2/ground/jobs": { "post": { "tags": [ "Ground" ], "summary": "ADE Ground Jobs", "operationId": "v2-ground_create_job", "responses": { "202": { "description": "Job created", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "The unique identifier for this v2-ground job. Format: ``ground-<26-character Crockford base32 ULID>`` (``[0-9a-hjkmnp-tv-z]{26}`` tail). Opaque, server-minted, and stable for the life of the job — the same id is returned on the sync response, the async 202, and every poll. Treat it as opaque; older id formats remain accepted indefinitely and are never re-issued." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "created_at": { "type": [ "string", "null" ] } } } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Map extracted fields to the document blocks they were quoted from. Takes the extraction_metadata from an extract call and the structure tree from the parse call the markdown came from, and returns, for every extracted field, the overlapping blocks with their ids, page numbers, and bounding boxes. Runs asynchronously and returns a job ID; use it to poll for status and retrieve the result once processing completes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "description": "Input to V2GroundOperationWorkflow — the ``/v2/ground`` request body.\n\nA pure, stateless join: each ``extraction_metadata`` leaf's ``ranges``\n(char offsets into the markdown both artifacts were produced from) is\noverlapped against the ``grounding.range`` carried on every ``structure``\nblock, and the matching blocks are returned. Nothing is stored server-side,\nso block ids in the response resolve only against the ``structure`` tree\nsupplied here — pairing an extraction with the parse result it actually\ncame from is the caller's responsibility.", "properties": { "extraction_metadata": { "additionalProperties": true, "description": "The ``extraction_metadata`` object returned by ``POST /v2/extract`` (or the pipeline's extract step): a tree mirroring your extraction schema whose leaves are ``{value, ranges}`` objects, where ``ranges`` are ``{start, end}`` Unicode code point offsets into the parse markdown.", "example": { "invoice_number": { "ranges": [ { "end": 31, "start": 13 } ], "value": "INV-042" } }, "title": "Extraction Metadata", "type": "object" }, "structure": { "additionalProperties": true, "description": "The ``structure`` tree from the parse response the extraction was produced from. Every block in the tree carries its ``grounding`` (``{page, range, box}``) inline; block ids in the response resolve against this exact tree.", "title": "Structure", "type": "object" } }, "required": [ "extraction_metadata", "structure" ], "title": "V2GroundRequest", "type": "object" } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "extraction_metadata": { "additionalProperties": true, "description": "The ``extraction_metadata`` object returned by ``POST /v2/extract`` (or the pipeline's extract step): a tree mirroring your extraction schema whose leaves are ``{value, ranges}`` objects, where ``ranges`` are ``{start, end}`` Unicode code point offsets into the parse markdown. JSON-serialized string in form data.", "example": { "invoice_number": { "ranges": [ { "end": 31, "start": 13 } ], "value": "INV-042" } }, "title": "Extraction Metadata", "type": "object" }, "structure": { "additionalProperties": true, "description": "The ``structure`` tree from the parse response the extraction was produced from. Every block in the tree carries its ``grounding`` (``{page, range, box}``) inline; block ids in the response resolve against this exact tree. JSON-serialized string in form data.", "title": "Structure", "type": "object" } }, "required": [ "extraction_metadata", "structure" ] } } } } }, "get": { "tags": [ "Ground" ], "summary": "ADE List Ground Jobs", "operationId": "v2-ground_list_jobs", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Page number (0-indexed).", "default": 0, "title": "Page" }, "description": "Page number (0-indexed)." }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "description": "Number of items per page.", "default": 10, "title": "Page Size" }, "description": "Number of items per page." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Filter by job status.", "title": "Status" }, "description": "Filter by job status." } ], "responses": { "200": { "description": "The caller's jobs, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "job_id": { "type": "string", "description": "The unique identifier for this v2-ground job. Format: ``ground-<26-character Crockford base32 ULID>`` (``[0-9a-hjkmnp-tv-z]{26}`` tail). Opaque, server-minted, and stable for the life of the job — the same id is returned on the sync response, the async 202, and every poll. Treat it as opaque; older id formats remain accepted indefinitely and are never re-issued." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "created_at": { "type": [ "string", "null" ] }, "completed_at": { "type": [ "string", "null" ] }, "model_version": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] } } } }, "page": { "type": "integer" }, "page_size": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "List your Ground jobs, newest first." } }, "/v2/ground/jobs/{job_id}": { "get": { "tags": [ "Ground" ], "summary": "ADE Get Ground Jobs", "description": "Get the status of an async Ground job, including its result once the job has completed.", "operationId": "v2-ground_get_job", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The identifier of the job to retrieve, as returned by the create-job request.", "title": "Job Id" }, "description": "The identifier of the job to retrieve, as returned by the create-job request." } ], "responses": { "200": { "description": "Job status / result", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "The unique identifier for this v2-ground job. Format: ``ground-<26-character Crockford base32 ULID>`` (``[0-9a-hjkmnp-tv-z]{26}`` tail). Opaque, server-minted, and stable for the life of the job — the same id is returned on the sync response, the async 202, and every poll. Treat it as opaque; older id formats remain accepted indefinitely and are never re-issued." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "created_at": { "type": [ "string", "null" ] }, "completed_at": { "type": "string", "description": "Present once the job is terminal." }, "progress": { "type": "number", "minimum": 0, "maximum": 1, "description": "Job completion as a decimal from 0 (not started) to 1 (complete). Present while ``processing``." }, "result": { "anyOf": [ { "description": "Result returned by V2GroundOperationWorkflow — the ``/v2/ground``\nresponse body.\n\n``grounding`` MIRRORS the ``extraction_metadata`` tree: nested objects and\narrays keep their shape, and each ``{value, ranges}`` leaf is replaced by\nthe list of structure blocks its ranges overlap (the block-hit shape\ndocumented on the field). It is NOT a flat map — a nested schema field like\n``issuer.name`` resolves to ``grounding[\"issuer\"][\"name\"]``.", "properties": { "grounding": { "additionalProperties": true, "description": "A tree mirroring ``extraction_metadata``: nested objects and arrays keep their shape, and each ``{value, ranges}`` leaf is replaced by the list of blocks its ranges overlap, in reading order. Each entry carries ``block_id`` and ``type`` identifying the matched ``structure`` block, ``parent_id`` naming the enclosing block for nested blocks (table cells), and the block's own ``grounding`` object (``{page, range, box}``) verbatim. When the block itself carries ``atomic_grounding``, the entry also lists the overlapping subset as ``{index, page, range, box}`` objects, where ``index`` is the position in the block's own ``atomic_grounding`` array; ``[]`` means the block matched but no individual entry did, and the key is omitted for blocks that carry no ``atomic_grounding``. A leaf is ``null`` when its ``ranges`` was ``null`` (a synthesised value, with no supporting passage to look up) and ``[]`` when valid ranges overlapped no block (which usually indicates a mismatched extraction/structure pair).", "example": { "invoice_number": [ { "atomic_grounding": [], "block_id": "text-1", "grounding": { "box": { "xmax": 0.42, "xmin": 0.1, "ymax": 0.15, "ymin": 0.12 }, "page": 1, "range": { "end": 31, "start": 13 } }, "type": "text" } ] }, "title": "Grounding", "type": "object" }, "metadata": { "$ref": "#/components/schemas/V2GroundMetadata", "description": "Request metadata (job_id, duration_ms, credit_usage)." } }, "required": [ "grounding", "metadata" ], "title": "V2GroundResult", "type": "object" }, { "type": "null" } ], "description": "Present once status is ``completed``." }, "error": { "type": "object", "description": "Present once status is ``failed``.", "properties": { "code": { "type": "string", "description": "Stable error code (``internal_error`` when unmapped)." }, "message": { "type": "string" } } } } } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found (e.g. no such job).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/files": { "post": { "tags": [ "files" ], "summary": "Stage an input file", "description": "Stage bytes on the data plane; pass the returned ``file_ref`` in\njob inputs (the contract request types take ``*_ref`` fields).", "operationId": "stage_file_v1_files_post", "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Body_stage_file_v1_files_post" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Response Stage File V1 Files Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "Body_stage_file_v1_files_post": { "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "title": "File" } }, "type": "object", "required": [ "file" ], "title": "Body_stage_file_v1_files_post" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "ErrorResponse": { "type": "object", "title": "ErrorResponse", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable snake_case error code (e.g. ``validation_error``, ``unknown_model_version``, ``invalid_url``, ``invalid_api_key``, ``rate_limit_exceeded``)." }, "message": { "type": "string", "description": "Human-readable detail." } } }, "BaseElementOptions": { "additionalProperties": false, "properties": { "markdown": { "default": true, "title": "Markdown", "type": "boolean" } }, "title": "BaseElementOptions", "type": "object" }, "BlocksOptions": { "additionalProperties": false, "properties": { "text": { "$ref": "#/components/schemas/BaseElementOptions" }, "table": { "$ref": "#/components/schemas/TableOptions" }, "figure": { "$ref": "#/components/schemas/FigureOptions" }, "marginalia": { "$ref": "#/components/schemas/BaseElementOptions" }, "attestation": { "$ref": "#/components/schemas/BaseElementOptions" }, "logo": { "$ref": "#/components/schemas/BaseElementOptions" }, "scan_code": { "$ref": "#/components/schemas/BaseElementOptions" }, "card": { "$ref": "#/components/schemas/BaseElementOptions" } }, "title": "BlocksOptions", "type": "object" }, "FigureOptions": { "additionalProperties": false, "properties": { "markdown": { "default": true, "title": "Markdown", "type": "boolean" } }, "title": "FigureOptions", "type": "object" }, "TableOptions": { "additionalProperties": false, "properties": { "markdown": { "default": true, "title": "Markdown", "type": "boolean" }, "format": { "default": "html", "enum": [ "markdown", "html" ], "title": "Format", "type": "string" } }, "title": "TableOptions", "type": "object" }, "Box": { "description": "Axis-aligned bounding box in normalized page coordinates.\n\nEvery value is a fraction of the page's width (`xmin`/`xmax`) or height\n(`ymin`/`ymax`) in `[0, 1]`, with at most 8 decimal places. To convert to\npixels, multiply by the dimensions of whatever raster of the page you are\ndrawing on. Coordinates are clamped and rounded at construction so the\nin-process value always equals the serialized one.", "properties": { "xmin": { "description": "Left edge as a fraction of the page width, in `[0, 1]`.", "title": "Xmin", "type": "number" }, "ymin": { "description": "Top edge as a fraction of the page height, in `[0, 1]`.", "title": "Ymin", "type": "number" }, "xmax": { "description": "Right edge as a fraction of the page width, in `[0, 1]`.", "title": "Xmax", "type": "number" }, "ymax": { "description": "Bottom edge as a fraction of the page height, in `[0, 1]`.", "title": "Ymax", "type": "number" } }, "required": [ "xmin", "ymin", "xmax", "ymax" ], "title": "Box", "type": "object" }, "Document": { "properties": { "type": { "const": "document", "default": "document", "description": "The node type. Identifies this node as the root of the structure tree.", "title": "Type", "type": "string" }, "children": { "description": "The pages of the document, in source order.", "items": { "$ref": "#/components/schemas/Page" }, "title": "Children", "type": "array" }, "markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The full document markdown — identical to the top-level `markdown` field, included so the structure tree is self-contained. Present only when `options.inline_markdown` is `true`.", "title": "Markdown" } }, "title": "Document", "type": "object" }, "Element": { "description": "Hierarchical document element. All non-page elements share this shape.\n\nKeys off `type`; optional fields are excluded from the serialized JSON\nvia ``exclude_none=True`` when not set.", "properties": { "type": { "description": "The element type. Determines which optional fields appear on this element.", "enum": [ "text", "table", "table_cell", "figure", "marginalia", "attestation", "logo", "card", "scan_code" ], "title": "Type", "type": "string" }, "id": { "description": "Semantic element id, unique within the document. Format `-`, where `` is a per-type 0-based counter assigned in reading order — `text-0` is the first text element in the document, `figure-0` the first figure, `table_cell-0` the first cell of the first table. Stable within a response but not across re-parses of the same document.", "title": "Id", "type": "string" }, "grounding": { "$ref": "#/components/schemas/Grounding", "description": "The element's spatial data: the page it appears on, its `[start, end)` range in the top-level `markdown` string, and its bounding box in normalized page coordinates." }, "atomic_grounding": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Grounding" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Fine-grained grounding segments at the model's current granularity (visual lines today; finer in future versions, same schema). Present only on leaf elements — every type except `table`. `[]` only when segments are structurally impossible: `table_cell` (a cell has no finer granularity than itself) and elements whose markdown is suppressed via `blocks..markdown=false`. Any other leaf the model could not segment finer carries a single entry covering the element's full range and box. Omitted entirely when `options.atomic_grounding` is `false`.", "title": "Atomic Grounding" }, "children": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Element" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "The cells (`table_cell` elements) of a `table` element. Present only when `type` is `table`.", "title": "Children" }, "markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "The element's slice of the top-level `markdown` string (`markdown[grounding.range.start:grounding.range.end]`). `\"\"` for zero-length ranges (e.g. blocks suppressed via `blocks..markdown=false`). Present only when `options.inline_markdown` is `true`.", "title": "Markdown" }, "row": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "0-indexed row position of this cell within its parent `table`. Present only on `table_cell` elements.", "title": "Row" }, "col": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "0-indexed column position of this cell within its parent `table`. Present only on `table_cell` elements.", "title": "Col" }, "colspan": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Number of columns this cell spans. `1` for unmerged cells. Present only on `table_cell` elements.", "title": "Colspan" }, "rowspan": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Number of rows this cell spans. `1` for unmerged cells. Present only on `table_cell` elements.", "title": "Rowspan" } }, "required": [ "type", "id", "grounding" ], "title": "Element", "type": "object" }, "Grounding": { "description": "Where a node lives: its page, its slice of `markdown`, and its box.\n\nThe same shape is used for page nodes, element nodes, and each\n`atomic_grounding` entry, so any grounding object is self-contained — it\ncan be lifted out of the tree and still locates its content.", "properties": { "page": { "description": "1-indexed page number this grounding is on. On a page node, the page's own number.", "title": "Page", "type": "integer" }, "range": { "$ref": "#/components/schemas/Range", "description": "`[start, end)` offsets into the top-level `markdown` string covered by this node or segment." }, "box": { "$ref": "#/components/schemas/Box", "description": "Bounding box in normalized page coordinates (`0`–`1` fractions of page width/height, at most 8 decimal places). A page node's box is always the full page `{0, 0, 1, 1}`." } }, "required": [ "page", "range", "box" ], "title": "Grounding", "type": "object" }, "Page": { "properties": { "type": { "const": "page", "default": "page", "description": "The node type. Identifies this node as a page in the structure tree.", "title": "Type", "type": "string" }, "grounding": { "$ref": "#/components/schemas/Grounding", "description": "The page's spatial data: `page` is the 1-indexed page number in the source document (not contiguous when `options.pages` filters out some pages); `range` covers this page's content in the top-level `markdown` string (zero-length `start == end` for failed pages); `box` is always the full page `{0, 0, 1, 1}`." }, "status": { "default": "ok", "description": "Whether this page was parsed successfully (`ok`) or failed (`failed`).", "enum": [ "ok", "failed" ], "title": "Status", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Failure reason. Present only when `status` is `failed`.", "title": "Reason" }, "children": { "description": "The elements detected on this page, in reading order. Empty for failed pages.", "items": { "$ref": "#/components/schemas/Element" }, "title": "Children", "type": "array" }, "markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "This page's slice of the top-level `markdown` string (`markdown[grounding.range.start:grounding.range.end]`). `\"\"` for failed pages. Present only when `options.inline_markdown` is `true`.", "title": "Markdown" } }, "required": [ "grounding" ], "title": "Page", "type": "object" }, "ParseBilling": { "description": "Billing summary for one parse request.", "properties": { "service_tier": { "anyOf": [ { "enum": [ "standard", "priority" ], "type": "string" }, { "type": "null" } ], "description": "The service tier the request ran in: `standard` or `priority`. A sync request reports `priority` (same lane, same price).", "title": "Service Tier" }, "total_credits": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Credits charged for this request.", "title": "Total Credits" } }, "required": [ "service_tier", "total_credits" ], "title": "ParseBilling", "type": "object" }, "ParseMetadata": { "description": "Information about a parse request. This is the customer-facing shape —\nthe internal billing-canonical metadata (``aide_common.parse_schema.ParseMetadata``)\nis projected into it at the render boundary (``project_customer_metadata``).", "properties": { "job_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The parse job identifier — always server-minted and unique per submit. On the async `/jobs` route this is the id the caller polls. Correlates with the job's entry in your billing dashboard. Format: ``-<26-character Crockford base32 ULID>`` matching ``^(parse|extract)-[0-9a-hjkmnp-tv-z]{26}$``. Opaque, server-minted, and stable for the life of the job — the same id is returned on the sync response, the async 202, and every poll. Treat it as opaque; older id formats remain accepted indefinitely and are never re-issued.", "title": "Job Id" }, "model_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The exact model snapshot that parsed the document, e.g. `dpt-3-pro-20260710`.", "title": "Model Version" }, "page_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total number of pages in the source document. Includes pages filtered out by `options.pages`; the actual returned pages are in `structure.children`.", "title": "Page Count" }, "output_markdown_chars": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of Unicode code points in the returned `markdown` string.", "title": "Output Markdown Chars" }, "range_units": { "const": "unicode_codepoints", "description": "Units of every `range` offset in the response. Always `\"unicode_codepoints\"` (Unicode code points into `markdown`). Declared explicitly so consumers know how to slice the string — e.g. JavaScript strings are UTF-16, so a naive `.slice()` drifts when the markdown contains astral characters; such consumers must convert code-point offsets to UTF-16 indices first.", "title": "Range Units", "type": "string" }, "openapi_spec": { "description": "URL of the OpenAPI spec covering this API, for inspection and client generation.", "title": "Openapi Spec", "type": "string" }, "failed_pages": { "description": "1-indexed page numbers that failed to parse. Empty when all pages succeed; failed pages also appear in `structure.children` with `status: failed`.", "items": { "type": "integer" }, "title": "Failed Pages", "type": "array" }, "duration_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total processing time in milliseconds.", "title": "Duration Ms" }, "billing": { "$ref": "#/components/schemas/ParseBilling", "description": "Billing summary: the service tier and the credits charged." } }, "required": [ "job_id", "model_version", "page_count", "output_markdown_chars", "range_units", "openapi_spec", "failed_pages", "duration_ms", "billing" ], "title": "ParseMetadata", "type": "object" }, "Range": { "description": "A `[start, end)` slice of the top-level `markdown` string.", "properties": { "start": { "description": "Inclusive start offset into the top-level `markdown` string, in the units declared by `metadata.range_units` (Unicode code points).", "title": "Start", "type": "integer" }, "end": { "description": "Exclusive end offset into the top-level `markdown` string, in the units declared by `metadata.range_units` (Unicode code points).", "title": "End", "type": "integer" } }, "required": [ "start", "end" ], "title": "Range", "type": "object" }, "ParseResponse": { "description": "The parse result: the full document as `markdown`, its hierarchical\n`structure` (with per-node spatial `grounding` inline), and request\n`metadata`.", "properties": { "markdown": { "description": "The full document as a single Markdown string, in reading order.", "title": "Markdown", "type": "string" }, "metadata": { "$ref": "#/components/schemas/ParseMetadata", "description": "Information about the request: model version, page count, duration, billing, and more." }, "structure": { "$ref": "#/components/schemas/Document", "description": "The document's hierarchical structure: pages and the elements detected on each page. Every node below the root carries its spatial data inline in a `grounding` object (`{page, range, box}`, normalized page coordinates); leaf elements additionally carry `atomic_grounding`." } }, "required": [ "markdown", "metadata", "structure" ], "title": "ParseResponse", "type": "object" }, "V2ExtractOptions": { "additionalProperties": false, "description": "Extraction options (``docs/extract-v2-proposal.md`` → Options).", "properties": { "strict": { "default": false, "description": "When ``true``, a schema containing fields the model cannot extract fails with a validation error — HTTP 422 on the sync route, or a failed job (``status: \"failed\"``) on the async ``/jobs`` route. When ``false`` (default), unsupported fields are skipped and extraction continues.", "title": "Strict", "type": "boolean" } }, "title": "V2ExtractOptions", "type": "object" }, "V2ExtractMetadata": { "description": "Response metadata for a v2 extract call.", "properties": { "job_id": { "description": "Gateway job id (workflow id). Matches the ``x-request-id`` the gateway minted for this request and the billing row id in vision-agent.", "title": "Job Id", "type": "string" }, "model_version": { "description": "Resolved model version.", "title": "Model Version", "type": "string" }, "duration_ms": { "description": "End-to-end request duration in milliseconds.", "title": "Duration Ms", "type": "integer" }, "doc_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Present when the input markdown contained a ```` comment (embedded by ``POST /v2/parse``). Links this extract call to the originating parse job.", "title": "Doc Id" }, "range_units": { "const": "unicode_codepoints", "default": "unicode_codepoints", "description": "Units of every `range` offset in the response. Always `\"unicode_codepoints\"` (Unicode code points into `markdown`). Declared explicitly so consumers know how to slice the string — e.g. JavaScript strings are UTF-16, so a naive `.slice()` drifts when the markdown contains astral characters.", "title": "Range Units", "type": "string" }, "input_markdown_chars": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Characters (Unicode code points) in the input markdown as submitted — the input basis of the credit charge.", "title": "Input Markdown Chars" }, "output_extraction_chars": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Characters in the serialized extraction output — the output basis of the credit charge.", "title": "Output Extraction Chars" }, "openapi_spec": { "type": "string", "description": "URL of the OpenAPI spec covering this API, for inspection and client generation." }, "billing": { "anyOf": [ { "$ref": "#/components/schemas/V2Billing" }, { "type": "null" } ], "description": "Billing summary: the service tier the request ran in and the credits charged." } }, "required": [ "job_id", "model_version", "duration_ms", "openapi_spec", "range_units" ], "title": "V2ExtractMetadata", "type": "object" }, "V2Billing": { "description": "Billing summary: the service tier the request ran in and the credits\ncharged.", "properties": { "service_tier": { "anyOf": [ { "enum": [ "standard", "priority" ], "type": "string" }, { "type": "null" } ], "default": null, "description": "The service tier the request ran in: `standard` or `priority`. A sync request reports `priority` (same lane, same price).", "title": "Service Tier" }, "total_credits": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Credits charged for this request.", "title": "Total Credits" } }, "title": "V2Billing", "type": "object" }, "PrebuiltWorkflowStep": { "description": "A Phase 1 step: references a server-defined pipeline by name.\n\nThe ``name`` identifies the prebuilt pipeline to run AND becomes the key\nunder which this step's result appears in the response ``output`` map.\nThe ``document`` field is a reference into the ``inputs`` namespace\n(``\"$inputs.\"``).", "properties": { "name": { "const": "parse-extract", "description": "Workflow to run — doubles as the result key in ``output``. v1 only: ``\"parse-extract\"``.", "title": "Name", "type": "string" }, "document": { "description": "Reference into the ``inputs`` namespace, e.g. ``\"$inputs.report\"``. The referenced input must be declared in the ``inputs`` form field.", "title": "Document", "type": "string" }, "schema": { "additionalProperties": true, "description": "JSON Schema for fields to extract.", "example": { "properties": { "revenue": { "type": "string" } }, "type": "object" }, "title": "Schema", "type": "object" }, "options": { "anyOf": [ { "$ref": "#/components/schemas/WorkflowStepOptions" }, { "type": "null" } ], "default": null, "description": "Parse + extract options for this step. Omit for defaults." } }, "required": [ "name", "document", "schema" ], "title": "PrebuiltWorkflowStep", "type": "object" }, "WorkflowDocumentInput": { "description": "One declared document input in the ``inputs`` map.\n\nA caller supplies exactly one of ``document`` or ``document_url``:\n\n* ``document`` — name of a multipart form part carrying the raw bytes. The\n gateway stages those bytes internally before the workflow runs.\n* ``document_url`` — public URL (SSRF-validated at submit; fetched and staged\n by the gateway before the workflow starts).", "properties": { "document": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Name of the multipart form part carrying the document bytes. The gateway resolves this to an internal ref before validation; it is not stored in the final request object.", "example": "report_pdf", "title": "Document" }, "document_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to fetch the document from. Must be a public http(s) URL; private/loopback IPs are rejected at submit time.", "title": "Document Url" } }, "title": "WorkflowDocumentInput", "type": "object" }, "WorkflowStepOptions": { "description": "Unified options for the ``parse-extract`` prebuilt step.\n\n``pages`` applies to the parse stage; ``strict`` applies to the extract\nstage. Omit entirely to use each stage's defaults.", "properties": { "pages": { "anyOf": [ { "items": { "minimum": 1, "type": "integer" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "1-indexed page numbers to process. ``null`` = all pages. Values < 1 are rejected; numbers > page_count are silently ignored.", "title": "Pages" }, "strict": { "default": false, "description": "When ``true``, a schema containing fields the model cannot extract fails with a validation error — HTTP 422 on the sync route, or a failed job on the async ``/jobs`` route. When ``false``, unsupported fields are skipped.", "title": "Strict", "type": "boolean" } }, "title": "WorkflowStepOptions", "type": "object" }, "V2WorkflowMetadata": { "description": "Response metadata for a v2 workflow call\n(``docs/pipeline-v2-proposal.md`` → Top-level metadata).", "properties": { "job_id": { "description": "Gateway job id (workflow id).", "title": "Job Id", "type": "string" }, "duration_ms": { "description": "Total end-to-end duration across all stages in milliseconds.", "title": "Duration Ms", "type": "integer" }, "openapi_spec": { "type": "string", "description": "URL of the OpenAPI spec covering this API, for inspection and client generation." }, "billing": { "anyOf": [ { "$ref": "#/components/schemas/V2Billing" }, { "type": "null" } ], "description": "Billing summary: the service tier the request ran in and the credits charged." } }, "required": [ "job_id", "duration_ms", "openapi_spec" ], "title": "V2WorkflowMetadata", "type": "object" }, "V2GroundMetadata": { "description": "Response metadata for a v2 ground call.", "properties": { "job_id": { "description": "Gateway job id (workflow id). Matches the ``x-request-id`` the gateway minted for this request.", "title": "Job Id", "type": "string" }, "duration_ms": { "description": "End-to-end request duration in milliseconds.", "title": "Duration Ms", "type": "integer" }, "openapi_spec": { "type": "string", "description": "URL of the OpenAPI spec covering this API, for inspection and client generation." }, "billing": { "anyOf": [ { "$ref": "#/components/schemas/V2Billing" }, { "type": "null" } ], "description": "Billing summary: the service tier the request ran in and the credits charged." } }, "required": [ "job_id", "duration_ms", "openapi_spec" ], "title": "V2GroundMetadata", "type": "object" } } } }