Upload

documents.createUpload stages bytes for one parse, extract, split, classify, or ground operation. It returns an UploadResponse that can be passed directly as the operation’s source.

A granular upload is temporary and single-use. To keep a file, upload it to a workspace.

Basic usage

import { NdiClient, isParseResult } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");
// Returns: UploadResponse with upload_id, file_name, size_bytes,
// content_hash, and expires_at
console.log(upload.upload_id, upload.expires_at);

const queued = await client.documents.parse(upload, { wait_seconds: 30 });
// Returns: Promise<Job>; the upload is consumed by this operation
const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
// Returns: succeeded Job with a ParseResult
if (isParseResult(job.result)) {
  console.log(job.result.markdown);
}

Method signature

createUpload(
  content: FileContent,
  opts?: { file_name?: string | null; ttl_seconds?: number | null },
): Promise<UploadResponse>

FileContent is a path string, URL (file: protocol only), Uint8Array, ArrayBuffer, Blob, File, or a { name?, read() } stream object.

Parameters

Parameter	Type	Required	Description
`content`	`FileContent`	Yes	File contents to stage
`opts.file_name`	`string \| null`	No	Filename override. Required when `content` does not carry a name (raw bytes, unnamed Blob)
`opts.ttl_seconds`	`number \| null`	No	How long an unused upload remains available. Omit for 24 hours; maximum 7 days

Returns

Promise<UploadResponse>:

Field	Type	Description
`upload_id`	`string`	Temporary handle accepted as a document-operation source
`file_name`	`string`	Recorded filename
`size_bytes`	`number`	Uploaded byte count
`content_hash`	`string`	SHA-256 digest of the staged bytes
`expires_at`	`string`	ISO 8601 deletion time if no operation consumes the upload

Upload options

From a path string (Node.js)

Use a local path string when the file is on disk:

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("invoice.pdf");
// Returns: Promise<UploadResponse>; file_name is "invoice.pdf"

From a file: URL (Node.js)

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const url = new URL("file:///home/user/docs/invoice.pdf");
const upload = await client.documents.createUpload(url);
// Returns: Promise<UploadResponse>

Only file: protocol URLs are accepted. For remote sources, pass a UrlSource directly to the operation instead of uploading through this method.

From a File object (browser or Node.js 20+)

import { NdiClient } from "ndi-sdk";

// In a browser: from an <input type="file"> element
const input = document.getElementById("file-input") as HTMLInputElement;
const file = input.files![0];

const client = new NdiClient();
const upload = await client.documents.createUpload(file);
// Returns: Promise<UploadResponse>; file_name is preserved from the File object

From raw bytes (Uint8Array or ArrayBuffer)

Raw bytes carry no filename. Supply one so NDI can select the correct processing lane:

import { NdiClient } from "ndi-sdk";

const data = new Uint8Array([37, 80, 68, 70]); // %PDF magic bytes
const client = new NdiClient();
const upload = await client.documents.createUpload(data, {
  file_name: "invoice.pdf",
});
// Returns: Promise<UploadResponse>

Passing Uint8Array or ArrayBuffer without file_name throws a client-side error before any network request.

From a Blob (browser)

import { NdiClient } from "ndi-sdk";

const pdfBytes = new Uint8Array([37, 80, 68, 70]); // %PDF …
const blob = new Blob([pdfBytes], { type: "application/pdf" });
const client = new NdiClient();
const upload = await client.documents.createUpload(blob, {
  file_name: "report.pdf",
});
// Returns: Promise<UploadResponse>

From a readable stream

Any object with a read() method is accepted:

import { NdiClient } from "ndi-sdk";
import { readFile } from "node:fs/promises";

const stream = {
  name: "report.pdf",
  read: () => readFile("report.pdf"),
};
const client = new NdiClient();
const upload = await client.documents.createUpload(stream);
// Returns: Promise<UploadResponse>

Custom unused-upload TTL

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("invoice.pdf", {
  ttl_seconds: 3600,
});
// Returns: Promise<UploadResponse> that expires in one hour if unused

The TTL only bounds an upload that no operation consumes. Once a document operation uses the handle, NDI removes the staged bytes when that job finishes. The handle cannot be reused for another operation.

Use a URL instead

You do not need to call createUpload when NDI can fetch the source directly:

import { NdiClient, UrlSource } from "ndi-sdk";

const client = new NdiClient();
const source: UrlSource = {
  type: "url",
  url: "https://example.com/reports/annual-report.pdf",
  file_name: "annual-report.pdf",
};
const job = await client.documents.parse(source);
// Returns: Promise<Job>

The URL must use HTTPS and be reachable by NDI. For private storage, provide a presigned HTTPS URL. See Sources and uploads.

Async usage

createUpload always returns a Promise. Use await or chain .then():

import { NdiClient, isParseResult } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");
// Returns: Promise<UploadResponse>
console.log(upload.upload_id);

const queued = await client.documents.parse(upload, { wait_seconds: 30 });
const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
// Returns: succeeded Job with a ParseResult
if (isParseResult(job.result)) {
  console.log(job.result.document.page_count);
}

Limits and formats

The upload endpoint enforces the byte cap configured for your API key and rejects formats that no granular document operation supports. Format support then narrows for the operation that consumes the upload; a file accepted by upload can still be rejected by parse, split, classify, extract, or ground.

Format support

Check which document, image, spreadsheet, email, and media formats each operation accepts.

Errors and limits

Review upload size, rate, concurrency, and request limits.

Error handling

import { NdiClient, InvalidRequestError, ConflictError } from "ndi-sdk";

const client = new NdiClient();
try {
  const upload = await client.documents.createUpload("report.pdf");
  const queued = await client.documents.parse(upload);
  // Returns: Promise<Job>, or throws if the upload cannot be staged or consumed
} catch (err) {
  if (err instanceof InvalidRequestError) {
    console.log(err.code, err.message);
  } else if (err instanceof ConflictError) {
    console.log(err.code, err.message);
  } else {
    throw err;
  }
}

Common upload outcomes:

file_too_large (413) — the bytes exceed the upload cap.
zero_byte_file (422) — the staged file is empty.
unsupported_file_type (422) — raised by createUpload when no granular operation supports the format, when the filename conflicts with a conclusive byte signature, or by the consuming operation when that specific operation does not support it.
Client-side Error — a path string that does not exist, or raw bytes supplied without file_name; thrown before any HTTP request.

Consuming operations can return upload_expired (409) for an expired handle or upload_not_found (404) for an unknown, cross-tenant, or already removed handle. These are not raised by createUpload itself. unsupported_file_type is synchronous and non-retryable. A rejection from createUpload creates no upload handle; a rejection from the consuming operation creates no job, so there is nothing to poll with jobs.wait. The service inspects only a bounded byte prefix and treats multipart Content-Type as advisory.

Best practices

Prefer path strings

Use a local path string for Node.js so the filename travels with the bytes automatically.

Create near use

Stage a granular upload immediately before its operation. It is a temporary, single-use handle.

Name raw bytes

Always pass file_name with Uint8Array, ArrayBuffer, or Blob so NDI can infer the format.

Use workspaces for persistence

Put files in a workspace when they must survive one operation or become searchable.

Get started

Core methods

Async and utilities

Basic usage

Method signature

Parameters

Returns

Upload options

From a path string (Node.js)

From a file: URL (Node.js)

From a File object (browser or Node.js 20+)

From raw bytes (Uint8Array or ArrayBuffer)

From a Blob (browser)

From a readable stream

Custom unused-upload TTL

Use a URL instead

Async usage

Limits and formats

Format support

Errors and limits

Error handling

Best practices

Prefer path strings

Create near use

Name raw bytes

Use workspaces for persistence

Next steps

​Basic usage

​Method signature

​Parameters

​Returns

​Upload options

​From a path string (Node.js)

​From a file: URL (Node.js)

​From a File object (browser or Node.js 20+)

​From raw bytes (Uint8Array or ArrayBuffer)

​From a Blob (browser)

​From a readable stream

​Custom unused-upload TTL

​Use a URL instead

​Async usage

​Limits and formats

Format support

Errors and limits

​Error handling

​Best practices

Prefer path strings

Create near use

Name raw bytes

Use workspaces for persistence

​Next steps

Basic usage

Method signature

Parameters

Returns

Upload options

From a path string (Node.js)

From a file: URL (Node.js)

From a File object (browser or Node.js 20+)

From raw bytes (Uint8Array or ArrayBuffer)

From a Blob (browser)

From a readable stream

Custom unused-upload TTL

Use a URL instead

Async usage

Limits and formats

Error handling

Best practices

Next steps