API Referencefiles

Upload a file

View as Markdown
Upload a file into a space and return the canonical file resource.

Authentication

AuthorizationBearer

Use Bearer <api-key>.

Headers

BCTRL-Subaccount-IdstringOptional
Optional effective subaccount context for organization API keys. Subaccount API keys are already scoped and cannot use this header to act as another subaccount.

Query parameters

spaceIdstringOptional

Filter by a prefixed space ID, or pass default to use the caller default space.

Request

This endpoint expects a multipart form containing a file.
filefileRequired
File bytes to upload.
metadatastringOptional

Optional JSON object string with caller-owned file metadata.

namestringOptional<=255 characters
Optional display filename.
pathstringOptional<=4096 characters
Optional relative destination path. Must not be absolute or contain . or .. path segments.

Response

Created
contentTypestring
createdAtdatetime
RFC 3339 timestamp with a UTC offset.
downloadUrlstring
idstring
Unique file identifier generated by BCTRL.
namestring1-200 characters

Customer-facing resource name. 1–200 characters.

pathstring
sizeBytesinteger>=0

Non-negative number of bytes.

sourceenum
spaceIdstring
Unique space identifier generated by BCTRL.
expiresAtdatetimeOptional
RFC 3339 timestamp with a UTC offset.
metadataobject or nullOptional
runIdstringOptional
Unique run identifier generated by BCTRL.
runtimeIdstringOptional
Unique runtime identifier generated by BCTRL.
typestringOptional1-64 characters

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error