Skip to main content
POST
Create an Upload Token for Browser Uploads
Creates an upload token that a browser or another untrusted client can use to upload, without your API key. The token fixes every constraint you send: a path for one file or a prefix for any file in a folder, the largest size, the allowed extensions and the visibility. It works only on the upload routes, and it stops working when the API key that created it is revoked. The token is shown once. Scope: blob:write.
string
Exact path the token can upload to. Use this or prefix, not both.
string
Folder the token can upload into. The random suffix is forced. Use this or path, not both.
string
public or private. Fixed by the token.
number
Largest file the token accepts, in bytes.
string[]
1–20 extensions, lowercase, without the dot.
string
Fixed cache_control for the uploaded objects.
string
Fixed inline or attachment for the uploaded objects.
string
ISO 8601 timestamp for deletion of the uploaded objects.
object
Fixed metadata for the uploaded objects. Enterprise-12 or higher.
boolean
Let uploads with this token replace an existing file. Default false: without it, the token never overwrites a file that already exists.
number
Seconds the token stays valid, 60–3600. Default 900.
number
How many uploads the token allows, 1–100. Default 1.
string
The workspace ID, when the blob belongs to a workspace. The call acts on the blob of the workspace owner and needs the blob:read workspace permission (blob:manage on routes that change data). Leave it out to act on your own blob.

Example request

Response

object
The token. Shown once.

Error Responses

string
The error code indicating the reason for failure. Possible values:
  • AUTH_TOKEN_MISSING (401): No Authorization header was sent.
  • API_KEY_INVALID (401): The API key doesn’t exist, was revoked, or its secret doesn’t match.
  • API_KEY_SCOPE_DENIED (403): The key lacks the scope this route needs (blob:read or blob:write); details.required names it.
  • WORKSPACE_PERMISSION_DENIED (403): Only with workspace_id: you’re not a member, or your role lacks the blob permission.
  • WORKSPACE_NOT_FOUND (404): Only with workspace_id: no workspace with that ID, or you’re not a member.
  • BLOB_NAMESPACE_SUSPENDED (403): The account’s blob storage is suspended, or its plan expired. Uploads and other writes are refused from the start of the 72-hour grace period.
  • VALIDATION_ERROR (400): A parameter or body field failed validation. details.path names the field.
  • PLAN_RESTRICTED_FEATURE (403): metadata was sent on a plan below Enterprise-12.
  • RATE_LIMIT_EXCEEDED (429): More than 60 tokens created in a minute; details.retry_after says how many seconds to wait.