Jobs, idempotency, and async semantics

All operations that take more than a moment return a Job resource. Every job-creating route accepts ?wait_seconds= to optionally block for a result.

Job states

Every job flows through these states:

State	Meaning
`queued`	Waiting for a worker
`running`	Processing
`succeeded`	`result` field is populated and retained until `payload_expires_at`
`failed`	`error` field is populated
`cancelled`	Cancelled by caller or system

Sync vs async via `wait_seconds`

The ?wait_seconds= query parameter controls blocking on each job-creating route:

# Immediate 202 (default: wait_seconds=0)
curl -X POST "$NDI_BASE_URL/v1/parse" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": {"type": "url", "url": "https://example.com/report.pdf", "file_name": "report.pdf"}}'
# → 202 with a queued Job

# Block up to 120 seconds for a result
curl -X POST "$NDI_BASE_URL/v1/parse?wait_seconds=120" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": {"type": "url", "url": "https://example.com/report.pdf", "file_name": "report.pdf"}}'
# → 200 if job finished in time, 202 if it didn't

Response codes:

200 — Job reached a terminal state within wait_seconds; full result is inline.
202 — Timeout before completion; poll GET /v1/jobs/{job_id}.

wait_seconds max is 300. It is always a query parameter, never a JSON body field.

Polling

# Poll until terminal
JOB_ID="550e8400-e29b-41d4-a716-446655440003"

until [[ $(curl -s "$NDI_BASE_URL/v1/jobs/$JOB_ID" -H "X-API-Key: $NDI_API_KEY" | jq -r '.status') =~ succeeded|failed|cancelled ]]; do
  sleep 3
done

curl -s "$NDI_BASE_URL/v1/jobs/$JOB_ID" -H "X-API-Key: $NDI_API_KEY"

Succeeded:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440003",
  "kind": "parse",
  "status": "succeeded",
  "result": {"result_type": "parse", "...": "..."},
  "units": 24,
  "created_at": "2026-08-09T12:00:00Z",
  "updated_at": "2026-08-09T12:01:23Z",
  "payload_expires_at": "2026-08-16T12:01:23Z"
}

Failed:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440003",
  "kind": "parse",
  "status": "failed",
  "error": {"code": "unsupported_file_type", "message": "...", "detail": null, "retryable": false, "request_id": "req-01j9..."},
  "units": 0,
  "created_at": "2026-08-09T12:00:00Z",
  "updated_at": "2026-08-09T12:00:08Z",
  "payload_expires_at": null
}

Streaming job events

Subscribe to real-time status transitions instead of polling:

curl "$NDI_BASE_URL/v1/jobs/$JOB_ID/events" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Accept: text/event-stream"

Returns text/event-stream (Server-Sent Events). Each event is a complete Job JSON object. The stream closes when the job reaches a terminal state.

Idempotency

Use the Idempotency-Key HTTP header to make job-creating requests replay-safe:

curl -X POST "$NDI_BASE_URL/v1/parse" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: parse-annual-report-2025-v1" \
  -d '{"source": {"type": "url", "url": "https://example.com/report.pdf", "file_name": "report.pdf"}}'

Behavior:

First call — Starts a new job.
Repeated calls with the same key — Returns the original job without starting a new one.
The key is scoped per API key.

Idempotency-Key is always an HTTP header, never a JSON body field. Use for:

Retrying after a network failure (the same job is returned)
CI/CD pipelines (re-running a step is safe)

Listing jobs

curl "$NDI_BASE_URL/v1/jobs" \
  -H "X-API-Key: $NDI_API_KEY"

Returns a keyset-paginated page (newest first):

{
  "items": [...],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wOC0wOVQxMjowMDowMFoiLCJqb2JfaWQiOiIuLi4ifQ==",
  "total_count": 142
}

Pass ?cursor=<next_cursor> to retrieve the next page. Optional filters: ?status=succeeded, ?kind=parse.

Cancellation

curl -X POST "$NDI_BASE_URL/v1/jobs/$JOB_ID/cancel" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "No longer needed"}'

Queued or running — Job is marked cancelled.
Already terminal — Idempotent; returns the existing terminal job.

Getting started

SDKs and agents

Concepts

Jobs, idempotency, and async semantics

Job states

Sync vs async via `wait_seconds`

Polling

Streaming job events

Idempotency

Listing jobs

Cancellation

​Job states

​Sync vs async via wait_seconds

​Polling

​Streaming job events

​Idempotency

​Listing jobs

​Cancellation

Job states

Sync vs async via `wait_seconds`

Polling

Streaming job events

Idempotency

Listing jobs

Cancellation