Upload a document

POST /v1/uploads stages a file for a granular operation. It does not put the file in a workspace. Use each handle for a single job: bytes are deleted after that job finishes. For a durable corpus, use workspace uploads instead.

Python
TypeScript
curl

from pathlib import Path

from ndi_sdk import NdiClient

with NdiClient() as client:
    upload = client.documents.create_upload(Path("report.pdf"))
    print(upload.upload_id, upload.expires_at)
    job = client.jobs.wait(client.documents.parse(upload, wait_seconds=30).job_id)
    print(job.result.markdown)

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");
const job = await client.jobs.wait(
  (await client.documents.parse(upload, { wait_seconds: 30 })).job_id,
);
console.log(job.result && "markdown" in job.result ? job.result.markdown : job.result);

UPLOAD=$(curl -s -X POST "$NDI_BASE_URL/v1/uploads" \
  -H "X-API-Key: $NDI_API_KEY" \
  -F "file=@report.pdf")
echo "$UPLOAD" | jq .

UPLOAD_ID=$(echo "$UPLOAD" | jq -r '.upload_id')
curl -s -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\"}}"

Inputs

	Python	TypeScript	HTTP
File	`Path`, bytes, or a binary file	path string, `Blob`, or `Uint8Array`	`multipart/form-data` field `file`
Optional TTL	`ttl_seconds=`	`ttl_seconds`	form field `ttl_seconds`

Default TTL is 24 hours; the cap is 7 days.

Result

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

Field	Meaning
`upload_id`	Handle to pass as `source.upload_id` on a later document operation
`file_name`	Original filename as received
`size_bytes`	Byte length of the staged file
`content_hash`	SHA-256 hex digest of the staged bytes. Use it to confirm the upload is the file you sent. It is not a workspace file id
`expires_at`	When an unused upload is deleted. Consumed uploads are removed when their job finishes

The SDK create_upload / createUpload return value is itself a valid source for document operations.

Errors

file_too_large (413) — over the upload size cap
unsupported_file_type (422) — rejected during upload when no granular operation supports the format, when a conclusive byte signature conflicts with the filename extension, or when the selected operation does not support an otherwise stageable format
upload_expired (409) — handle expired

Single-shot and staged upload rejection is synchronous and non-retryable. It creates no handle, and operation-specific rejection creates no job. Resumable uploads report the error on the completion job after parts are joined, without creating a workspace file or ingestion job. NDI inspects a bounded prefix of the uploaded bytes. It does not trust the multipart Content-Type, and it does not read the full file before streaming it. When inspection is inconclusive, formats such as CSV, JSON, and legacy Office files fall back to their filename extension.

Getting started

Guides

Agents

Concepts

Troubleshooting

Inputs

Result

Errors

Next

​Inputs

​Result

​Errors

​Next

Inputs

Result

Errors

Next