Upload a document - NDI Platform API

POST /v1/uploads stages a file for a granular operation. It does not put the file in a workspace. The handle is single-use: bytes are deleted when the job that reads them 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"
}

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 by the next operation, not always at upload
upload_expired (409) — handle expired or already consumed

Next