> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ndi.nace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload

> Stage a file for parse, extract, split, classify, or ground

`documents.createUpload` stages bytes for a **granular** operation. The handle
is single-use: bytes are deleted when the job that reads them finishes.
Default TTL is 24 hours; the cap is 7 days.

For a durable corpus, use [workspaces](/sdks/typescript/workspaces).

```ts theme={"dark"}
import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");
console.log(upload.upload_id, upload.expires_at);
const job = await client.jobs.wait(
  (await client.documents.parse(upload, { wait_seconds: 30 })).job_id,
);
console.log(job.status);
```

## Method signature

```text theme={"dark"}
createUpload(
  content: FileContent,
  opts?: { file_name?: string | null; ttl_seconds?: number | null },
): Promise<UploadResponse>
```

`FileContent` is a path string, `URL`, `Uint8Array`, `ArrayBuffer`, `Blob`,
`File`, or a `{ name?, read() }` stream.

### Parameters

| Parameter          | Type          | Required | Description                              |
| ------------------ | ------------- | -------- | ---------------------------------------- |
| `content`          | `FileContent` | Yes      | File to stage                            |
| `opts.file_name`   | `string`      | No       | Override the name (needed for raw bytes) |
| `opts.ttl_seconds` | `number`      | No       | Unused-upload ceiling; omit for 24 hours |

### Returns

`UploadResponse`: `upload_id`, `file_name`, `size_bytes`, `content_hash`,
`expires_at`. Pass the object itself as `source` to a document operation.

## Options

```ts theme={"dark"}
import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf", {
  ttl_seconds: 3600,
});
console.log(upload.expires_at);
```

```ts theme={"dark"}
import { NdiClient } from "ndi-sdk";

const data = new Uint8Array([37, 80, 68, 70]);
const client = new NdiClient();
const upload = await client.documents.createUpload(data, {
  file_name: "report.pdf",
});
console.log(upload.file_name);
```

## Errors

* `file_too_large` (413) — over the upload size cap
* `upload_expired` (409) — handle expired or already consumed
* `unsupported_file_type` — usually raised by the next operation, not upload

See [Upload guide](/guides/upload) and [Sources](/concepts/sources-and-uploads).