assets

Upload an asset (single-call multipart)

Changed on

Single-call multipart/form-data upload. The platform streams the bytes through its trusted byte-path, dedups by the server-computed hash, and mints the asset record.

The blake3 hash is always computed server-side from the received bytes — a client-declared expected_hash is verified, never trusted. The uploaded asset is referenceable immediately; any content scanning runs in the background and does not block the response.

~100 MB single-request expectation for v1; chunked/resumable large uploads are a deliberate open question.

post/api/v2/assets

Request

  • Base URL: http://127.0.0.1:8189
  • URL: http://127.0.0.1:8189/api/v2/assets
  • Auth: one of:
    • HTTP bearer
    • none

Headers

Idempotency-Keystring

Client-generated UUID (recommended). Single-use: the first request to present a key is processed; any later request with the same key is rejected 422 idempotency_key_reuse (reject-on-duplicate, no response replay). Keys expire after 24h.

Response

Bytes deduped to an existing blob; asset minted over it.

idstring required
hashstring nullable required

blake3:<hex>; null while lazily computed.

size_bytesinteger required
content_typestring required
file_pathstring nullable
created_newboolean

On create responses: distinguishes a brand-new blob (true) from a dedup hit against bytes the platform already had (false).

created_atstring date-time required
urlstring uri required

Short-lived content URL (signed, or proxy-served).

url_expires_atstring date-time required
expires_atstring date-time nullable

Retention deadline for the asset itself (distinct from url_expires_at, the signed URL's validity). Null or absent means the asset is non-expiring. On a dedup-hit create response the deadline may be later than now + the requested/default retention: re-referencing content extends its retention, never shortens it.

job_idstring nullable

ID of the job that produced this asset. Absent for uploaded assets, which have no producing job.

Example response

{
  "id": "9f8a1c0d-2b3e-4f56-8a7b-1c2d3e4f5a6b",
  "hash": "blake3:9f8a1c0d...",
  "size_bytes": 4816293,
  "content_type": "image/png",
  "file_path": "photo.png"
}

Changes

  • 2edfd164baddRevision changes
    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • d4300ec5fe59Revision changes
    • breaking

      removed the success response with the status