curl --request POST \
--url https://ndi-api.nace.ai/v1/uploads \
--header 'Content-Type: multipart/form-data' \
--header 'X-API-Key: <api-key>' \
--form file=@example-file{
"content_hash": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"file_name": "<string>",
"size_bytes": 123,
"upload_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}create_upload
Stage bytes for a single granular operation 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
single-use: the bytes are deleted once the job that consumes them
finishes, and are never stored against a workspace. The expires_at
field is the hard ceiling — if the upload was never consumed, storage is
reclaimed at that time.
Uploads are workspace-free: this is the entry point for callers that want to use granular operations without onboarding to the full ingestion model.
curl --request POST \
--url https://ndi-api.nace.ai/v1/uploads \
--header 'Content-Type: multipart/form-data' \
--header 'X-API-Key: <api-key>' \
--form file=@example-file{
"content_hash": "<string>",
"expires_at": "2023-11-07T05:31:56Z",
"file_name": "<string>",
"size_bytes": 123,
"upload_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}{
"error": {
"code": "invalid_request",
"detail": null,
"message": "Request body has extra fields that this operation does not accept.",
"request_id": "req-01j9k2n3p4q5r6s7t8v9",
"retryable": false
}
}Authorizations
Body
The document to stage for a granular operation.
How long this upload is retained (seconds). Capped at MAX_UPLOAD_TTL_SECONDS. Defaults to DEFAULT_UPLOAD_TTL_SECONDS. Bytes are deleted at job completion, so the TTL is only the ceiling for an upload that was never consumed.
1 <= x <= 604800Response
Successful Response
Returned by POST /v1/uploads on success.
upload_id is the handle passed to :class:~ndi_service.app.platform_api.contracts.UploadSource.
Bytes are deleted at job completion, not at expires_at; the TTL is
the ceiling for an upload that was never consumed.
SHA-256 hex digest of the staged bytes. Confirms the upload is the file you sent, not a workspace file id.
When an unused upload is deleted. Consumed uploads are removed when their job finishes.
Original filename as received.
Byte length of the staged file, after upload completes.
Handle to pass as source.upload_id on a later document operation.