curl --request POST \
--url https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/upload-sessions \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"path": "<string>",
"total_size_bytes": 123
}
'{
"chunk_size": 123,
"expires_at": "2023-11-07T05:31:56Z",
"session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"session_token": "<string>",
"total_parts": 123
}{
"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_session
Open a chunked upload for a large file. Cost class: fast.
Same auth as upload_file — an X-API-Key or a short-lived
X-Upload-Token grant — but redeemed exactly once, here. Every later
request against the session (parts, status, complete, abort) presents
the session_token this returns instead, in the same X-Upload-Token
header.
Upload every part with PUT .../upload-sessions/{session_id}/parts/{n}
at exactly chunk_size bytes (the final part may be shorter), then
call POST .../complete. GET the session at any point to see which
parts have already landed, e.g. after a dropped connection.
curl --request POST \
--url https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/upload-sessions \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"path": "<string>",
"total_size_bytes": 123
}
'{
"chunk_size": 123,
"expires_at": "2023-11-07T05:31:56Z",
"session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"session_token": "<string>",
"total_parts": 123
}{
"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
Headers
Replaying a request with the same key returns the original job with 200, never a second job.
200Path Parameters
Workspace identifier.
Body
Body for POST /workspaces/{workspace_id}/upload-sessions.
Same destination/conflict/labelling contract as UploadFileRequest —
this is the chunked entry point to the exact same ledger write, for a
file large enough (or a link flaky enough) that one unretried multipart
POST is the wrong shape. total_size_bytes is required and checked
byte-for-byte at complete: nothing here is trusted on faith.
Destination path inside the workspace. Relative — must not start with '/'.
1 - 1024^[^/]Exact total size of the file, across every part.
Whether this file joins the knowledge-graph corpus. 'auto' follows the workspace's KG exclusion rules; 'include'/'exclude' override them for this file.
auto, include, exclude Caller-supplied metadata, stored verbatim.
Show child attributes
Show child attributes
'reject' raises path_conflict at complete-time when a file already exists at this path. 'new_version' increments the version and stamps replaced_at on the previous one.
reject, new_version How long the session accepts parts before it expires unfinished.
1 <= x <= 5400Response
Successful Response
A newly created upload session, ready to accept parts.
session_token is sent as X-Upload-Token on every subsequent
request against this session (parts, status, complete, abort) — the
upload grant or API key used to create the session is not sent again.
Upload every part at exactly this size, except a shorter final part.
When the session stops accepting parts.
Send in the X-Upload-Token header of every subsequent request.
ceil(total_size_bytes / chunk_size) — the parts complete() expects.