Drive files
Use the owning End User’s User API Key under /api/v1/user/drive. An Organization backend can operate on an explicit target End User under /api/v1/org/users/{userId}/drive; it remains the Organization actor and must stay within that Organization.
Upload and verify
Section titled “Upload and verify”- Read
GET /api/v1/user/drive/upload-capabilitiesfor effective limits. - Create
POST /api/v1/user/drive/uploadswith a stableIdempotency-Key,originalName,byteSize, the whole file’s lowercasesha256, andcontentType(null when unspecified). - Follow the returned transport. For an active inline upload, pass
upload.uploadUrlto the terminal and PUT the bytes to its relativeurlwith every returnedheadersentry, without an API Key. Success returns the ready File, including for empty files. The existing Key-authorized inline upload usesPUT /api/v1/user/drive/uploads/{uploadId}/contentwith the exact length andContent-Digest. Multipart upload obtains each part’s restricted URL from/uploads/{uploadId}/parts/{partNumber}/presign; retain its digest and ETag and use returned headers. - Confirm multipart with
POST /api/v1/user/drive/uploads/{uploadId}/complete: submit the complete ascending part list. Inline PUT already returns ready; confirmation with{}is still supported. Readiness requires whole-file size and digest verification.
Read /uploads/{uploadId} after uncertain transport or confirmation. Replaying the original intent preserves the File and fixed expiry. Failed or expired uploads require a new intent; an integrity failure is terminal. Cancel a pending upload with DELETE /uploads/{uploadId}.
An Organization backend uses this same inline and multipart workflow under /api/v1/org/users/{userId}/drive, with its Organization Key on each authenticated management request. Multipart creation returns partSize and totalParts; it issues no core upload ticket. Each part grant and completion rechecks the current exact Key and active ordinary owner. After rotation or revocation, a valid Key can recover the same owned upload and fixed expiry. Previously returned provider part URLs keep their provider-controlled lifetime; changing the Organization Key does not revoke them. A core completion already admitted may finish. Disabled owners retain File reads, upload status and abort cleanup, while creation, part grants and completion require an active owner. Ordinary ready Files are listed and read at /api/v1/org/users/{userId}/files, including /{fileId}/content, and remain selectable as Turn inputs.
Organization-issued upload and download tickets bind the exact issuing credential. Rotation or revocation refuses new redemptions; an already admitted transfer may finish within its original bounds. Renew an active inline ticket by replaying its original creation under a valid Key, preserving the File and fixed expiry. Retained User-Key tickets keep their existing lifetime.
Upload from a browser
Section titled “Upload from a browser”For inline files, keep the Organization or User API Key on your backend and give the page only upload.uploadUrl. Use fetch(new URL(upload.uploadUrl.url, API_ORIGIN), { method: 'PUT', headers: upload.uploadUrl.headers, body: file, credentials: 'omit' }); the browser supplies Content-Length. The URL is a bearer credential: protect it from logs and sharing. It expires after 60 seconds at admission, with an independent 120-second request deadline. On 404 upload_ticket_invalid, the backend replays the same create body and Idempotency-Key to renew an active upload. Status reads never issue URLs; completed replays and non-production deployments without a ticket key omit them. 409 idempotency_in_progress requires status reconciliation and retry; failed, cancelled or expired uploads need a new key and File. 503 upload_temporarily_unavailable can indicate admission pressure or a request deadline; query status because an already-started write may still finish.
A page on any origin can also call these upload routes directly with the User API Key in Authorization. The page then holds a key that authorizes all of that End User’s routes, so give it only to that End User’s own client. Responses admit every origin but never credentials, so send no cookies. Set Content-Type: application/octet-stream on the inline PUT; a File or Blob body otherwise sends its own media type and the upload is rejected. Multipart parts go straight to Drive9 object storage. The operator of that Drive9 storage must configure its CORS policy to admit the page’s origin and every header the presign response returns, and to expose ETag.
Browse and read
Section titled “Browse and read”GET /api/v1/user/drive/entries lists immediate children of a directory or reads an entry by path or fileId. Ready attachments and general files share opaque file IDs. Pass the returned cursor with its original scope and filters.
curl --fail-with-body --get "$BASE_URL/api/v1/user/drive/entries" \ -H "Authorization: Bearer $USER_API_KEY" --data-urlencode 'path=/'
curl --fail-with-body --get "$BASE_URL/api/v1/user/drive/files/content" \ -H "Authorization: Bearer $USER_API_KEY" --data-urlencode "fileId=$FILE_ID"Content reads return complete file bytes. Directories and hidden system assets are outside this file interface. Select a ready file for a message through the Session command flow; upload creation alone does not make its content ready.
Session files
Section titled “Session files”When an MCP tool returns an image, audio or other binary content, or the model reads a binary MCP resource, the platform stores each item as a ready File of the Session’s End User and gives the model a reference to it; a model with image input also sees the image. Read it like any File at /api/v1/org/users/{userId}/files/{fileId} and /content, or select it as a Turn input. Its source is {"kind": "session", "sessionId": ..., "operationId": ...}, while an upload reads {"kind": "user_upload"}. The call’s Operation lists the File IDs under output.details.mcp.files, never the bytes.
A result over the binary limits (4 MiB per item, 8 MiB and 8 items per result) fails the call before any File is stored, and a failed call leaves no partial set of Files.
Edit general files
Section titled “Edit general files”Create directories with POST /api/v1/user/drive/directories. Create or replace a general file with PUT /api/v1/user/drive/files/content; it requires a stable Idempotency-Key and exact Content-Length. Replacing a file also requires its current quoted If-Match ETag. A complete confirmed write returns its file facts and ETag.
DELETE /api/v1/user/drive/entries deletes a file or empty directory, without recursion. Unknown write or delete outcomes do not authorize automatic resubmission; reconcile before deciding whether to issue another command. Full bodies and headers are in the API reference.
Download tickets
Section titled “Download tickets”Create a short-lived ticket with POST /api/v1/user/drive/download-tickets for an authorized fileId. Redeem it at GET /api/v1/drive-downloads/{ticket} for complete content or a restricted storage redirect.
The ticket is a bearer credential: anyone holding it can redeem it. Protect it from logs and public sharing. After expiry, obtain a fresh ticket through an authorized read flow.
A backend can use the same general Drive operations at /api/v1/org/users/{userId}/drive with its Organization Key, including for a disabled ordinary owner. Organization-issued tickets bind the exact credential: rotation or revocation rejects new redemptions, while an admitted transfer may finish. Another Key’s tickets remain valid; use fresh authority to issue a new ticket. A returned provider URL keeps its own expiry and is not revoked by the core check.
Drive tickets now use the opaque v4 format. Old v3.drive links lack issuer attribution and are refused; request a fresh ticket after upgrade. New User-issued Drive tickets retain their Key-independent lifetime. Other download kinds and User upload tickets keep their existing contracts.