NAnace
files

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.

post/v1/workspaces/{workspace_id}/upload-sessions

Request

Path parameters

workspace_idstring uuid required

Workspace identifier.

Headers

Idempotency-Keystring nullable

Use the same key to recover an earlier request. A replay returned as a Job carries Idempotent-Replayed: true and replayed: true without a new charge; Job credits keeps the original cost. Re-serving a settled inline tool answer reports zero credits for that call and also carries Idempotent-Replayed: true; a fresh re-execution after a transient failure carries no header. The key is kept with the job for replay and never cleared, so it must not contain personal data.

Request body

graph_inclusion'auto' | 'include' | 'exclude'

Whether this file joins the knowledge-graph corpus. 'auto' follows the workspace's KG exclusion rules; 'include'/'exclude' override them for this file.

labelsobject

Caller-supplied metadata, stored verbatim.

on_conflict'reject' | 'new_version'

'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.

pathstring required

Destination path inside the workspace. Relative, must not start with '/', and must not use the platform-reserved '.workspace' subtree.

source_modified_atstring date-time nullable

Filesystem modification time reported by the uploading client. Informational only: callers control this value, so it is not audit evidence.

total_size_bytesinteger required

Exact total size of the file, across every part.

ttl_secondsinteger

How long the session accepts parts before it expires unfinished.

Response

Successful Response

chunk_sizeinteger required

Upload every part at exactly this size, except a shorter final part.

expires_atstring date-time required

When the session stops accepting parts.

session_idstring uuid required
session_tokenstring required

Send in the X-Upload-Token header of every subsequent request.

total_partsinteger required

ceil(total_size_bytes / chunk_size) — the parts complete() expects.

Changes

No recorded changes to this operation across all 2 revisions of this API.