Sources and uploads

Granular document operations (parse, split, classify, extract, and ground) all accept a source field in the request body. The source is a discriminated union on type:

URL source (`"type": "url"`)

Point an operation at any https:// or s3:// URL:

{
  "source": {
    "type": "url",
    "url": "https://example.com/annual-report.pdf",
    "file_name": "annual-report.pdf"
  }
}

Fields:

url — https:// or s3:// only. NDI verifies the resolved hostname.
file_name — Used to choose the processing lane and appears in result metadata.

Upload source (`"type": "upload"`)

Upload a file via POST /v1/uploads, then reference it by upload_id:

# 1. Upload
UPLOAD=$(curl -s -X POST "$NDI_BASE_URL/v1/uploads" \
  -H "X-API-Key: $NDI_API_KEY" \
  -F "file=@document.pdf")
UPLOAD_ID=$(echo "$UPLOAD" | jq -r '.upload_id')

# 2. Use in an operation
curl -X POST "$NDI_BASE_URL/v1/parse" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": {\"type\": \"upload\", \"upload_id\": \"$UPLOAD_ID\"}}"

Upload response:

{
  "upload_id": "550e8400-e29b-41d4-a716-446655440002",
  "file_name": "document.pdf",
  "size_bytes": 2048000,
  "content_hash": "a3f2b1c0d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1",
  "expires_at": "2026-08-16T12:00:00Z"
}

Upload lifecycle:

TTL is set at upload time via ttl_seconds form field. The default is 7 days; the maximum is also 7 days. The expires_at field in the response shows the exact expiry.
Uploads are not single-use — the same upload_id can be used in multiple operations until it expires.
Upload IDs are scoped to your API key.

Source discriminator:

{
  "source": {
    "type": "upload",
    "upload_id": "550e8400-e29b-41d4-a716-446655440002"
  }
}

Workspace file source (`"type": "workspace_file"`)

Reference a file already stored in a workspace. Granular operations read the raw source bytes — the file does not need to be ingested first.

{
  "source": {
    "type": "workspace_file",
    "workspace_id": "550e8400-e29b-41d4-a716-446655440001",
    "file_id": "550e8400-e29b-41d4-a716-446655440004"
  }
}

This is the bridge between the two integration patterns: you can use granular operations (parse, extract, …) on files already in a workspace.

Parse result source (`"type": "parse_result"`)

Reuse the retained result of a successful Parse job without downloading and uploading the document again:

{
  "source": {
    "type": "parse_result",
    "job_id": "550e8400-e29b-41d4-a716-446655440010"
  }
}

The referenced job must belong to the same API key, have kind: "parse" and status: "succeeded", and still have an available result. Support varies by operation:

Operation	`parse_result` support
Parse	Supported; page selection and `output.include_images` are not available
Split	Supported
Classify	Not supported
Extract	Supported; `page_ranges` is not available
Ground	Supported

Workspace file uploads

Uploading files into a workspace is a separate endpoint — not POST /v1/uploads.

# Upload into a workspace (persistent storage)
curl -X POST "$NDI_BASE_URL/v1/workspaces/$WS/files" \
  -H "X-API-Key: $NDI_API_KEY" \
  -F "file=@document.pdf" \
  -F 'metadata={"path":"reports/document.pdf","access_labels":[]}'

This returns a Job with kind: "upload_file", not an upload object. The file persists in the workspace after the job completes. See Files for full documentation.

Which upload to use?

Pattern	Endpoint	Storage	Lifecycle
Granular operation	`POST /v1/uploads`	Temporary staging	Expires after TTL
Workspace storage	`POST /v1/workspaces/{id}/files`	Persistent	Lives until deleted

Getting started

SDKs and agents

Concepts

URL source (`"type": "url"`)

Upload source (`"type": "upload"`)

Workspace file source (`"type": "workspace_file"`)

Parse result source (`"type": "parse_result"`)

Workspace file uploads

Which upload to use?

​URL source ("type": "url")

​Upload source ("type": "upload")

​Workspace file source ("type": "workspace_file")

​Parse result source ("type": "parse_result")

​Workspace file uploads

​Which upload to use?

URL source (`"type": "url"`)

Upload source (`"type": "upload"`)

Workspace file source (`"type": "workspace_file"`)

Parse result source (`"type": "parse_result"`)

Workspace file uploads

Which upload to use?