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.

Args: session: Database session. body: Destination path, declared total size, and conflict policy — the same fields upload_file takes, minus the bytes. upload_auth: The resolved workspace context, plus the upload grant when the caller redeemed one instead of sending an API key. idempotency_key: Replaying with the same key returns the original session rather than opening a second one.

Returns: A :class:CreateUploadSessionResponse with the session token.

Raises: PlatformError: file_too_large when total_size_bytes exceeds the effective byte cap. PlatformError: access_denied when a path-pinned grant is used to create a session at a different path. PlatformError: unauthorized when a single-use grant is replayed.

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

Request

Path parameters

workspace_idstring uuid required

Workspace identifier.

Headers

Idempotency-Keystring nullable

Replaying a request with the same key returns the original job with 200, never a second job. The key is kept with the job for replay and never cleared, so it must not contain personal data.

Request body

pathstring required

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

total_size_bytesinteger required

Exact total size of the file, across every part.

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.

labelsobject

Caller-supplied metadata, stored verbatim.

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.

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.

ttl_secondsinteger

How long the session accepts parts before it expires unfinished.

Response

Successful Response

session_idstring uuid required
session_tokenstring required

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

chunk_sizeinteger required

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

total_partsinteger required

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

expires_atstring date-time required

When the session stops accepting parts.

Changes

No recorded changes to this operation across all 1 revision of this API.