> ## Documentation Index
> Fetch the complete documentation index at: https://docs.landing.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ADE Ground

> 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.



## OpenAPI

````yaml /dpt3/openapi-adev2.json post /v2/ground
openapi: 3.1.0
info:
  title: >-
    LandingAI Agentic Document Extraction (ADE) API v2: Parse, Extract, and
    Ground 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. Ground maps extracted fields back to the source blocks,
    with page numbers and bounding boxes for each value. Documentation:
    https://docs.landing.ai
  version: 1.0.0
servers:
  - url: https://api.ade.landing.ai
    description: Production vision tools API
security: []
paths:
  /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
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: >-
                Input to V2GroundOperationWorkflow — the ``/v2/ground`` request
                body.


                A pure, stateless join: each ``extraction_metadata`` leaf's
                ``ranges``

                (char offsets into the markdown both artifacts were produced
                from) is

                overlapped against the ``grounding.range`` carried on every
                ``structure``

                block, and the matching blocks are returned. Nothing is stored
                server-side,

                so block ids in the response resolve only against the
                ``structure`` tree

                supplied here — pairing an extraction with the parse result it
                actually

                came 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
      responses:
        '200':
          description: v2-ground result
          content:
            application/json:
              schema:
                description: >-
                  Result returned by V2GroundOperationWorkflow — the
                  ``/v2/ground``

                  response body.


                  ``grounding`` MIRRORS the ``extraction_metadata`` tree: nested
                  objects and

                  arrays keep their shape, and each ``{value, ranges}`` leaf is
                  replaced by

                  the list of structure blocks its ranges overlap (the block-hit
                  shape

                  documented on the field). It is NOT a flat map — a nested
                  schema field like

                  ``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'
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |-
            curl -X POST 'https://api.ade.landing.ai/v2/ground' \
              -H 'Authorization: Bearer YOUR_API_KEY' \
              -F 'extraction_metadata=<extraction-metadata.json' \
              -F 'structure=<structure.json'
        - lang: Python
          label: Python
          source: |-
            import json
            import requests

            url = 'https://api.ade.landing.ai/v2/ground'
            headers = {'Authorization': 'Bearer YOUR_API_KEY'}

            with open('parse.json') as f:
                parse = json.load(f)
            with open('extract.json') as f:
                extract = json.load(f)

            payload = {
                'extraction_metadata': extract['extraction_metadata'],
                'structure': parse['structure'],
            }

            response = requests.post(url, headers=headers, json=payload)
            print(response.json())
        - lang: JavaScript
          label: Node.js
          source: |-
            const axios = require('axios');
            const fs = require('fs');

            const parse = JSON.parse(fs.readFileSync('parse.json', 'utf8'));
            const extract = JSON.parse(fs.readFileSync('extract.json', 'utf8'));

            axios.post('https://api.ade.landing.ai/v2/ground', {
              extraction_metadata: extract.extraction_metadata,
              structure: parse.structure,
            }, {
              headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
            })
              .then(response => console.log(response.data))
              .catch(error => console.error(error));
components:
  schemas:
    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
    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.
    V2Billing:
      description: |-
        Billing summary: the service tier the request ran in and the credits
        charged.
      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

````