Direct upload — send a whole file in one request

Uploads a file into an existing upload session in a single POST, with the file as the raw request body.

This is the recommended method for AI agents, scripts and any caller sending a single file under the size limit. It needs no protocol support: one request, plain headers, no base64 metadata and no byte offsets.

The alternative is the resumable method (/api/tus, TUS protocol), which is what the website and mobile apps use. Choose resumable when the file exceeds the size limit below, when the connection is unreliable (mobile, Tor/I2P), or when you need a progress bar.

Order of operations: create a session (POST /api/analyse/session, /api/convert/session, or /api/session) → upload here → start the job. Check ready_for_job_start in the response rather than polling the session-files endpoint. A steganography hide needs two uploads — the payload (X-Upload-Step: 1) and the cover media (X-Upload-Step: 2) — so it only reports ready once both have arrived.

Content-Type must be set. Without it curl --data-binary sends application/x-www-form-urlencoded and the body is parsed as form data rather than a file.

Content-Length is required; chunked transfer-encoding is refused. Without a declared length a body truncated in transit cannot be distinguished from a complete one, and analysing a truncated file would return results describing a file you never sent.

Retries: send the same X-Client-Upload-Id to make a retry safe. If the original succeeded but its response was lost, the retry returns that original result (HTTP 200, deduplicated: true) instead of uploading a second copy. Without the header a retry creates a second file.