landing-ai/ade-document-processing-skills/document-extraction

Document Extraction (ADE)

Overview

LandingAI's Agentic Document Extraction (ADE) is a document processing service that parses, extracts, and classifies documents without templates or training. The REST APIs are the primary interface. Official libraries wrap them for Python (landingai-ade on PyPI) and TypeScript (landingai-ade on npm).

ADE has two API generations. The v2 APIs (powered by DPT-3) are the current generation for parsing and extraction. Several capabilities exist only as v1 APIs and remain fully supported.

Every linked docs page can be fetched as raw Markdown by appending .md to its URL (for example, https://docs.landing.ai/dpt3/parse.md). A page index lives at https://docs.landing.ai/llms.txt. Full request and response contracts are in the API reference (linked per endpoint below).

Which API Version? {#which-api-version}

Use the v2 APIs by default. File format is not a reason to use v1: v2 Parse accepts PDFs, images, Office documents (DOCX, DOC, PPTX, PPT, ODT, RTF), and spreadsheets (XLSX, CSV); the formats it rejects are in Core Flow Step 1. Route to v1 only when one of these applies:

• The user has existing code calling the /v1/ade/* endpoints (or v1 library methods client.parse() / client.extract()) and has not asked to migrate.
• The pipeline needs custom figure prompts or v1-style page splits (split=page).
• The pipeline feeds Parse output into the v1 Section or v1 Split APIs, which require the v1 Parse response shape.

A password is not a reason to route to v1: both versions decrypt only PDFs (v2 through options.password, see Core Flow) and return HTTP 422 for a password sent with any other file type, so decrypt other files before uploading.

To move an existing v1 pipeline to v2, follow https://docs.landing.ai/dpt3/migration-guide.

Do not mix versions within one pipeline, except as this matrix allows:

The v1 Classify API takes the raw document, not Parse output, so it composes with either version.

API Drift: Your Prior Knowledge May Be Stale

If you have seen ADE code before, it was probably v1. These v1 idioms cause silent wrong-output bugs in v2 code:

For the full v1-to-v2 request and response mapping, see https://docs.landing.ai/dpt3/migration-guide.

Setup

API Key

All endpoints authenticate with the same header: Authorization: Bearer YOUR_API_KEY. Get a key at https://va.landing.ai/settings/api-key and set it as the VISION_AGENT_API_KEY environment variable (both libraries read it automatically). Before asking the user for a key, check for an existing .env file in the working directory and in this skill's own directory (skills/document-extraction/.env); a .env-sample template sits next to this file. Keys are region-specific; for EU endpoints and data residency see https://docs.landing.ai/dpt3/eu.

Libraries (optional)

• Python: pip install landingai-ade (v1.18.1 or later covers everything in this skill). Guide: https://docs.landing.ai/dpt3/ade-python
• TypeScript: npm install landingai-ade (v2.13.1 or later covers everything in this skill). Guide: https://docs.landing.ai/dpt3/ade-typescript

When writing scripts, use the user's language and environment. Never install packages globally; use the project's virtualenv or package.json.

Core Flow: Parse, Extract, Then Ground (v2)

Parse converts a document into Markdown plus structure. Extract pulls schema-defined fields from that Markdown. Run both as jobs on the `standard` service tier: create the job, then call wait() (or poll GET .../jobs/{job_id}) for the finished job. Standard jobs cost half the credits of priority; see Processing Modes below for when to leave this default. Keep the trailing <!-- doc_id=... --> comment when saving Markdown; v2 Extract reads it to link the extraction back to its parse job.

Step 1: Parse. Jobs accept PDFs, images, Office documents (DOCX, DOC, PPTX, PPT, ODT, RTF), and spreadsheets (XLSX, CSV, up to 50 MB), up to 1 GiB for PDFs and 50 MiB for images; for the current page limits, see https://docs.landing.ai/dpt3/rate-limits. Parse rejects HTML, XLS, ODS, and ODP files with HTTP 422, so convert those first. It detects most formats from the file content, but CSV, TGA, DOC, and PPT files must keep their extension (.csv, .tga, .doc, .ppt) in the uploaded filename. DOCX, DOC, PPTX, PPT, ODT, and RTF files are converted to PDF before parsing; the conversion can change layout and page count, and page-based limits and credits apply to the converted PDF's page count (https://docs.landing.ai/dpt3/file-types). Models: dpt-3-pro-latest (default, highest quality) or dpt-3-verity (preview: lower latency and credits, for digitally created text documents only; renamed from dpt-3-fast, whose values still work). DPT-3 Verity does not read scans, handwriting, or non-Latin scripts, outputs plain Markdown without heading or bold formatting, and adds per-word confidence scores. Comparison and snapshot values: https://docs.landing.ai/dpt3/parse-models.

mkdir -p output
curl -X POST 'https://api.ade.landing.ai/v2/parse/jobs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'document=@document.pdf' \
  -F 'model=dpt-3-pro-latest' \
  -F 'service_tier=standard'
 
# The create response is {"job_id": "...", "status": "pending", ...}.
# Repeat this request with that job_id until status is completed or failed.
# A completed job carries the parse response under result; save result.markdown
# from this file as output/parse-output.md for Step 2 (the library examples do this).
curl 'https://api.ade.landing.ai/v2/parse/jobs/JOB_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY' -o output/parse-response.json

from pathlib import Path
from landingai_ade import LandingAIADE
client = LandingAIADE()
Path("output").mkdir(exist_ok=True)
job = client.v2.parse_jobs.create(
    document=Path("document.pdf"),
    model="dpt-3-pro-latest",
    service_tier="standard",
)
# wait() polls until the job finishes. raise_on_failure turns a failed job into
# JobFailedError instead of returning a job whose result is None.
done = client.v2.parse_jobs.wait(job.job_id, timeout=3600, raise_on_failure=True)
Path("output/parse-response.json").write_text(done.result.model_dump_json(indent=2), encoding="utf-8")
Path("output/parse-output.md").write_text(done.result.markdown, encoding="utf-8")

import fs from "fs";
import LandingAIADE from "landingai-ade";
const client = new LandingAIADE();
fs.mkdirSync("output", { recursive: true });
const job = await client.v2.parseJobs.create({
  document: fs.createReadStream("document.pdf"),
  model: "dpt-3-pro-latest",
  service_tier: "standard",
});
// wait() polls until the job finishes. raiseOnFailure turns a failed job into
// JobFailedError instead of returning a job whose result is null.
const done = await client.v2.parseJobs.wait(job.job_id, { timeout: 3_600_000, raiseOnFailure: true });
const parsed = done.result as LandingAIADE.V2ParseResponse;
if (!parsed.markdown) {
  throw new Error(`Job ${job.job_id} returned no Markdown (status: ${done.status}).`);
}
fs.writeFileSync("output/parse-response.json", JSON.stringify(parsed, null, 2));
fs.writeFileSync("output/parse-output.md", parsed.markdown);

Three things to get right with jobs:

• The output is nested under `result`. A finished job is {job_id, status, result, ...}. When status is completed, the parse response (markdown, structure, metadata) is result, so read done.result.markdown, not done.markdown. When status is failed, result is null and error carries a code and message; the library wait() calls above turn that into JobFailedError.
• `wait()` has a 10-minute default timeout (timeout=600 seconds in Python, timeout: 600000 milliseconds in TypeScript). When it expires, wait() raises JobWaitTimeoutError but the job keeps running server-side. Pass a longer timeout for large documents on standard, as above, or catch the error and resume with parse_jobs.get(job_id) / parseJobs.get(jobId).
• Save the full response, not only the Markdown. Job create methods do not accept save_to / saveTo; write result to disk yourself as shown, or pass output_save_url (see Processing Modes below). The saved JSON carries structure and grounding, which every cropping, table, and RAG workflow below needs.

Useful options (multipart field with a JSON value): {"pages": [1, 3]} (1-indexed page selection; any page beyond the document's last page rejects the whole request with HTTP 422, or fails the job after it starts), {"blocks": {"table": {"format": "markdown"}}} (pipe-syntax tables instead of HTML), {"password": "..."} (encrypted PDFs only; never hard-code it; a missing or wrong password returns HTTP 422 on Parse, while a Parse Jobs create still succeeds and the job ends failed with the cause in error.code). Full contract: Parse API reference, https://docs.landing.ai/dpt3/parse-input.