Skip to main content
POST
/
v1
/
assets
Error
A valid request URL is required to generate request examples
{
  "asset_id": "asset_d8aad64dib2c7m3ae7j1",
  "already_exists": true,
  "status": "ready"
}

Authorizations

​
X-API-Key
string
header
required

Personal Access Token, sent verbatim as pat_<32 chars>. PATs are minted from the Chief settings UI.

Headers

​
X-Project-Id
string
required

Project identifier scoping the request. Required on every project-scoped public endpoint. Missing or malformed values respond with HTTP 400 and code publicapi.tenancy.project.missing.

Pattern: ^project_[a-z0-9]{20}$

Body

application/json
​
filename
string
required

Original filename. Used for display and ingest hints.

​
mime_type
string
required

RFC 6838 media type of the upload.

​
md5
string

Hex-encoded md5 of the file. Optional. When supplied and content with this digest already exists in the project, the server returns the existing asset instead of a new upload URL.

Response

Content dedup hit. An asset with this md5 already exists in the project; no upload is needed.

Two shapes share this schema. A new upload (201) carries the signed-URL fields the client uses to PUT the bytes. A content-dedup hit (200) sets already_exists to true, reports the existing asset's status, and omits the upload fields.

​
asset_id
string
required
Pattern: ^asset_[a-z0-9]{20}$
​
already_exists
boolean
required

True when an asset with the request's md5 already existed; the upload fields are then absent.

​
status
enum<string>

Asset lifecycle. Progresses uploaded -> ingesting -> ready, or terminates at failed on any extraction error.

Available options:
uploaded,
ingesting,
ready,
failed
​
upload_url
string<uri>
​
upload_method
string

HTTP method to use for the upload. PUT today; resumable multi-part uploads may add new values without breaking the existing PUT flow.

Example:

"PUT"

​
upload_headers
object

Headers the client MUST apply verbatim to the upload request. Includes Content-Type.

​
expires_at
string<date-time>