{ "openapi": "3.1.0", "info": { "title": "LandingAI Agentic Document Extraction (ADE) API v2: Parse and Extract Documents with DPT-3", "description": "Parse and extract data from documents with DPT-3, a document parsing model from LandingAI, using the Agentic Document Extraction (ADE) v2 endpoints. Parse converts PDFs and images into structured Markdown and elements with per-element grounding (page numbers and coordinates) for RAG, search, and extraction pipelines. Extract pulls specific fields from parsed Markdown using a JSON schema. Documentation: https://docs.landing.ai", "version": "1.0.0" }, "servers": [ { "url": "https://api.ade.landing.ai", "description": "Production vision tools API" } ], "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" } } } }, "206": { "description": "Partial success (some pages failed to parse)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseResponse" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "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." } } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST 'https://api.ade.landing.ai/v2/parse' \\\n -H 'Authorization: Bearer YOUR_API_KEY' \\\n -F 'document=@document.pdf' \\\n -F 'model=dpt-3-pro-latest'" }, { "lang": "Python", "label": "Python", "source": "import requests\n\nurl = 'https://api.ade.landing.ai/v2/parse'\nheaders = {'Authorization': 'Bearer YOUR_API_KEY'}\n\nfiles = {'document': open('document.pdf', 'rb')}\ndata = {'model': 'dpt-3-pro-latest'}\n\nresponse = requests.post(url, headers=headers, files=files, data=data)\nprint(response.json())" }, { "lang": "JavaScript", "label": "Node.js", "source": "const axios = require('axios');\nconst FormData = require('form-data');\nconst fs = require('fs');\n\nconst form = new FormData();\nform.append('document', fs.createReadStream('document.pdf'));\nform.append('model', 'dpt-3-pro-latest');\n\naxios.post('https://api.ade.landing.ai/v2/parse', form, {\n headers: { 'Authorization': 'Bearer YOUR_API_KEY', ...form.getHeaders() }\n})\n .then(response => console.log(response.data))\n .catch(error => console.error(error));" } ] } }, "/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``." } } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST 'https://api.ade.landing.ai/v2/parse/jobs' \\\n -H 'Authorization: Bearer YOUR_API_KEY' \\\n -F 'document=@document.pdf' \\\n -F 'model=dpt-3-pro-latest'" }, { "lang": "Python", "label": "Python", "source": "import requests\n\nurl = 'https://api.ade.landing.ai/v2/parse/jobs'\nheaders = {'Authorization': 'Bearer YOUR_API_KEY'}\n\nfiles = {'document': open('document.pdf', 'rb')}\ndata = {'model': 'dpt-3-pro-latest'}\n\nresponse = requests.post(url, headers=headers, files=files, data=data)\nprint(response.json())" }, { "lang": "JavaScript", "label": "Node.js", "source": "const axios = require('axios');\nconst FormData = require('form-data');\nconst fs = require('fs');\n\nconst form = new FormData();\nform.append('document', fs.createReadStream('document.pdf'));\nform.append('model', 'dpt-3-pro-latest');\n\naxios.post('https://api.ade.landing.ai/v2/parse/jobs', form, {\n headers: { 'Authorization': 'Bearer YOUR_API_KEY', ...form.getHeaders() }\n})\n .then(response => console.log(response.data))\n .catch(error => console.error(error));" } ] }, "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" } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl 'https://api.ade.landing.ai/v2/parse/jobs' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" }, { "lang": "Python", "label": "Python", "source": "import requests\n\nurl = 'https://api.ade.landing.ai/v2/parse/jobs'\nheaders = {'Authorization': 'Bearer YOUR_API_KEY'}\n\nresponse = requests.get(url, headers=headers)\nprint(response.json())" }, { "lang": "JavaScript", "label": "Node.js", "source": "const axios = require('axios');\n\naxios.get('https://api.ade.landing.ai/v2/parse/jobs', {\n headers: { 'Authorization': 'Bearer YOUR_API_KEY' }\n})\n .then(response => console.log(response.data))\n .catch(error => console.error(error));" } ] } }, "/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``." }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/ParseMetadata" }, { "type": "null" } ], "description": "The parse metadata (billing included), present alongside ``output_url`` once a job with ``output_save_url`` has ``completed`` — the delivery moves the content, not the receipt. Inline jobs carry it inside ``result`` instead." }, "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" } } } } } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl 'https://api.ade.landing.ai/v2/parse/jobs/JOB_ID' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" }, { "lang": "Python", "label": "Python", "source": "import requests\n\nurl = 'https://api.ade.landing.ai/v2/parse/jobs/JOB_ID'\nheaders = {'Authorization': 'Bearer YOUR_API_KEY'}\n\nresponse = requests.get(url, headers=headers)\nprint(response.json())" }, { "lang": "JavaScript", "label": "Node.js", "source": "const axios = require('axios');\n\naxios.get('https://api.ade.landing.ai/v2/parse/jobs/JOB_ID', {\n headers: { 'Authorization': 'Bearer YOUR_API_KEY' }\n})\n .then(response => console.log(response.data))\n .catch(error => console.error(error));" } ] } }, "/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" ] } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST 'https://api.ade.landing.ai/v2/extract' \\\n -H 'Authorization: Bearer YOUR_API_KEY' \\\n -F 'markdown=@parse-output.md' \\\n -F 'schema={\"type\":\"object\",\"properties\":{\"revenue\":{\"type\":\"string\",\"description\":\"Q1 2024 revenue\"}}}'" }, { "lang": "Python", "label": "Python", "source": "import json\nimport requests\n\nurl = 'https://api.ade.landing.ai/v2/extract'\nheaders = {'Authorization': 'Bearer YOUR_API_KEY'}\n\nfiles = {'markdown': open('parse-output.md', 'rb')}\ndata = {\n 'schema': json.dumps({\n 'type': 'object',\n 'properties': {\n 'revenue': {'type': 'string', 'description': 'Q1 2024 revenue'}\n }\n })\n}\n\nresponse = requests.post(url, headers=headers, files=files, data=data)\nprint(response.json())" }, { "lang": "JavaScript", "label": "Node.js", "source": "const axios = require('axios');\nconst FormData = require('form-data');\nconst fs = require('fs');\n\nconst form = new FormData();\nform.append('markdown', fs.createReadStream('parse-output.md'));\nform.append('schema', JSON.stringify({\n type: 'object',\n properties: {\n revenue: { type: 'string', description: 'Q1 2024 revenue' }\n }\n}));\n\naxios.post('https://api.ade.landing.ai/v2/extract', form, {\n headers: { 'Authorization': 'Bearer YOUR_API_KEY', ...form.getHeaders() }\n})\n .then(response => console.log(response.data))\n .catch(error => console.error(error));" } ] } }, "/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" ] } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl -X POST 'https://api.ade.landing.ai/v2/extract/jobs' \\\n -H 'Authorization: Bearer YOUR_API_KEY' \\\n -F 'markdown=@parse-output.md' \\\n -F 'schema={\"type\":\"object\",\"properties\":{\"revenue\":{\"type\":\"string\",\"description\":\"Q1 2024 revenue\"}}}'" }, { "lang": "Python", "label": "Python", "source": "import json\nimport requests\n\nurl = 'https://api.ade.landing.ai/v2/extract/jobs'\nheaders = {'Authorization': 'Bearer YOUR_API_KEY'}\n\nfiles = {'markdown': open('parse-output.md', 'rb')}\ndata = {\n 'schema': json.dumps({\n 'type': 'object',\n 'properties': {\n 'revenue': {'type': 'string', 'description': 'Q1 2024 revenue'}\n }\n })\n}\n\nresponse = requests.post(url, headers=headers, files=files, data=data)\nprint(response.json())" }, { "lang": "JavaScript", "label": "Node.js", "source": "const axios = require('axios');\nconst FormData = require('form-data');\nconst fs = require('fs');\n\nconst form = new FormData();\nform.append('markdown', fs.createReadStream('parse-output.md'));\nform.append('schema', JSON.stringify({\n type: 'object',\n properties: {\n revenue: { type: 'string', description: 'Q1 2024 revenue' }\n }\n}));\n\naxios.post('https://api.ade.landing.ai/v2/extract/jobs', form, {\n headers: { 'Authorization': 'Bearer YOUR_API_KEY', ...form.getHeaders() }\n})\n .then(response => console.log(response.data))\n .catch(error => console.error(error));" } ] }, "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.", "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl 'https://api.ade.landing.ai/v2/extract/jobs' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" }, { "lang": "Python", "label": "Python", "source": "import requests\n\nurl = 'https://api.ade.landing.ai/v2/extract/jobs'\nheaders = {'Authorization': 'Bearer YOUR_API_KEY'}\n\nresponse = requests.get(url, headers=headers)\nprint(response.json())" }, { "lang": "JavaScript", "label": "Node.js", "source": "const axios = require('axios');\n\naxios.get('https://api.ade.landing.ai/v2/extract/jobs', {\n headers: { 'Authorization': 'Bearer YOUR_API_KEY' }\n})\n .then(response => console.log(response.data))\n .catch(error => console.error(error));" } ] } }, "/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``." }, "metadata": { "type": [ "object", "null" ], "description": "The result's metadata block (billing included), present alongside ``output_url`` once a job with ``output_save_url`` has ``completed`` — the delivery moves the content, not the receipt. Same shape as the inline ``result``'s ``metadata``; inline jobs carry it there instead." } } } } } }, "404": { "description": "Not found (e.g. no such job).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "cURL", "source": "curl 'https://api.ade.landing.ai/v2/extract/jobs/JOB_ID' \\\n -H 'Authorization: Bearer YOUR_API_KEY'" }, { "lang": "Python", "label": "Python", "source": "import requests\n\nurl = 'https://api.ade.landing.ai/v2/extract/jobs/JOB_ID'\nheaders = {'Authorization': 'Bearer YOUR_API_KEY'}\n\nresponse = requests.get(url, headers=headers)\nprint(response.json())" }, { "lang": "JavaScript", "label": "Node.js", "source": "const axios = require('axios');\n\naxios.get('https://api.ade.landing.ai/v2/extract/jobs/JOB_ID', {\n headers: { 'Authorization': 'Bearer YOUR_API_KEY' }\n})\n .then(response => console.log(response.data))\n .catch(error => console.error(error));" } ] } } }, "components": { "schemas": { "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" } } } }