{
  "openapi": "3.1.0",
  "info": {
    "title": "LandingAI Agentic Document Extraction (ADE) API v2: Parse Documents with DPT-3",
    "description": "Parse 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. Documentation: https://docs.landing.ai",
    "version": "0.1.0"
  },
  "servers": [
    {
      "url": "https://api.ade.landing.ai",
      "description": "Production vision tools API"
    }
  ],
  "paths": {
    "/v2/parse": {
      "post": {
        "summary": "Parse",
        "description": "Parse a PDF or image into structured data using DPT-3, a document parsing model from LandingAI.\n\nUse the response to power retrieval-augmented generation (RAG), intelligent search, key information extraction, and automated document workflows.\n\nEach call returns a reading-order Markdown rendering of the document, a hierarchical structure of its pages and elements, per-element grounding back to the source, and metadata about the request (such as model version, duration, page count, and credit usage).\n\nFor EU users, use this endpoint: `https://api.ade.eu-west-1.landing.ai/v2/parse`.",
        "operationId": "parse_parse_api__post",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_parse_parse_api__post"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ParseResponse"
                }
              }
            }
          },
          "206": {
            "description": "Partial failure — some pages failed, body still carries per-page reasons",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ParseResponse"
                }
              }
            }
          },
          "400": {
            "description": "Unknown version or invalid document_url"
          },
          "413": {
            "description": "Document exceeds 50 MiB size limit"
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "500": {
            "description": "Total failure — every page failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ParseResponse"
                }
              }
            }
          }
        },
        "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\nheaders = {\n    'Authorization': 'Bearer YOUR_API_KEY'\n}\n\nurl = 'https://api.ade.landing.ai/v2/parse'\n\ndata = {\n    'model': 'dpt-3-pro-latest'\n}\n\n# Upload a document\ndocument = open('document.pdf', 'rb')\nfiles = {'document': document}\n\nresponse = requests.post(url, files=files, data=data, headers=headers)\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'));\n\nform.append('model', 'dpt-3-pro-latest');\n\naxios.post('https://api.ade.landing.ai/v2/parse', form, {\n  headers: {\n    'Authorization': 'Bearer YOUR_API_KEY',\n    ...form.getHeaders()\n  }\n})\n.then(response => console.log(response.data))\n.catch(error => console.error(error));"
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "BaseElementOptions": {
        "properties": {
          "caption": {
            "type": "boolean",
            "title": "Caption",
            "default": true
          }
        },
        "type": "object",
        "title": "BaseElementOptions"
      },
      "Body_parse_parse_api__post": {
        "properties": {
          "document": {
            "anyOf": [
              {
                "type": "string",
                "contentMediaType": "application/octet-stream"
              },
              {
                "type": "null"
              }
            ],
            "title": "Document",
            "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": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Document Url",
            "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": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Model",
            "description": "The DPT-3 model snapshot to use for this request. Accepts a dated snapshot (for example, `dpt-3-pro-20250101`) or the `dpt-3-pro-latest` alias. Defaults to the latest DPT-3 Pro snapshot."
          },
          "options": {
            "anyOf": [
              {
                "type": "string",
                "contentMediaType": "application/json",
                "contentSchema": {
                  "$ref": "#/components/schemas/ParseOptions"
                }
              },
              {
                "type": "null"
              }
            ],
            "title": "Options",
            "description": "Optional JSON 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."
          }
        },
        "type": "object",
        "title": "Body_parse_parse_api__post"
      },
      "Document": {
        "properties": {
          "type": {
            "type": "string",
            "const": "document",
            "title": "Type",
            "description": "The node type. Identifies this node as the root of the structure tree.",
            "default": "document"
          },
          "children": {
            "items": {
              "$ref": "#/components/schemas/Page"
            },
            "type": "array",
            "title": "Children",
            "description": "The pages of the document, in source order."
          }
        },
        "type": "object",
        "title": "Document"
      },
      "Element": {
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "text",
              "table",
              "td",
              "th",
              "figure",
              "marginalia",
              "attestation",
              "logo",
              "card",
              "scan_code"
            ],
            "title": "Type",
            "description": "The element type. Determines which optional fields appear on this element."
          },
          "id": {
            "type": "string",
            "title": "Id",
            "description": "A unique identifier for this element within the document. Use it to look up the element's entry in the top-level `grounding` map; treat the value as opaque."
          },
          "span": {
            "prefixItems": [
              {
                "type": "integer"
              },
              {
                "type": "integer"
              }
            ],
            "type": "array",
            "maxItems": 2,
            "minItems": 2,
            "title": "Span",
            "description": "Unicode code point offsets `[start, end)` in the top-level `markdown` string covered by this element."
          },
          "children": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/Element"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Children",
            "description": "The cells (`td` and `th`) of a `table` element. Present only when `type` is `table`."
          },
          "row": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Row",
            "description": "0-indexed row position of this cell within its parent `table`. Present only on `td` and `th` elements."
          },
          "col": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Col",
            "description": "0-indexed column position of this cell within its parent `table`. Present only on `td` and `th` elements."
          },
          "colspan": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Colspan",
            "description": "Number of columns this cell spans. `1` for unmerged cells. Present only on `td` and `th` elements."
          },
          "rowspan": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Rowspan",
            "description": "Number of rows this cell spans. `1` for unmerged cells. Present only on `td` and `th` elements."
          }
        },
        "type": "object",
        "required": [
          "type",
          "id",
          "span"
        ],
        "title": "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."
      },
      "ElementGrounding": {
        "properties": {
          "page": {
            "type": "integer",
            "title": "Page",
            "description": "The 0-indexed page number where this element appears."
          },
          "span": {
            "prefixItems": [
              {
                "type": "integer"
              },
              {
                "type": "integer"
              }
            ],
            "type": "array",
            "maxItems": 2,
            "minItems": 2,
            "title": "Span",
            "description": "Unicode code point offsets `[start, end)` in the top-level `markdown` string covered by this element. Matches the element's `span` in the structure tree."
          },
          "box": {
            "prefixItems": [
              {
                "type": "integer"
              },
              {
                "type": "integer"
              },
              {
                "type": "integer"
              },
              {
                "type": "integer"
              }
            ],
            "type": "array",
            "maxItems": 4,
            "minItems": 4,
            "title": "Box",
            "description": "Bounding box `[left, top, right, bottom]` for the full element on the source page, in the page's `unit` (`pt` for PDFs, `px` for images)."
          },
          "parts": {
            "items": {
              "$ref": "#/components/schemas/GroundingEntry"
            },
            "type": "array",
            "title": "Parts",
            "description": "Finer-grained grounding segments within the element. Per visual line for `text` and `marginalia`; empty for other element types or when `options.grounding.parts` is `false`."
          }
        },
        "type": "object",
        "required": [
          "page",
          "span",
          "box"
        ],
        "title": "ElementGrounding",
        "description": "Grounding for one document element: element-level box + fine-grained parts."
      },
      "ElementsOptions": {
        "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"
          }
        },
        "type": "object",
        "title": "ElementsOptions"
      },
      "FigureOptions": {
        "properties": {
          "caption": {
            "type": "boolean",
            "title": "Caption",
            "default": true
          }
        },
        "type": "object",
        "title": "FigureOptions"
      },
      "GroundingEntry": {
        "properties": {
          "span": {
            "prefixItems": [
              {
                "type": "integer"
              },
              {
                "type": "integer"
              }
            ],
            "type": "array",
            "maxItems": 2,
            "minItems": 2,
            "title": "Span",
            "description": "Unicode code point offsets `[start, end)` in the top-level `markdown` string covered by this part."
          },
          "box": {
            "prefixItems": [
              {
                "type": "integer"
              },
              {
                "type": "integer"
              },
              {
                "type": "integer"
              },
              {
                "type": "integer"
              }
            ],
            "type": "array",
            "maxItems": 4,
            "minItems": 4,
            "title": "Box",
            "description": "Bounding box `[left, top, right, bottom]` for this part on the source page, in the page's `unit` (`pt` for PDFs, `px` for images)."
          }
        },
        "type": "object",
        "required": [
          "span",
          "box"
        ],
        "title": "GroundingEntry",
        "description": "One fine-grained grounding segment (line-level or finer)."
      },
      "GroundingOptions": {
        "properties": {
          "parts": {
            "type": "boolean",
            "title": "Parts",
            "default": true
          }
        },
        "type": "object",
        "title": "GroundingOptions"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "Page": {
        "properties": {
          "type": {
            "type": "string",
            "const": "page",
            "title": "Type",
            "description": "The node type. Identifies this node as a page in the structure tree.",
            "default": "page"
          },
          "page": {
            "type": "integer",
            "title": "Page",
            "description": "The 0-indexed page number in the source document. Not contiguous when `options.pages` filters out some pages."
          },
          "span": {
            "prefixItems": [
              {
                "type": "integer"
              },
              {
                "type": "integer"
              }
            ],
            "type": "array",
            "maxItems": 2,
            "minItems": 2,
            "title": "Span",
            "description": "Unicode code point offsets `[start, end)` in the top-level `markdown` string covered by this page. Zero-length `[n, n]` for failed pages."
          },
          "width": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Width",
            "description": "Page width in `unit`. Omitted when `status` is `failed`."
          },
          "height": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Height",
            "description": "Page height in `unit`. Omitted when `status` is `failed`."
          },
          "dpi": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Dpi",
            "description": "Resolution used for the page's coordinate system. Omitted when `status` is `failed`."
          },
          "unit": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "pt",
                  "px"
                ]
              },
              {
                "type": "null"
              }
            ],
            "title": "Unit",
            "description": "The unit used for page dimensions and grounding coordinates: `pt` for PDFs, `px` for images. Omitted when `status` is `failed`."
          },
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "failed"
            ],
            "title": "Status",
            "description": "Whether this page was parsed successfully (`ok`) or failed (`failed`).",
            "default": "ok"
          },
          "reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Reason",
            "description": "Failure reason. Present only when `status` is `failed`."
          },
          "children": {
            "items": {
              "$ref": "#/components/schemas/Element"
            },
            "type": "array",
            "title": "Children",
            "description": "The elements detected on this page, in reading order."
          }
        },
        "type": "object",
        "required": [
          "page",
          "span"
        ],
        "title": "Page"
      },
      "ParseMetadata": {
        "properties": {
          "job_id": {
            "type": "string",
            "title": "Job Id",
            "description": "A unique identifier for this parse run. Correlates with the job's entry in your billing dashboard."
          },
          "filename": {
            "type": "string",
            "title": "Filename",
            "description": "The filename of the parsed document."
          },
          "version": {
            "type": "string",
            "title": "Version",
            "description": "The exact model snapshot used to parse the document."
          },
          "page_count": {
            "type": "integer",
            "title": "Page Count",
            "description": "Total number of pages in the source document. Includes pages filtered out by `options.pages`; the actual returned pages are in `structure.children`."
          },
          "failed_pages": {
            "items": {
              "type": "integer"
            },
            "type": "array",
            "title": "Failed Pages",
            "description": "0-indexed page numbers that failed to parse. Empty when all pages succeed; failed pages also appear in `structure.children` with `status: failed`."
          },
          "duration_ms": {
            "type": "integer",
            "title": "Duration Ms",
            "description": "Total processing time in milliseconds."
          },
          "markdown_chars": {
            "type": "integer",
            "title": "Markdown Chars",
            "description": "Number of Unicode code points in the returned `markdown` string.",
            "default": 0
          },
          "credit_usage": {
            "type": "number",
            "title": "Credit Usage",
            "description": "Credits consumed by this request.",
            "default": 0
          }
        },
        "type": "object",
        "required": [
          "job_id",
          "filename",
          "version",
          "page_count",
          "duration_ms"
        ],
        "title": "ParseMetadata"
      },
      "ParseOptions": {
        "properties": {
          "pages": {
            "anyOf": [
              {
                "items": {
                  "type": "integer"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Pages"
          },
          "elements": {
            "$ref": "#/components/schemas/ElementsOptions"
          },
          "grounding": {
            "$ref": "#/components/schemas/GroundingOptions"
          }
        },
        "type": "object",
        "title": "ParseOptions"
      },
      "ParseResponse": {
        "properties": {
          "markdown": {
            "type": "string",
            "title": "Markdown",
            "description": "The full document as a single Markdown string, in reading order."
          },
          "metadata": {
            "$ref": "#/components/schemas/ParseMetadata",
            "description": "Information about the request: model version, page count, duration, credit usage, and more."
          },
          "structure": {
            "$ref": "#/components/schemas/Document",
            "description": "The document's hierarchical structure: pages and the elements detected on each page. Spatial information for each element is in `grounding`."
          },
          "grounding": {
            "additionalProperties": {
              "$ref": "#/components/schemas/ElementGrounding"
            },
            "type": "object",
            "title": "Grounding",
            "description": "A map keyed by element ID. Each entry carries the element's page, bounding box, Markdown span, and finer-grained parts."
          }
        },
        "type": "object",
        "required": [
          "markdown",
          "metadata",
          "structure",
          "grounding"
        ],
        "title": "ParseResponse"
      },
      "TableOptions": {
        "properties": {
          "caption": {
            "type": "boolean",
            "title": "Caption",
            "default": true
          },
          "format": {
            "type": "string",
            "enum": [
              "markdown",
              "html"
            ],
            "title": "Format",
            "default": "html"
          }
        },
        "type": "object",
        "title": "TableOptions"
      },
      "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"
      }
    }
  }
}