Create File
Starts an upload: creates a pending file at path and returns an upload to PUT its bytes to. The bytes go
straight to storage, not through the API. Then call Complete File to make the file ready.
Retry-safe: sending the identical request again (same path, size, sha256, content_type and
expires_at) returns the existing file with 200 instead of 201: a pending one with a fresh upload, or
a ready one without. If its bytes were uploaded but the upload was never completed, it is completed then. A
different request at a path whose file is still pending and has no bytes replaces that file; at any other
taken path it returns 409.
The file counts against the organization’s Drive quota from creation, pending or not: 1 GiB and 10,000 files
by default. A file that doesn’t fit returns 403 with code limit_exceeded. Deleting a file frees its
space within seconds. Expired files count until a create needs their space: a create that doesn’t fit first
gives back what expired files hold, a batch at a time, so retry a refusal while many expired files remain.
Requires the file_create permission, which an unverified organization’s keys don’t have at any scope until
it completes agent verification. A key without file_read can still create files, but gets the plain 409 at
any taken path, even for an identical request at a file it didn’t create.
Agent Drive is in AgentMail Labs, available in US production (api.agentmail.to) but not yet in EU
production (api.agentmail.eu). Organizations that have not joined Labs receive a 403.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
Request
Where the file lives in its inbox’s drive, such as reports/q3.pdf. Unique within the inbox. Segments are
separated by /, with no leading or trailing /, no empty, . or .. segment, no \ and no control or
invisible characters. At most 1,024 bytes, and at most 255 bytes per segment. Stored in Unicode NFC, so two
spellings of one name are one path. Case is kept.
The base64 encoding of the file’s 32-byte SHA-256 digest, as S3’s x-amz-checksum-sha256 takes it (44
characters, ending in =). S3 refuses an upload whose bytes don’t match.
Size of the file in bytes. At most 104,857,600 (100 MiB).
The file’s MIME type, such as application/pdf. Defaults to application/octet-stream.
When the file expires, in the future. Rounded up to a whole second and returned in UTC. On a retry, send
the expires_at the first response returned.
Response
The file’s MIME type, such as application/pdf. Defaults to application/octet-stream.
Where the file lives in its inbox’s drive, such as reports/q3.pdf. Unique within the inbox. Segments are
separated by /, with no leading or trailing /, no empty, . or .. segment, no \ and no control or
invisible characters. At most 1,024 bytes, and at most 255 bytes per segment. Stored in Unicode NFC, so two
spellings of one name are one path. Case is kept.
The base64 encoding of the file’s 32-byte SHA-256 digest, as S3’s x-amz-checksum-sha256 takes it (44
characters, ending in =). S3 refuses an upload whose bytes don’t match.
Size of the file in bytes. At most 104,857,600 (100 MiB).
pending until its bytes are uploaded and the upload is completed, then ready. Only a ready file has a
download URL. A pending file is deleted if it isn’t completed within a day.
When download_url stops working. Never after the file’s own expiry.
A signed URL that downloads the file’s bytes, named by name. No API key is needed to use it, so treat it
as a secret. It works until download_expires_at, at most an hour, even after the file is deleted. Get the
file again for a fresh one.
When the file expires. After it, the file is gone from get and list and its path is free; its bytes are deleted soon after. Absent for a file that never expires.
Where to upload a pending file’s bytes: one HTTP PUT to url with exactly headers and the file’s bytes as
the body. Every header is signed, so S3 refuses the upload if any is missing or different, and refuses bytes
whose size or SHA-256 doesn’t match the file. Then call Complete File.