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 reachable https:// URL. Use a presigned HTTPS URL for private object storage:

Python
TypeScript
cURL

from ndi_sdk import UrlSource

source = UrlSource(
    url="https://example.com/annual-report.pdf",
    file_name="annual-report.pdf",
)

import { UrlSource } from "ndi-sdk";

const source = UrlSource({
  url: "https://example.com/annual-report.pdf",
  file_name: "annual-report.pdf",
});

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

Fields:

url — https:// only. NDI verifies the resolved hostname.
file_name — Chooses the processing lane and appears in result metadata.

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

Stage bytes with POST /v1/uploads, then pass the handle:

Python
TypeScript
cURL

from ndi_sdk import NdiClient

with NdiClient() as client:
    upload = client.documents.create_upload("document.pdf")
    job = client.documents.parse(upload)

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("document.pdf");
const job = await client.documents.parse(upload);

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

curl -X POST "$NDI_BASE_URL/v1/parse?wait_seconds=60" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"source\": {\"type\": \"upload\", \"upload_id\": \"$UPLOAD_ID\"}}"

Lifecycle:

Default TTL is 24 hours. Set another with the ttl_seconds multipart form field, next to file. The cap is 7 days; a longer value is rejected with invalid_request (422), not clamped. expires_at is the unused-upload ceiling.
Use each handle for a single job. Bytes are deleted after that job finishes. expires_at only bounds an upload nothing ever consumed.
Upload IDs are scoped to your API key.

The SDK accepts the create_upload / createUpload response directly as a parse/extract/split/classify/ground source.

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.

Python
TypeScript
cURL

from ndi_sdk import WorkspaceFileSource

source = WorkspaceFileSource(
    workspace_id="550e8400-e29b-41d4-a716-446655440001",
    file_id="550e8400-e29b-41d4-a716-446655440004",
)

import type { WorkspaceFileSource } from "ndi-sdk";

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

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

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

Reuse a successful Parse job without paying for the parse twice:

Python
TypeScript
cURL

from ndi_sdk import ParseResultSource

source = ParseResultSource(
    job_id="550e8400-e29b-41d4-a716-446655440010"
)

import type { ParseResultSource } from "ndi-sdk";

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

{
  "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.

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

Workspace file uploads

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

Python
TypeScript
cURL

from ndi_sdk import NdiClient

with NdiClient() as client:
    job = client.files.upload(
        workspace_id,
        "document.pdf",
        path="reports/document.pdf",
    )

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const workspaceId = "550e8400-e29b-41d4-a716-446655440001";
const job = await client.files.upload(workspaceId, "document.pdf", {
  path: "reports/document.pdf",
});

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"}'

This returns a Job with kind: "upload_file". The file persists until you delete it, the workspace’s source_ttl_days elapses, or the account is closed; see Data retention. Large files use upload sessions. Browser clients use upload grants. Workspace .txt sources may be up to 1 GiB. The SDK automatically uses a resumable session for these files. After upload, workspace ingestion and Parse preserve the complete UTF-8 text as a streamed content artifact; inline Markdown is a representative preview and ParseResult.document.content_url streams the complete text. Split, Extract, and Ground retain their 256 MiB operation limit and return file_size_too_large above it.

Which upload to use?

Pattern	Endpoint	Storage	Lifecycle
Granular operation	`POST /v1/uploads`	Temporary staging	Single-use; 24h default TTL
Workspace storage	`POST /v1/workspaces/{id}/files`	Persistent	Until you delete it, `source_ttl_days` elapses, or the account is closed
Resumable workspace upload	`POST .../upload-sessions`	Persistent	SDK auto-uses this at ≥32 MiB
Browser upload	`POST .../upload-grants` then redeem	Persistent	Grant is short-lived and single-use

Getting started

Guides

Agents

Concepts

Troubleshooting

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?