Skip to main content
POST
Upload Blob Object in One Request
Uploads one file of up to 100 MB in a single multipart/form-data request and stores it at path. For larger files use Start a direct upload. Responds with 201 and the new object. Scope: blob:write. Accepts an upload token. Upload token: this route also accepts an upload token (Authorization: Bearer vcup_...) instead of an API key.
string
required
Destination path in the account. 1–1024 characters, up to 16 segments of [A-Za-z0-9._ -] (1–255 characters each), no leading or trailing /, no // or .., and an extension is required. Rejected paths return VALIDATION_ERROR; they are never changed silently.
string
public or private. Default private.
boolean
Replace an object already at path. Default false: a taken path returns BLOB_OBJECT_ALREADY_EXISTS.
boolean
When path is taken, save the file as name-1.ext, name-2.ext and so on (the first free name) instead of returning BLOB_OBJECT_ALREADY_EXISTS. The response carries the final path. Default false. Can’t be combined with overwrite, and has no effect with an upload token that fixes the path.
boolean
Insert - plus 10 random base-36 characters before the extension. Default false. Forced to true for an upload token without a fixed path.
string
immutable, max-age=<seconds> or no-cache (Enterprise-26 or higher). Default: no value set.
string
inline or attachment. Default: inline. Files ending in .html, .htm, .svg, .xml or .xhtml are always served as attachment.
string
Name suggested when the file is downloaded. Default: the last segment of path.
string
ISO 8601 timestamp when the object is deleted. Must be at least the plan’s minimum from now (7 days, or 1 hour on Enterprise-26 or higher).
string
JSON object, URL-encoded: up to 5 keys, each [a-z0-9-]{1,64}, 512 bytes in total. Enterprise-12 or higher.
string
Hex SHA-256 of the file. A mismatch returns BLOB_CHECKSUM_MISMATCH and nothing is stored.
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.
file
required
The file, as the only multipart/form-data part. Up to 100 MB; the plan’s limit applies.

Example request

Response

object
The stored object. Responds with 201.

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_UPLOAD_TOKEN_INVALID (401): The upload token doesn’t exist, has expired or was revoked (only with an upload token).
  • BLOB_CHECKSUM_MISMATCH (400): The checksum_sha256 doesn’t match the file. Nothing was stored.
  • VALIDATION_ERROR (400): A query parameter failed validation, for example an invalid path. details.path names it.
  • BLOB_OBJECT_ALREADY_EXISTS (409): path is taken and overwrite is not true.
  • BLOB_FILE_TOO_LARGE (413): The file is above 100 MB, the plan’s limit for this route, or the rule’s or token’s max_size.
  • STORAGE_QUOTA_EXCEEDED (403): Storing the file would exceed the plan’s blob quota.
  • BLOCKED_FILE_TYPE (422): The extension is blocked, not allowed by the folder rule or token, or the file is an executable.
  • 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.
  • PLAN_RESTRICTED_FEATURE (403): metadata (below Enterprise-12) or cache_control: no-cache (below Enterprise-26) isn’t included in the plan.
  • BLOB_UPLOAD_TOKEN_CONSTRAINT (403): Only with an upload token: the path, folder or another option the token fixes doesn’t match the request.
  • BLOB_UPLOAD_TOKEN_EXHAUSTED (401): Only with an upload token: it has used all its uses.
  • RATE_LIMIT_EXCEEDED (429): Below Enterprise-12, uploads are limited to 1 per second. details.retry_after gives the wait.