---
title: "create_upload"
method: POST
path: "/v1/uploads"
tags: ["document-operations"]
---

# create_upload

`POST /v1/uploads`

## Request

- Base URL: `https://ndi-api.nace.ai`
- URL: `https://ndi-api.nace.ai/v1/uploads`
- Auth: API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/nace/apis/ndi-platform-api/docs/v1/uploads/post.ts> (a function with typed inputs; its response is checked against the schema)

Stage bytes for document operations and return a handle.

Cost class: **fast** (upload I/O only; no processing units charged here).

The returned ``upload_id`` is passed as ``{"type": "upload", "upload_id":
"<id>"}`` in any subsequent document-operation request.  Uploads are
retained until explicit deletion of the upload, consuming jobs or tenant.
Zero retention refuses standalone uploads with ``422 invalid_request``;
use a workspace bound to your own S3 or Azure storage.

Uploads are workspace-free: this is the entry point for callers that want
to use granular operations without onboarding to the full ingestion model.

## Request body `multipart/form-data`

- BodyCreateUploadV1UploadsPost
  - `file` string, binary, required: The document to stage for a granular operation.

## Response `200`

Successful Response

- NdiServiceAppPlatformApiDocumentOperationsSchemasUploadResponse: Returned by ``POST /v1/uploads`` on success. ``upload_id`` is the handle passed to :class:`~ndi_service.app.platform_api.contracts.UploadSource`. Ordinary bytes stay until explicit deletion; Zero retention remains separate.
  - `content_hash` string, required: SHA-256 hex digest of the staged bytes. Confirms the upload is the file you sent, not a workspace file id.
  - `expires_at` string, date-time, nullable, required: Zero retention cleanup deadline; null for ordinary uploads kept until explicit deletion.
  - `file_name` string, required: Original filename as received.
  - `size_bytes` integer, required: Byte length of the staged file, after upload completes.
  - `upload_id` string, uuid, required: Handle to pass as source.upload_id on a later document operation.

## Other responses

- `504`: Gateway Timeout
- `default`: Typed error envelope used by every 4xx and 5xx. ``error.code`` distinguishes the failure; HTTP status is a consequence of the code.

---

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