---
title: "Start a chunked upload"
method: POST
path: "/v1/documents/upload-sessions"
tags: ["Documents"]
---

# Start a chunked upload

`POST /v1/documents/upload-sessions`

## Request

- Base URL: `https://console.nace.ai`
- URL: `https://console.nace.ai/v1/documents/upload-sessions`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/nace/apis/drex-api/docs/v1/documents/upload-sessions/post.ts> (a function with typed inputs; its response is checked against the schema)

A resumable upload of a large file into the workspace `workspace_id` names, or, without one, for your document jobs, in parts of `chunk_size` bytes. Takes an `Idempotency-Key` header.

Send each call below straight to the document service, with `X-Upload-Token: <session_token>`:

1. `PUT {upload_session_url}/parts/{n}` for each part, numbered from 0.
2. `POST {upload_session_url}/complete?wait_seconds=60` with an `Idempotency-Key`. It assembles the file in the background and answers `202` while it runs.
3. Repeat step 2 with the same key until it answers `200` with `result.file` (`workspace_id`, `file_id`).

`GET {upload_session_url}` shows progress, and `DELETE {upload_session_url}` aborts.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `workspace_id` string: Optional. A workspace from the Workspaces API that this key may use; the file goes into that workspace. Leave it out to upload a file for your document jobs (parse, extract, classify, split, ground).
  - `path` string, required
  - `total_size_bytes` integer, required
  - `ttl_seconds` integer

## Response `201`

The session.

- object
  - `workspace_id` string, uuid: The workspace the file goes into.
  - `session_id` string
  - `session_token` string
  - `chunk_size` integer
  - `total_parts` integer
  - `expires_at` string, date-time
  - `upload_session_url` string, uri

## Other responses

- `401`: Missing or invalid API key (`authentication_error`, code `invalid_api_key`).
- `404`: `workspace_id` is not a workspace this key may use (`not_found_error`, code `workspace_not_found`).
- `422`: The body is not a JSON object or has an unknown field, or the document service refused it (`invalid_request_error`).
- `429`: Over the account's requests per minute for document routes, or the document service is throttling this account (`rate_limit_error`).
- `500`: Something failed on Drex's side (`internal_error`).
- `502`: The document service refused Drex's own request (`upstream_error`, code `ndi_refused_drex`). Retry later.
- `503`: The document service is unavailable (`service_unavailable`).
- `504`: The document service timed out (`upstream_error`).
- `529`: The public API is paused (code `service_disabled`) (`overloaded`).

---

[API](https://skmtc.dev/nace/apis/drex-api.md) - [All operations](https://skmtc.dev/nace/apis/drex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nace/apis/drex-api/revisions/a0e62d925a61?raw)