Anthropic API (unofficial showcase)
POST/v1/files

Upload a file

Uploads a file for use through the Files API. Send the file as multipart form data and optionally set expires_in_seconds to control how long its bytes remain available. The response includes file metadata and the expiration time when one is set.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

2 parameters · 2 body fields
anthropic-versionstringoptional
The version of the Claude API to use.
anthropic-workspace-idstringoptional
Workspace ID to select when the credential can act on multiple Workspaces. A credential tied to one Workspace can omit it; if supplied, it must match that Workspace.

Multipart form data containing the file to upload and optional expiration settings.

filestringrequired
The file to upload. Only the final path component of the part's `filename` is kept; an absent or empty `filename` is replaced with `unnamed` plus the extension for the file's stored `mime_type`, when known.
expires_in_secondsintegeroptional
Seconds from upload until the file expires and its bytes become permanently unavailable. Must be between 3600 (one hour) and 7776000 (ninety days).

17 status codes
200Returns the created file metadata, including its ID, filename, MIME type, size, creation time, downloadability, and expiration time when applicable.
created_atstringrequired
RFC 3339 datetime string representing when the file was created.
downloadablebooleanoptional
Whether the file can be downloaded.
Default:false
expires_atstringoptional
RFC 3339 datetime string representing when the file will expire and become unavailable for download. Null if the file does not expire. For files uploaded with `expires_in_seconds`, this is the upload time plus that value.
Default:null
filenamestringrequired
Original filename of the uploaded file.
idstringrequired
Unique object identifier. The format and length of IDs may change over time.
mime_typestringrequired
MIME type of the file.
size_bytesintegerrequired
Size of the file in bytes.
typestringrequired
Object type. For files, this is always `"file"`.
400Returned when the request contains an invalid argument, such as an invalid expiration value or malformed upload.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
401Returned when the request does not have valid authentication credentials.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
403Returned when the caller does not have permission to perform the operation.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
404Returned when a requested entity is not found.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
408Returned when the operation's deadline expires before completion.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
409Returned when a concurrency issue aborts the operation.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
412Returned when the operation is rejected because the system is not in the required state.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
413Returned when the operation is attempted beyond a valid range.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
429Returned when a resource is exhausted, such as when rate limits are reached.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
431Returned when request metadata is too large.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
499Returned when the client cancels the operation.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
500Returned when an internal server error occurs.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
501Returned when the operation is not implemented or supported.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
503Returned when the service is unavailable.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
504Returned when an upstream service does not respond in time.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error
529Returned when the service is temporarily overloaded.
errorobjectrequired
request_idstringrequired
Default:null
typestringrequired
Default:error

Error handling

A 400 is returned for an invalid argument; a 401 for invalid authentication in the x-api-key header; a 403 when the caller lacks permission; a 404 when a requested entity is not found; a 408 when the deadline expires; and a 409 when a concurrency issue aborts the operation. A 412 is returned when a precondition is not met; a 413 when the operation exceeds a valid range; a 429 when a resource is exhausted; a 431 when request metadata is too large; a 499 when the client cancels the operation; a 500 for an internal error; a 501 when the operation is unsupported; a 503 when the service is unavailable; a 504 when an upstream service times out; and a 529 when the service is overloaded. The file form field is required, and expires_in_seconds must be between 3600 and 7776000 seconds.