Skip to main content

​
Assets API

The assets API stores files inside the daemon state root and returns stable identifiers that can be referenced from later session inputs.

​
HTTP endpoints

  • GET /v1/assets
  • GET /v1/assets/{asset_id}
  • GET /v1/assets/{asset_id}/raw
  • POST /v1/assets
GET /v1/assets supports an optional query filter over the asset identifier, file name, media type, or digest.

​
Create an asset

POST /v1/assets accepts one inline upload payload: 
{
  "file_name": "note.txt",
  "media_type": "text/plain",
  "content_base64": "SU5MSU5FX0FTU0VUX09L"
}
The daemon persists the raw payload, normalizes the media type, and returns the stored asset view.

​
Asset views

Asset summaries returned by GET /v1/assets include:
  • asset_id
  • media_type
  • file_name
  • sha256
  • byte_length
  • created_at_ms
GET /v1/assets/{asset_id} returns the full asset view, including:
  • uri, an opaque daemon-managed raw storage reference
  • text_uri, an opaque daemon-managed derived-text reference when the daemon extracted prompt-ready text from the asset
  • preview_image_uri, an opaque daemon-managed visual preview reference when one exists
  • preview_image_media_type, the MIME type for that preview

​
Supported media types

The daemon currently accepts:
  • text/plain
  • text/csv
  • text/markdown
  • application/json
  • application/pdf
  • application/dxf
  • image/png
  • image/jpeg
  • audio/wav
  • audio/webm
  • audio/mpeg
  • audio/mp4
  • audio/m4a
  • audio/l16
  • audio/l24
Unsupported or mismatched file types are rejected before the asset is stored.

​
Normalization behavior

Important daemon-side rules:
  • imports are deduplicated by normalized media type and content digest
  • CSV aliases normalize to text/csv
  • DXF aliases normalize to application/dxf
  • MP3 aliases normalize to audio/mpeg, and M4A aliases normalize to audio/m4a
  • PNG and JPEG uploads are decoded and re-encoded into normalized daemon-owned image payloads
  • PDFs and supported text documents keep their raw payloads and, when possible, a derived text representation
  • supported audio assets can later gain a derived text_uri when the daemon performs speech-to-text and a transcription backend is configured
  • DXF uploads also derive a PNG preview when the daemon can parse the plan
  • derived document text is what text-only routes consume later during prompt rendering
Use GET /v1/assets/{asset_id}/raw when a client needs the exact persisted bytes rather than the metadata view.

​
Limits

Current limits enforced by the daemon:
  • maximum raw upload size: 12 MiB
  • maximum normalized image size: 4 MiB
  • maximum image edge: 2048 pixels
Use the asset store when you want stable reuse, restart safety, or explicit inspection of uploaded files before they are referenced by runs.