Assets
List assets (keyset-paginated)
Returns one page of usable assets (each with a durable stored url) in the uniform list envelope `{ data, pagination }`. Keep paginating while `pagination.nextCursor` is non-null — even when `data` is empty — passing it back verbatim as `?cursor=`. Filter by `?type=`, `?status=` and/or `?favorited=true` (combinable); an omitted `?status=` returns the ready set (`active` + `completed`), and `?favorited=true` returns only shortlisted assets. Add `?showDeleted=true` to include deleted assets (every row then carries `deletedAt`).
Get a single asset by id
Returns the single usable asset with the given stable Mocart asset document id. Add `?showDeleted=true` to read a deleted asset too (the body then carries `deletedAt`). The strong `ETag` header identifies the asset state; send it back as `If-Match` on a write.
Edit an asset
Edits `favorited`, `notes` and `metadata` and returns the asset. Every field is optional; a body that changes nothing is a `200` that records nothing. The asset `status` is not editable: use `archive` and `unarchive`. `metadata` merges — a string sets a key, `null` deletes it, an unmentioned key stays.
Delete an asset
Deletes an asset and returns it with `deletedAt` set. The asset is only hidden, never destroyed: `POST /assets/{assetId}/undelete` restores it, and `?showDeleted=true` still reads it.
Archive an asset
Archives an asset and returns it. No request body. Archiving an archived asset is a no-op `200` that records nothing, so a retry is always safe; `Idempotency-Key` is required.
Unarchive an asset
Restores an archived asset to the status it held before, or `active` when that was never recorded, and returns it. No request body. Unarchiving an asset that is not archived is a no-op `200`; `Idempotency-Key` is required.
Restore a deleted asset
Restores a deleted asset and returns it: the same body `GET /assets/{id}` returns. There is no time limit. Restoring an asset that is already live is a no-op `200`; `Idempotency-Key` is required.