Upload a file

POST

/file

• Local Faber instance

Stores the file under the SHA-256 of its content. Uploading the same bytes again returns the same file_id with already_exists: true. Reference stored files from a task with { "file_id": "..." }.

Authorizations

• apiKey

Request Body ^required

object

file

required

File content. The part’s filename and content type are stored as metadata.

string format: binary

Responses

200

Stored

object

file_id

required

Lowercase hex SHA-256 of the file content

string

/^[0-9a-f]{64}$/

size

required

integer format: int64

already_exists

required

boolean

400

Malformed request body or parameters (invalid_request)

object

error

required

Human-readable message

string

code

required

Stable machine-readable error code. Clients should treat unknown codes as internal_error.

string

Allowed values: invalid_request unauthorized not_found file_not_found payload_too_large limits_exceeded profile_not_allowed capacity_exhausted rate_limited shutting_down cancelled deadline_exceeded sandbox_setup_failed cache_disabled internal_error

Example

{
  "error": "Failed to deserialize the JSON body into the target type: missing field `cmd`",
  "code": "invalid_request"
}

401

Missing or wrong API key (unauthorized)

object

error

required

Human-readable message

string

code

required

Stable machine-readable error code. Clients should treat unknown codes as internal_error.

string

Allowed values: invalid_request unauthorized not_found file_not_found payload_too_large limits_exceeded profile_not_allowed capacity_exhausted rate_limited shutting_down cancelled deadline_exceeded sandbox_setup_failed cache_disabled internal_error

Example

{
  "error": "Missing or invalid API key",
  "code": "unauthorized"
}

Headers

WWW-Authenticate

string

413

The body exceeds the configured size limit (payload_too_large)

object

error

required

Human-readable message

string

code

required

Stable machine-readable error code. Clients should treat unknown codes as internal_error.

string

Allowed values: invalid_request unauthorized not_found file_not_found payload_too_large limits_exceeded profile_not_allowed capacity_exhausted rate_limited shutting_down cancelled deadline_exceeded sandbox_setup_failed cache_disabled internal_error

Example

{
  "error": "The request body is larger than the configured limit",
  "code": "payload_too_large"
}

429

The API key has used up its requests (rate_limited). Sent only when the service enables per-key rate limiting (RATE_LIMIT_PER_MINUTE). Retry after the Retry-After header.

object

error

required

Human-readable message

string

code

required

Stable machine-readable error code. Clients should treat unknown codes as internal_error.

string

Allowed values: invalid_request unauthorized not_found file_not_found payload_too_large limits_exceeded profile_not_allowed capacity_exhausted rate_limited shutting_down cancelled deadline_exceeded sandbox_setup_failed cache_disabled internal_error

Example

{
  "error": "Rate limit exceeded for this API key",
  "code": "rate_limited"
}

Headers

Retry-After

integer

Seconds until the key may make another request

503

Too many concurrent uploads or the store is full (capacity_exhausted)

object

error

required

Human-readable message

string

code

required

Stable machine-readable error code. Clients should treat unknown codes as internal_error.

string

Allowed values: invalid_request unauthorized not_found file_not_found payload_too_large limits_exceeded profile_not_allowed capacity_exhausted rate_limited shutting_down cancelled deadline_exceeded sandbox_setup_failed cache_disabled internal_error

Example

{
  "error": "Too many uploads in progress",
  "code": "capacity_exhausted"
}