Skip to main content
POST
Start a Direct Blob Upload
Starts a direct upload: the bytes go from your client straight to storage, not through the API. Files up to the plan’s single-part limit come back in single mode with one url. Larger files come back in multipart mode with a part size and count. Then send the bytes and call Complete a direct upload. The reserved storage counts toward the quota until the upload completes, aborts or expires. 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, with the same rules as Upload in one request.
number
required
Exact size of the file in bytes, from 0 up to 10 GB. The stored bytes must match it.
string
public or private. Default private.
boolean
Replace an object already at path. Default false.
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 upload 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 a random suffix 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).
string
inline or attachment. HTML, SVG, XML, XHTML and HTM are always attachment.
string
Name suggested on download.
string
ISO 8601 timestamp for deletion, at least the plan’s minimum from now.
string
Hex SHA-256 of the whole file. Checked when the upload completes. Only valid for a direct upload sent in a single part; a multipart upload refuses it with VALIDATION_ERROR.
object
Up to 5 keys, each [a-z0-9-]{1,64}, 512 bytes in total. Enterprise-12 or higher.
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 upload, with the URLs to send the bytes to.

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_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.
  • BLOB_UPLOAD_TOKEN_CONSTRAINT (403): Only with an upload token: the path, folder or another option the token fixes doesn’t match the request.
  • PLAN_RESTRICTED_FEATURE (403): metadata (below Enterprise-12) or cache_control: no-cache (below Enterprise-26) isn’t included in the plan.
  • BLOB_UPLOAD_LIMIT (409): The account already has as many uploads in progress as its plan allows (max_open_uploads).
  • BLOB_OBJECT_ALREADY_EXISTS (409): path is taken and overwrite is not true.
  • BLOB_FILE_TOO_LARGE (413): size is above 10 GB, the folder rule’s max_size, or the token’s max_size.
  • STORAGE_QUOTA_EXCEEDED (403): The reserved size plus what’s already used would exceed the plan’s blob quota.
  • BLOCKED_FILE_TYPE (422): The extension is blocked or not allowed by the folder rule or token.
  • 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.