API v1 preview

The File object

A registered file and its temporary upload instructions.

Fields

id string · required

Unique, server-generated file ID. Treat it as an opaque reference.

Min length: 37 · Max length: 37

upload object · required

Temporary upload instructions. Send all fields unchanged, then append the file as the last form field. Do not send your API key to storage.

upload fields

method string · required

Allowed values: POST

url string (uri) · required

Destination for the file upload. Authorization is carried in the signed form fields.

fields object · required

Complete generated form fields, including the object key, policy, signature, and AWS verification fields. Treat this map as opaque and forward every field unchanged. The actual file is supplied separately.

expires_at string (date-time) · required

UTC expiration of these upload instructions, at most one hour after issuance. Retrying does not extend it. Completed uploads remain usable until the file’s unlinked retention deadline.

Returned by

Create a file

Example

JSON

{
  "upload": {
    "method": "POST",
    "url": "https://example-upload-bucket.s3.amazonaws.com/",
    "fields": {
      "key": "files/2a08c3d391244972a31a0f87d3821fa9/source",
      "policy": "GENERATED_POLICY",
      "x-amz-algorithm": "AWS4-HMAC-SHA256",
      "x-amz-credential": "GENERATED_CREDENTIAL_SCOPE",
      "x-amz-date": "20260921T180000Z",
      "x-amz-signature": "GENERATED_SIGNATURE",
      "x-amz-security-token": "GENERATED_SESSION_TOKEN",
      "success_action_status": "204"
    },
    "expires_at": "2026-09-21T19:00:00Z"
  },
  "id": "file_6c82bd3e319b4bb099310d54a761879e"
}

API v1 preview