Get the document structure as JSON

Every queued job produces two results: Markdown and a JSON structure file (DoclingDocument). Download the JSON with format=json when you need to know what was a heading or a table. It also records where each item was.

The direct call returns Markdown only.

What the JSON contains

The file starts with schema_name and version. The lists texts, tables and pictures hold the items. Each item has a label such as section_header, paragraph, list_item or caption. It also has a prov list with page_no and a bounding box. pages is an object keyed by page number.

Fetch both formats

curl -H "X-API-Key: $FLATMARK_API_KEY" \
  "https://api.flatmark.dev/v1/convert/jobs/$JOB_ID/result?format=markdown" -o doc.md
curl -H "X-API-Key: $FLATMARK_API_KEY" \
  "https://api.flatmark.dev/v1/convert/jobs/$JOB_ID/result?format=json" -o doc.json

Python: list headings and tables

import httpx

job_id = "YOUR_JOB_ID"
doc = httpx.get(
    f"https://api.flatmark.dev/v1/convert/jobs/{job_id}/result",
    params={"format": "json"},
    headers={"X-API-Key": "YOUR_KEY"},
    timeout=60,
).raise_for_status().json()

print(doc["schema_name"], doc["version"])
for item in doc["texts"]:
    if item["label"] == "section_header":
        print("heading:", item["text"])
for table in doc["tables"]:
    pages = [p["page_no"] for p in table["prov"]]
    print(f"table {table['data']['num_rows']}x{table['data']['num_cols']} on page {pages}")

When to use the JSON

Use it to cite pages in answers or to pull out only the tables. You can also chunk at item boundaries, so a table stays whole. For a prompt, use the Markdown: the JSON is much larger. Results are deleted 7 days after submission.

Next step

Submit a file to the queue and download both results.

FAQ

Can I get the JSON from a direct call?

No. The direct call to /v1/convert returns Markdown only. The JSON structure file comes from queued jobs.

How long can I download the JSON?

Results are deleted 7 days after submission. Download both files before then.