parse

curl --request POST \
  --url https://ndi-api.nace.ai/v1/parse \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "source": {
    "upload_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "upload"
  }
}
'

{
  "created_at": "2023-11-07T05:31:56Z",
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "kind": "parse",
  "status": "queued",
  "deleted_at": "2023-11-07T05:31:56Z",
  "effort": "<string>",
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>",
    "retryable": true,
    "detail": {}
  },
  "finished_at": "2023-11-07T05:31:56Z",
  "force": true,
  "idempotency_key": "<string>",
  "name": "<string>",
  "payload_expires_at": "2023-11-07T05:31:56Z",
  "progress": {
    "items_done": 0,
    "items_failed": 0,
    "items_total": 123,
    "stage": "<string>",
    "units_done": 0,
    "units_total": 123
  },
  "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "query": "<string>",
  "query_scope": {
    "type": "workspace"
  },
  "result": {
    "document": {
      "page_count": 123,
      "blocks": [
        {
          "content": "<string>",
          "id": "<string>",
          "type": "<string>",
          "confidence": 123,
          "image_url": "<string>",
          "location": {
            "page": 2,
            "kind": "page_region",
            "polygons": [
              [
                [
                  123,
                  123
                ]
              ]
            ]
          }
        }
      ],
      "chunks": [
        {
          "content": "<string>",
          "id": "<string>",
          "location": {
            "page": 2,
            "kind": "page_region",
            "polygons": [
              [
                [
                  123,
                  123
                ]
              ]
            ]
          }
        }
      ],
      "markdown": "<string>",
      "ocr": {
        "lines": [
          {
            "bbox": {
              "height": 123,
              "left": 123,
              "original_page": 123,
              "page": 123,
              "top": 123,
              "width": 123
            },
            "confidence": 123,
            "text": "<string>",
            "chunk_index": 123,
            "rotation": 0
          }
        ],
        "words": [
          {
            "bbox": {
              "height": 123,
              "left": 123,
              "original_page": 123,
              "page": 123,
              "top": 123,
              "width": 123
            },
            "confidence": 123,
            "text": "<string>",
            "chunk_index": 123,
            "rotation": 0
          }
        ]
      },
      "spreadsheet": {
        "sheets": [
          {
            "cell_map_url": "<string>",
            "sheet_name": "<string>"
          }
        ]
      },
      "text": "<string>"
    },
    "file_name": "<string>",
    "lane": "<string>",
    "ocr_applied": true,
    "units": 123,
    "converted_pdf_url": "<string>",
    "result_type": "parse"
  },
  "result_state": "available",
  "source": {
    "upload_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "upload"
  },
  "started_at": "2023-11-07T05:31:56Z",
  "units": 0,
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "error": {
    "code": "invalid_request",
    "detail": null,
    "message": "Request body has extra fields that this operation does not accept.",
    "request_id": "req-01j9k2n3p4q5r6s7t8v9",
    "retryable": false
  }
}

{
  "error": {
    "code": "invalid_request",
    "detail": null,
    "message": "Request body has extra fields that this operation does not accept.",
    "request_id": "req-01j9k2n3p4q5r6s7t8v9",
    "retryable": false
  }
}

parse

Parse a document into structured text, Markdown, or block JSON.

Cost class: job (processing units proportional to page count and OCR load; billed on completion).

Accepts any source a granular operation can read — a staged upload, an https:// URL, a workspace file, or a prior Parse job. Returns 202 with a queued :class:~ndi_service.app.platform_api.results.Job immediately; pass ?wait_seconds=N to block up to N seconds for the result inline.

OCR is applied automatically when the document needs it; the result’s ocr_applied flag reports whether it ran.

POST

parse

curl --request POST \
  --url https://ndi-api.nace.ai/v1/parse \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "source": {
    "upload_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "upload"
  }
}
'

{
  "created_at": "2023-11-07T05:31:56Z",
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "kind": "parse",
  "status": "queued",
  "deleted_at": "2023-11-07T05:31:56Z",
  "effort": "<string>",
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>",
    "retryable": true,
    "detail": {}
  },
  "finished_at": "2023-11-07T05:31:56Z",
  "force": true,
  "idempotency_key": "<string>",
  "name": "<string>",
  "payload_expires_at": "2023-11-07T05:31:56Z",
  "progress": {
    "items_done": 0,
    "items_failed": 0,
    "items_total": 123,
    "stage": "<string>",
    "units_done": 0,
    "units_total": 123
  },
  "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "query": "<string>",
  "query_scope": {
    "type": "workspace"
  },
  "result": {
    "document": {
      "page_count": 123,
      "blocks": [
        {
          "content": "<string>",
          "id": "<string>",
          "type": "<string>",
          "confidence": 123,
          "image_url": "<string>",
          "location": {
            "page": 2,
            "kind": "page_region",
            "polygons": [
              [
                [
                  123,
                  123
                ]
              ]
            ]
          }
        }
      ],
      "chunks": [
        {
          "content": "<string>",
          "id": "<string>",
          "location": {
            "page": 2,
            "kind": "page_region",
            "polygons": [
              [
                [
                  123,
                  123
                ]
              ]
            ]
          }
        }
      ],
      "markdown": "<string>",
      "ocr": {
        "lines": [
          {
            "bbox": {
              "height": 123,
              "left": 123,
              "original_page": 123,
              "page": 123,
              "top": 123,
              "width": 123
            },
            "confidence": 123,
            "text": "<string>",
            "chunk_index": 123,
            "rotation": 0
          }
        ],
        "words": [
          {
            "bbox": {
              "height": 123,
              "left": 123,
              "original_page": 123,
              "page": 123,
              "top": 123,
              "width": 123
            },
            "confidence": 123,
            "text": "<string>",
            "chunk_index": 123,
            "rotation": 0
          }
        ]
      },
      "spreadsheet": {
        "sheets": [
          {
            "cell_map_url": "<string>",
            "sheet_name": "<string>"
          }
        ]
      },
      "text": "<string>"
    },
    "file_name": "<string>",
    "lane": "<string>",
    "ocr_applied": true,
    "units": 123,
    "converted_pdf_url": "<string>",
    "result_type": "parse"
  },
  "result_state": "available",
  "source": {
    "upload_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "upload"
  },
  "started_at": "2023-11-07T05:31:56Z",
  "units": 0,
  "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "error": {
    "code": "invalid_request",
    "detail": null,
    "message": "Request body has extra fields that this operation does not accept.",
    "request_id": "req-01j9k2n3p4q5r6s7t8v9",
    "retryable": false
  }
}

{
  "error": {
    "code": "invalid_request",
    "detail": null,
    "message": "Request body has extra fields that this operation does not accept.",
    "request_id": "req-01j9k2n3p4q5r6s7t8v9",
    "retryable": false
  }
}

Authorizations

X-API-Key

string

header

required

Headers

Idempotency-Key

string | null

Replaying a request with the same key returns the original job with 200, never a second job.

Maximum string length: 200

Query Parameters

wait_seconds

integer

default:0

Bounded inline wait. 0 (the default) returns 202 immediately. Above 0 the route returns 200 with a terminal job if the work finished in time, and 202 with the still-running job if it did not. Either way, read status.

Required range: 0 <= x <= 300

Body

application/json

Body for canonical POST /v1/parse (and the hidden legacy alias).

page_ranges is the canonical one-based inclusive selector. Legacy page_range / pages remain accepted on the wire during rollout.

password is write-only: it is never stored in ndi_job.input or returned in any response. The service stores an AES-GCM-encrypted copy in ndi_job_secret for the unlock activity to consume once, then deletes it.

source

UploadSource · object

required

Bytes staged through POST /v1/uploads. Single-use, TTL-bound.

UploadSource
UrlSource
WorkspaceFileSource
ParseResultSource

Show child attributes

chunking

ParseChunkingOptions · object

Show child attributes

corpus_sources

WorkspaceFileSource · object[]

Workspace files visible in the run tray, including files not submitted by this request.

Maximum array length: 50

Show child attributes

diagrams

ParseDiagramsOptions · object

Show child attributes

figures

ParseFiguresOptions · object

Show child attributes

name

string | null

Display name for this run. The console calls a named run a 'project'.

Maximum string length: 200

ocr

ParseOcrOptions · object

Show child attributes

output

ParseOutputOptions · object

Show child attributes

output_formats

enum<string>[] | null

Legacy formats list. Prefer output.formats.

Available options:

markdown,

text,

blocks

page_range

Page Range · object | null

Show child attributes

page_ranges

PageRange · object[] | null

Maximum array length: 200

Show child attributes

pages

PageSelection · object | null

Legacy page selector. Prefer page_ranges.

Show child attributes

parser

enum<string> | null

Optional parse pipeline. Omit or null for native (the default). 'datalab' and 'nace_router' are explicit opt-in providers.

Available options:

native,

datalab,

nace_router

password

string | null

Optional PDF password. Never stored in the job payload or returned in any response.

Maximum string length: 1024

project_id

string<uuid> | null

Caller-minted grouping id; jobs submitted together share it. Not a server-side resource.

quality

enum<string>

default:auto

Available options:

auto,

fast,

accurate

spreadsheet

ParseSpreadsheetOptions · object

Workbook-specific Parse controls for spreadsheet sources.

Defaults preserve the pre-control behavior: every sheet/row/column is included and formula source text is omitted (cached values still appear).

Show child attributes

Response

Successful Response

Every slow method returns one of these (spec 12 §1.4).

There is no /parse + /parse_async pair: every job-creating route returns 202 with a queued job and accepts ?wait_seconds=, returning 200 with a terminal job if the work finished inside the window. The caller's code path is the same either way — read status.

created_at

string<date-time>

required

job_id

string<uuid>

required

kind

enum<string>

required

What a job is doing. Open enum — a new member is additive.

Available options:

parse,

split,

classify,

categorize,

extract,

ground,

ingestion,

reconciliation,

kg_build,

file_upload,

file_replace,

upload_session_complete,

file_delete,

workspace_delete,

intelligent_search,

qa_file,

qa_tables,

filtered_search,

je_testing,

deep_search_v2

status

enum<string>

required

cancelled is a first-class terminal status, not a failed variant.

Conflating them makes error-rate metrics lie and forces every client to string-match an error code.

Available options:

queued,

running,

succeeded,

failed,

cancelled

deleted_at

string<date-time> | null

When the caller hid this run from listings, via delete_job. A soft delete: the job still reads by id and still counts toward GET /v1/usage — what it stops doing is appearing in GET /v1/jobs.

effort

string | null

Which implementation ran this job, for the one kind whose request carries an effort (intelligent_search): 'fast' is fact-search, 'deep' (or the legacy 'balanced') is deep-search and the console's QA chat — a deep-search run under another surface, not a fourth implementation, so this field cannot tell those two apart. Null for every other kind. Read from the stored request, so it rides the same retention path as query and result: null once result_state leaves available.

error

Error · object | null

Present only on failed.

Show child attributes

finished_at

string<date-time> | null

force

boolean | null

The request's own force flag, echoed regardless of outcome. Present for kinds whose request carries one (e.g. kg_build, where a true value cleared the durable store before the job ran) so a caller can tell that apart from a build that failed leaving the prior store untouched — result alone cannot, since it is absent on failure either way.

idempotency_key

string | null

name

string | null

Caller-chosen display name (the console's 'project'). Mutable via PATCH /v1/jobs/{job_id}.

payload_expires_at

string<date-time> | null

progress

JobProgress · object | null

Absent until running.

Show child attributes

project_id

string<uuid> | null

Caller-minted grouping id shared by jobs submitted together. Filterable on GET /v1/jobs.

query

string | null

The question this job was asked, for the search kinds that carry one (intelligent_search, qa_file, qa_tables, filtered_search); null for every other kind. Read from the stored request, so it rides the same retention path as result: null once result_state leaves available. Narrow by design — the frozen access context never reaches the wire. File scope is summarised separately as query_scope.

query_scope

WorkspaceQueryScope · object

The question ran against the whole workspace.

WorkspaceQueryScope
FileQueryScope
PathPrefixQueryScope
FilesQueryScope

Show child attributes

result

ParseResult · object

Present only on succeeded, and only while retained.

Show child attributes

result_state

enum<string>

default:available

Why Job.result is null.

available with a null result means the job has not succeeded yet; expired means retention dropped it; not_retained means the client is provisioned zero_retention and already had its one chance to read it. A late poll returns the job with a state, never a 404 — "this expired" and "this never existed" are a scheduling problem and a bug respectively, and a 404 makes them identical.

Available options:

available,

expired,

not_retained

source

UploadSource · object

Bytes staged through POST /v1/uploads. Single-use, TTL-bound.

UploadSource
UrlSource
WorkspaceFileSource
ParseResultSource

Show child attributes

started_at

string<date-time> | null

units

integer

default:0

workspace_id

string<uuid> | null

The workspace this job reads. Null for a document operation whose source is an upload, a URL, or a prior parse result.

Conventions

Granular operations

Catalog

Workspaces and files

Ingestion and graph

Tools and search

Jobs and usage

parse

Authorizations

Headers

Query Parameters

Body

Response