Large and resumable uploads

Workspace files.upload is a single multipart POST. The Python and TypeScript SDKs switch to a resumable upload session automatically at 32 MiB. Call the session routes yourself when you need to resume after a drop or stream from a source that is not in memory. The workspace .txt ceiling is 1 GiB. A file at that boundary is uploaded as four 256 MiB parts; it cannot use the 512 MiB single-request route. Other document formats keep their existing format-specific ceilings.

Python
TypeScript
curl

from pathlib import Path

from ndi_sdk import NdiClient

path = Path("ledger.xlsx")
data = path.read_bytes()

with NdiClient() as client:
    workspace = client.workspaces.create(name="large-uploads")
    job = client.jobs.wait(
        client.files.upload_chunked(
            workspace.workspace_id,
            data,
            path="books/ledger.xlsx",
        ).job_id
    )
    print(job.result.file.path, job.result.file.size_bytes)

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const workspace = await client.workspaces.create({ name: "large-uploads" });
const job = await client.jobs.wait(
  (
    await client.files.upload(workspace.workspace_id, "ledger.xlsx", {
      path: "books/ledger.xlsx",
    })
  ).job_id,
);
console.log(job.result);

SIZE=$(wc -c < ledger.xlsx | tr -d ' ')
SESSION=$(curl -s -X POST "$NDI_BASE_URL/v1/workspaces/$WS/upload-sessions" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"path\":\"books/ledger.xlsx\",\"total_size_bytes\":$SIZE}")

SESSION_ID=$(echo "$SESSION" | jq -r '.session_id')
TOKEN=$(echo "$SESSION" | jq -r '.session_token')
CHUNK=$(echo "$SESSION" | jq -r '.chunk_size')

# PUT each part (0-indexed). Resume with GET .../upload-sessions/$SESSION_ID.
PART=0
curl -s -X PUT "$NDI_BASE_URL/v1/workspaces/$WS/upload-sessions/$SESSION_ID/parts/$PART" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "X-Upload-Token: $TOKEN" \
  --data-binary @part0.bin

curl -s -X POST "$NDI_BASE_URL/v1/workspaces/$WS/upload-sessions/$SESSION_ID/complete?wait_seconds=60" \
  -H "X-API-Key: $NDI_API_KEY" \
  -H "X-Upload-Token: $TOKEN"

Session lifecycle

POST .../upload-sessions — returns session_id, session_token, chunk_size, total_parts
PUT .../parts/{part_number} — send each chunk with X-Upload-Token
GET .../upload-sessions/{session_id} — list landed parts after a drop
POST .../complete — concatenates parts and writes the ledger row (a Job)
DELETE .../upload-sessions/{session_id} — abort and reclaim staged parts

The session token is not your API key. Send it on every part and on complete. Default session TTL is a server default; ttl_seconds is optional on create.

When to use which

Size / client	Call
Under 32 MiB from the SDK	`files.upload` (single POST)
32 MiB or larger from the SDK	automatic session under `files.upload`
Resume or stream yourself	`create_upload_session` + parts + complete
Browser without your API key	Upload grants

For .txt, the 1 GiB contract covers workspace storage, ingestion, search/read, and Parse. Split, Extract, and Ground currently reject .txt sources above 256 MiB because those operations still materialize text in memory. Uploading still does not ingest. Call ingest after the complete job succeeds.

Getting started

Guides

Agents

Concepts

Troubleshooting

Session lifecycle

When to use which

​Session lifecycle

​When to use which

Session lifecycle

When to use which