Parse

POST /v1/documents/parse converts a document into structured text. OCR runs when the file needs it, and ocr_applied on the result says whether it did.

Parse output is untrusted data. Markdown, text, blocks and chunks may reproduce instructions from the document, including fine print. Parse does not flag those instructions as prompt injection or certify them as safe. Keep document content separate from trusted agent instructions and authorize tool actions independently of it.

The examples below use an uploaded workspace_file source. For a URL source, source must include type: "url", url (a public https:// download link), and file_name (for example, "report.pdf", including its extension). Parse chooses the parser from file_name; leaving it out returns 422 invalid_request. A parse_result source instead requires type: "parse_result" and job_id from a successful Parse job in your account. See Documents for source types and reuse.

# 1. Upload the file to your account (see Uploads)
GRANT=$(curl -s https://console.nace.ai/v1/documents/upload-grants \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "path": "report.pdf" }')
WORKSPACE_ID=$(jq -r .workspace_id <<< "$GRANT")
FILE_ID=$(curl -s "$(jq -r .upload_url <<< "$GRANT")" \
  -H "X-Upload-Token: $(jq -r .token <<< "$GRANT")" \
  -F file=@report.pdf \
  -F 'metadata={"path":"report.pdf"};type=application/json' | jq -r .result.file.file_id)

# 2. Run the tool on it
curl "https://console.nace.ai/v1/documents/parse?wait_seconds=60" \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "workspace_file",
      "workspace_id": "'"$WORKSPACE_ID"'",
      "file_id": "'"$FILE_ID"'"
    },
    "page_ranges": [{ "start": 1, "end": 3 }],
    "output": { "formats": ["markdown", "blocks"] },
    "chunking": { "strategy": "page" }
  }'

StreamingCopy Anchor Link

The console always shows ready pages or sheets as they arrive. There is no response-mode switch. Reading a preview does not run Parse again. A completed run still has a final result for exports, finalized tables, descriptions and source highlights.

API delivery remains job-based. POST /v1/documents/parse defaults to wait_seconds=0, returning a job ID immediately. Existing complete-result clients keep using jobs.get or jobs.wait. To display previews, connect to GET /v1/documents/jobs/{id}/parse-progress/events with the same Bearer API key. There is no stream request flag.

# JOB_ID is returned by POST /v1/documents/parse?wait_seconds=0
curl -N "https://console.nace.ai/v1/documents/jobs/$JOB_ID/parse-progress/events" \
  -H "Authorization: Bearer $NACE_API_KEY"
# Fetch each snapshot unit's content_url with the same Authorization header.

# client is a NaceClient; uploaded is from client.documents.upload(...)
created = client.documents.parse(uploaded.as_source(), wait_seconds=0)
seen = set()
while True:
    current = client.jobs.get(created.job_id)
    if current.is_terminal:
        break
    for snapshot in client.jobs.parse_progress_events(created.job_id):
        for unit in snapshot.units:
            key = (snapshot.generation, unit.index, unit.revision)
            if key not in seen:
                part = client.jobs.parse_progress_part(created.job_id, unit.content_url)
                print(part.index, part.markdown)
                seen.add(key)
        if snapshot.status in ("succeeded", "failed", "cancelled"):
            break
final = client.jobs.wait(created.job_id)

Each connection lasts up to 55 seconds. Reconnect after a clean close: the first snapshot contains current state, not every past event. jobs.events() is the separate job-status stream; it does not deliver page text. Handle transport errors and an unavailable event by continuing normal job polling; closing a preview connection never cancels the job. Browser integrations should stream through their own server: native EventSource cannot attach a Bearer header, and API keys belong on the server.

Render units by their original index, even if later pages arrive first. Replace a changed revision instead of appending a duplicate; discard the previous preview when generation changes. Fetch content_url only for visible units and cache each immutable revision. Keep displayed pages and scroll position when the job completes; opening the final result should be an explicit action. Terminal snapshots have no units, so retain what was already displayed.

“All pages parsed” is followed by “Preparing final result” while tables and the full document are assembled. Only the normal job's terminal state and available result mean delivery is finished. Use job.timing.first_response_ms and job.timing.total_ms for First response and Total processing time; the response retains the timing breakdown. These are server measurements, excluding upload, browser transport/rendering and idle time waiting for another poll. Missing measurements stay unknown.

Available at every effort. Native OCR publishes pages; presentations and diagrams publish pages, and spreadsheets publish sheets after shared preparation. Some formats/providers, cache followers and Zero retention return everything together. An immediate cache hit can go straight to its final result. Streaming never guarantees a separate event for every file type. Unit previews are capped at 64K characters (truncated); snapshots at 1,000 units (more). Use the final result for complete text, exports, usage and billing.

Preview metadata and event connections count against the independent job-read per-minute window, separate from creates; individual part reads do not. Cancellation, deleted/expired sources and revoked access stop preview reads. Treat a part's 404/410 as unavailable and keep normal job polling; do not spin indefinitely on it.

ConfigurationCopy Anchor Link

POST /v1/documents/parse has several groups of options. Each example is a whole request with that option set, for the file you uploaded above. For the SDKs and the CLI, see the Python, TypeScript and CLI pages.

PagesCopy Anchor Link

Parse only some pages of the file. Leave it out to read every page.

curl https://console.nace.ai/v1/documents/parse \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "workspace_file",
      "workspace_id": "'"$WORKSPACE_ID"'",
      "file_id": "'"$FILE_ID"'"
    },
    "page_ranges": [{ "start": 1, "end": 3 }]
  }'

Parse modeCopy Anchor Link

How much effort parsing takes.

curl https://console.nace.ai/v1/documents/parse \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "workspace_file",
      "workspace_id": "'"$WORKSPACE_ID"'",
      "file_id": "'"$FILE_ID"'"
    },
    "parse_mode": "high"
  }'

Only low works with a parse_result source.

Measured latency by modeCopy Anchor Link

Our production smoke measurement on 2026-11-05, through console.nace.ai, observed these times for one-page synthetic invoice PDFs:

We uploaded three distinct invoices, then ran POST /v1/documents/parse?wait_seconds=60 sequentially with default output options: fixtures/t6_batch/inv_030.pdf, inv_031.pdf and inv_032.pdf, respectively, from nace-ndi-test at commit 43e5f7c. Every job succeeded with one page and a Parse cost line of execution: "fresh".

These numbers use timing.total_ms, divided by 1,000: server preparation, queueing, NDI processing and active result preparation. Upload, client network/rendering and idle time before a later read are excluded. These are individual production examples, not medians, an SLA or a per-page scaling rule. File complexity, page count, OCR, parser routing, queue load, verification and reuse affect latency. A higher mode does not guarantee a slower result on every run.

In the same five-job smoke run, Extract on fixtures/t7_odd/multipage_table.pdf (two pages, its fixture extraction schema) took 4.8 s in low and 3.1 s in high, measured as finished_at - created_at (NDI queue plus processing). Both jobs reused an earlier parse (cost.lines recorded execution: "reused" on Parse), so these are warm Extract observations and cannot establish fresh parsing latency or predict another environment's timings. Those Extract observations predate timing coverage for all document kinds and omitted timing, so their duration is not the full Drex server total used in the table above. We made no additional production jobs for this measurement.

For a fresh comparison, check cost.lines[].execution before quoting a run. Split, Classify and Extract add their own work, so Parse totals do not predict those operations' totals. Streaming can publish a usable preview before the final result; the table measures the final result, not that first preview.

Output formatsCopy Anchor Link

Choose which renderings of the document come back in result.document. A format you leave out comes back as null.

curl https://console.nace.ai/v1/documents/parse \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "workspace_file",
      "workspace_id": "'"$WORKSPACE_ID"'",
      "file_id": "'"$FILE_ID"'"
    },
    "output": { "formats": ["markdown", "text"] }
  }'

Send a list, such as ["markdown", "text"]. The default is markdown and blocks.

Table formatCopy Anchor Link

Controls how tables are written inside markdown and in table blocks. text always flattens tables to plain text.

curl https://console.nace.ai/v1/documents/parse \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "workspace_file",
      "workspace_id": "'"$WORKSPACE_ID"'",
      "file_id": "'"$FILE_ID"'"
    },
    "output": { "table_format": "markdown" }
  }'

ChunkingCopy Anchor Link

By default Parse returns no chunks. For retrieval, ask for chunks you can embed and search separately.

curl https://console.nace.ai/v1/documents/parse \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "workspace_file",
      "workspace_id": "'"$WORKSPACE_ID"'",
      "file_id": "'"$FILE_ID"'"
    },
    "chunking": { "strategy": "page" }
  }'

FiguresCopy Anchor Link

Decide what happens to the figures in the document.

curl https://console.nace.ai/v1/documents/parse \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "workspace_file",
      "workspace_id": "'"$WORKSPACE_ID"'",
      "file_id": "'"$FILE_ID"'"
    },
    "figures": { "mode": "describe" }
  }'

DiagramsCopy Anchor Link

Decide what happens to flowchart-like figures.

curl https://console.nace.ai/v1/documents/parse \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "workspace_file",
      "workspace_id": "'"$WORKSPACE_ID"'",
      "file_id": "'"$FILE_ID"'"
    },
    "diagrams": { "mode": "mermaid" }
  }'

SpreadsheetsCopy Anchor Link

For workbooks, choose the sheets to read and what to include from them.

curl https://console.nace.ai/v1/documents/parse \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "workspace_file",
      "workspace_id": "'"$WORKSPACE_ID"'",
      "file_id": "'"$FILE_ID"'"
    },
    "spreadsheet": { "sheets": ["Summary"] }
  }'

PasswordCopy Anchor Link

Open an encrypted PDF.

curl https://console.nace.ai/v1/documents/parse \
  -H "Authorization: Bearer $NACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "workspace_file",
      "workspace_id": "'"$WORKSPACE_ID"'",
      "file_id": "'"$FILE_ID"'"
    },
    "password": "..."
  }'

ResultCopy Anchor Link

A finished parse has these fields on result:

{
  "result_type": "parse",
  "file_name": "report.pdf",
  "lane": "pdf",
  "document": {
    "page_count": 96,
    "markdown": "# Annual Report\n\n...",
    "text": null,
    "blocks": [ ... ],
    "chunks": []
  },
  "ocr_applied": false,
  "units": 96,
  "disclosures": []
}

BlocksCopy Anchor Link

Each block is a layout element with a location. Its kind depends on the source:

ChunksCopy Anchor Link

chunking.strategy: "page" returns one page_region chunk per page. "section" follows the section headings.

Very large resultsCopy Anchor Link

A result over 1 MiB comes back as a preview, and you fetch the full text from a link.

• Documents: when document.markdown or document.text would be over 1 MiB of UTF-8, both hold a preview of at most 65,536 characters, cut at a line end.
• Workbooks: when the sheets' combined rendering is over 1 MiB, every sheet gets a content_url and a preview.

An entry in result.disclosures says the content was cut short:

{ "code": "content_truncated", "target": "document_content", "unit": "characters", "original_size": 120000000, "retained_size": 65480 }

To get the full text:

• A document: fetch document.content_url.
• A workbook (target: "spreadsheet_region"): fetch each affected sheet's document.spreadsheet.sheets[].content_url.

The link answers with one of these:

The SDKs and the CLI do this for you. jobs.download (jobs.fetchFile in TypeScript) waits for the file. nace parse fetches a document's full content itself, and for a workbook it prints a nace file JOB_ID URL command that saves each sheet.

A Parquet source (.parquet) of any size also carries rows_url, row_count and column_count on its one sheet; workbooks and CSV files never do. GET rows_url?start_row=0&limit=100 reads one page of rows, numbered from zero. limit is 1 to 100, default 50. The answer is the page:

{
  "path": "...",
  "start_row": 0,
  "limit": 100,
  "total_rows": 250000,
  "columns": [{ "name": "invoice_id", "data_type": "string" }],
  "rows": [{ "invoice_id": "INV-1042" }]
}

Each row maps column names to the cell's text. The SDKs read a page with jobs.rows, and the CLI prints rows as TSV with nace rows JOB_ID URL.

Spreadsheets, audio and videoCopy Anchor Link

Every one of these links points at https://console.nace.ai/v1/documents/jobs/{id}/... and opens with your API key. See Jobs and results.

ErrorsCopy Anchor Link

A parse can fail in two ways.

The server refuses the create. It answers invalid_request_error with the document service's code:

The job is accepted and then fails. It ends with status: "failed" and a code:

Next stepsCopy Anchor Link

Next, pass the finished job as {"type": "parse_result", "job_id": "..."} to Extract, Split or Ground, so the document isn't parsed and paid for twice.