AGagentmail-to
inboxes > files

Complete File

Changed on

Makes a pending file ready once its bytes are uploaded, and returns it, with its download_url if the key has file_read. Calling it on a file that is already ready returns the file.

Returns 409 if the bytes haven't been uploaded yet, or if what was uploaded doesn't match the file's size and sha256. Returns 404 for a file that has expired or was deleted, including a pending file not completed within a day of its creation.

Requires the file_create permission. Only a key with file_read, or the key that created the file, can complete it; any other key gets 404.

post/v0/inboxes/{inbox_id}/files/{file_id}/complete

Request

  • Base URL
    https://api.agentmail.to
  • URL
    https://api.agentmail.to/v0/inboxes/{inbox_id}/files/{file_id}/complete
  • Auth
    HTTP bearer

Path parameters

inbox_idstring required

The ID of the inbox.

file_idstring required

ID of the file. A UUID.

Response

Response with status 200

file_idstring required

ID of the file. A UUID.

inbox_idstring required

The ID of the inbox.

emailstring required

Email address of the inbox.

pathstring required

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.

namestring required

The path's last segment. A download saves under this name.

sizeinteger required

Size of the file in bytes. At most 104,857,600 (100 MiB).

content_typestring required

The file's MIME type, such as application/pdf. Defaults to application/octet-stream.

sha256string required

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.

status'pending' | 'ready' required

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.

created_atstring date-time required

When the file was created.

updated_atstring date-time required

When the file last changed, such as when its upload was completed.

expires_atstring date-time

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.

download_urlstring

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.

download_expires_atstring date-time

When download_url stops working. Never after the file's own expiry.

Changes