Media

Images, audio, video and files, uploaded once and referenced by id.

Generated from the contract, version 2.0.0-draft.2 (OpenAPI). Base URL https://usekabu.com/api. Errors are problem details, each code with its own page.

Upload a file up to 25 MiB

POST/v2/media

Returns status ready: the bytes are verified, hashed and pinned before the response, so the id can be attached to an ask immediately. An org owner may call it with a user token for purpose=brand_logo or purpose=avatar only (an image); any other purpose with a user token is 403.

Auth: an API key, or a signed-in human’s token (the Kabu apps).
Scopes: media:write.
Signed-in humans: owner.

Parameter	In	Type	Required	Description
`Idempotency-Key`	header	string, at most 255 characters	Optional	Retry-safe key. For messages, sessions and responses it binds to the created object for its life; elsewhere for 24 h.
`Kabu-Org`	header	string	Optional	Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.

Request body: multipart/form-data: MediaUpload.

Status	Means	Body
`201`	OK	Media
`4XX`	Error	Problem
`5XX`	Error	Problem

curl -X POST "https://usekabu.com/api/v2/media" \
  -H "Authorization: Bearer $KABU_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@./report.pdf"

Presigned (resumable) upload up to 2 GiB

POST/v2/media/uploads

PUT the bytes to upload_url. A durable finaliser (with periodic reconciliation for lost storage events) verifies size, sha256 and content type, pins an immutable object version and only then marks the media ready; the upload URL cannot overwrite ready content. Replaying with the same Idempotency-Key while uploading returns a fresh upload_url; after 24 h unfinished uploads expire (410 upload_expired) and their reservation is released.

Auth: an API key.
Scopes: media:write.

Parameter	In	Type	Required	Description
`Idempotency-Key`	header	string, at most 255 characters	Optional	Retry-safe key. For messages, sessions and responses it binds to the created object for its life; elsewhere for 24 h.

Request body: UploadCreate.

Status	Means	Body
`201`	OK	Upload
`4XX`	Error	Problem
`5XX`	Error	Problem

curl -X POST "https://usekabu.com/api/v2/media/uploads" \
  -H "Authorization: Bearer $KABU_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"filename":"…","content_type":"…","size":1,"sha256":"…"}'

Get media with a fresh signed URL; with wait, hold until ready or failed

GET/v2/media/{media_id}

Auth: an API key, or a signed-in human’s token (the Kabu apps).
Scopes: messages:read.
Signed-in humans: audience.

Parameter	In	Type	Required	Description
`media_id`	path	string	Required	A `med_…` id.
`wait`	query	integer, from 0 to 50	Optional	Hold up to N seconds for the state to settle. 0 or absent returns at once. The kabu CLI and the MCP tools wait 25.
`Kabu-Org`	header	string	Optional	Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner.

Status	Means	Body
`200`	OK	Media
`4XX`	Error	Problem
`5XX`	Error	Problem

curl "https://usekabu.com/api/v2/media/$MEDIA_ID" \
  -H "Authorization: Bearer $KABU_API_KEY"

Erase the bytes

DELETE/v2/media/{media_id}

Auth: an API key.
Scopes: media:write.

Parameter	In	Type	Required	Description
`media_id`	path	string	Required	A `med_…` id.

Status	Means	Body
`204`	Done
`4XX`	Error	Problem
`5XX`	Error	Problem

curl -X DELETE "https://usekabu.com/api/v2/media/$MEDIA_ID" \
  -H "Authorization: Bearer $KABU_API_KEY"

Schemas

MediaUpload

Property	Type	Required	Description
`file`	string (binary)	Required	The file part, with a filename and content type.
`purpose`	string, one of `"attachment"`, `"avatar"`, `"brand_logo"`	Optional	`brand_logo` and `avatar` accept an image only and are the two purposes an org owner may upload with a user token (an avatar is the photo of a project or agent); every other purpose needs an API key.

Unknown properties are refused.

UploadCreate

Property	Type	Required
`filename`	string, at most 255 characters	Required
`content_type`	string	Required
`size`	integer, from 1 to 2147483648	Required
`sha256`	string, matching `^[a-f0-9]{64}$`	Required

Unknown properties are refused.

Upload

Property	Type	Required	Description
`object`	`"upload"`	Required
`media`	Media	Required
`upload_url`	string (uri)	Required
`headers`	object	Required
`resumable`	boolean	Required	True only when upload_url is Kabu’s own endpoint implementing IETF Resumable Uploads; a presigned object-storage PUT is false.
`expires_at`	Timestamp	Required