Upload Large File
Upload files up to 200 MB. The client uploads the file body directly to Google Cloud Storage with a short-lived signed PUT URL, then registers the upload with the API.
How it works
The file body is uploaded directly from the client to Google Cloud Storage using a short-lived V4-signed PUT URL — the bytes never pass through the API server, which lets the endpoint accept files up to 200 MB. A single upload is three calls from the client:POST /v2/files/sign— the API mints a signed GCS PUT URL valid for ~15 minutes and returns the headers the client must echo on the PUT.PUTthe file body directly to the returneduploadUrl. The PUT carries exactly the headers fromrequiredHeaders— no more, no less — they are bound into the V4 signature, so a missing, extra, or different header makes GCS reject the PUT with403.POST /v2/files/register— the API verifies the uploaded object’s size against what you declared at/sign, moves it server-side from the temporary staging area to its final location, deduplicates by content hash, and returns the standardFileDTO(same shape as POST /files).
Step 2 — direct PUT to Google Cloud Storage
Send exactly the headers returned inrequiredHeaders (currently Content-Type and x-goog-if-generation-match):
200 on success. The x-goog-if-generation-match: 0 header makes the PUT create-only — replays return 412 Precondition Failed.
Step 3 — register the upload
After the PUT succeeds, finalize the upload. The declared size does not need to be sent again — the server remembers thesize you declared at /sign (for ~16 minutes) and compares it against the actual uploaded object:
201 with the standard FileDTO. If a file with identical content already exists in the workspace, the API returns 200 with the existing file’s FileDTO instead of creating a duplicate. The optional process field works exactly like on POST /files.
Supported files
Same as POST /files — Text, Word, Spreadsheet, PDF, Excel, PowerPoint, Image, Video, Audio, and 30+ code extensions.Limits
- Maximum file size per upload: 200 MB
- One file per flow (run the three steps again for additional files)
- Storage limit: 30 files
Errors
| Status | Meaning |
|---|---|
400 | /register validation failed (missing field or malformed object_path) |
401 | Missing or invalid Bearer token |
403 | Caller lacks API permission for the target workspace — or, on the GCS PUT, the headers do not match requiredHeaders |
404 | Upload session expired (~15-minute window) or unknown, or the object was never uploaded — start again at /sign |
412 | On the GCS PUT: the object already exists (the signed URL is create-only) |
415 | Unsupported content_type at /register |
422 | /sign validation failed (missing field or size > 200 MB) — or the uploaded object is larger than the size declared at /sign (the object is deleted) |
429 | Throttled |
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
ID of the workspace. If not provided, the user's selected workspace will be used.
Body
Original filename including extension (e.g. report.pdf). Used to derive the stored extension.
MIME type of the file. Bound into the signed URL - the client MUST PUT with exactly this Content-Type header.
Declared file size in bytes. The server remembers this value and /register rejects the upload if the actual uploaded object is larger than declared. Hard maximum: 200 MB (209715200 bytes).
Response
Signed PUT URL minted.
Pre-signed Google Cloud Storage PUT URL. Valid for ~15 minutes.
GCS object path the file will land at. Pass this back to POST /v2/files/register.
Headers the client MUST send on the PUT - bound into the V4 signature. Contains exactly Content-Type (the value you declared) and x-goog-if-generation-match: 0 (create-only). Send these headers verbatim and do not add others.
Short-lived signed download URL (~3 hours) for the uploaded object. For a durable reference, use the url field of the FileDTO returned by POST /v2/files/register.