gallery

GET /gallery/items

Query items, scoped to the caller unless scope=all.

R38. `scope=all` needs `gallery.read_all` (403 otherwise). `studio` narrows `scope=all` to one studio. Filters combine with AND; `tag` repeats and every tag must be present. `q` is full-text over title and `params.prompt` (Q17), FTS5 query syntax. Ordered `created_at` descending, `id` breaking ties, with or without `q`. Deleted items are never returned.

Needs the gallery capability.

Go	`Query(ctx context.Context, params GalleryQueryParams) (ItemPage, error)`
Python	`def query(self, *, scope: Optional[Any] = None, studio: Optional[Any] = None, kind: Optional[Any] = None, tag: Optional[Sequence[str]] = None, session_id: Optional[Any] = None, starred: Optional[Any] = None, asset_id: Optional[Any] = None, since: Optional[Any] = None, until: Optional[Any] = None, q: Optional[Any] = None, limit: Optional[Any] = None, cursor: Optional[Any] = None) -> Any`
JavaScript	`query(params = {})`

Parameter	In	Type	About
scope	query	string (self \| all)
studio	query	StudioIdValue
kind	query	AssetKind
tag	query	string[]
session_id	query	ULID
starred	query	boolean
asset_id	query	ULID
since	query	string	Items created at or after this time.
until	query	string	Items created before this time.
q	query	string
limit	query	integer
cursor	query	string	The `next_cursor` of the previous page, unchanged.

Status	Body	Means
200	ItemPage	A page of items.
400	Error	The request is malformed. Codes: `bad_request`, `bad_filter`, `bad_cursor`, `invalid_document`.
401	Error	No studio token, or a revoked or unknown one. Code `unauthenticated`.
403	Error	The token lacks a capability (`capability_required`, with `details.capability`), the job is not a task the studio may change (`not_a_task`), or the request came from another origin (`bad_origin`).

POST /gallery/items

Record an output with its params, inputs, tags and session. One call per generation.

07 §5. The item, its inputs, its tags and its search entry are written in one transaction (06 §8). `asset_id` and every input's `asset_id` must be readable by the caller (Q9), else 404; `session_id` must be one of the caller's live sessions, else 422 `unknown_session` (Q15). Duplicate `(asset_id, role)` inputs and duplicate tags are collapsed.

Needs the gallery capability.

Go	`Add(ctx context.Context, body ItemCreate) (*Item, error)`
Python	`def add(self, body: Dict[str, Any]) -> Any`
JavaScript	`add(body)`

Request body: ItemCreate (application/json)

Status	Body	Means
201	Item	The recorded item.
400	Error	The request is malformed. Codes: `bad_request`, `bad_filter`, `bad_cursor`, `invalid_document`.
401	Error	No studio token, or a revoked or unknown one. Code `unauthenticated`.
403	Error	The token lacks a capability (`capability_required`, with `details.capability`), the job is not a task the studio may change (`not_a_task`), or the request came from another origin (`bad_origin`).
404	Error	Absent, deleted, or not the caller's to see. Code `not_found`.
413	Error	The body is over its limit. Code `too_large`, with `details.limit` in bytes.
422	Error	Well-formed but refused. Codes: `outside_roots`, `cross_device`, `not_a_file`, `unknown_session`, `self_handoff`, `not_launchable`, `blocked`, `not_linkable`.

GET /gallery/items/{id}

One item. Another studio's without gallery.read_all, or a deleted one, is 404.

Needs the gallery capability.

Go	`Get(ctx context.Context, id string) (*Item, error)`
Python	`def get(self, id: str) -> Any`
JavaScript	`get(id)`

Parameter	In	Type	About
id	path · required	ULID

Status	Body	Means
200	Item	The item.
401	Error	No studio token, or a revoked or unknown one. Code `unauthenticated`.
403	Error	The token lacks a capability (`capability_required`, with `details.capability`), the job is not a task the studio may change (`not_a_task`), or the request came from another origin (`bad_origin`).
404	Error	Absent, deleted, or not the caller's to see. Code `not_found`.

PATCH /gallery/items/{id}

Star, tag or rename one of the caller's own items.

07 §3, Q16, M4 first review #11. A JSON merge patch: `tags`, an array, replaces the whole set; `title: null` clears the title. Params, inputs, asset and session are provenance and cannot change. Another studio's item is 404, even with `gallery.read_all`.

Needs the gallery capability.

Go	`Update(ctx context.Context, id string, body map[string]any) (*Item, error)`
Python	`def update(self, id: str, body: Dict[str, Any]) -> Any`
JavaScript	`update(id, body)`

Parameter	In	Type	About
id	path · required	ULID

Request body: ItemUpdate (application/merge-patch+json)

Status	Body	Means
200	Item	The updated item.
400	Error	The request is malformed. Codes: `bad_request`, `bad_filter`, `bad_cursor`, `invalid_document`.
401	Error	No studio token, or a revoked or unknown one. Code `unauthenticated`.
403	Error	The token lacks a capability (`capability_required`, with `details.capability`), the job is not a task the studio may change (`not_a_task`), or the request came from another origin (`bad_origin`).
404	Error	Absent, deleted, or not the caller's to see. Code `not_found`.

DELETE /gallery/items/{id}

Soft-delete one of the caller's own items.

Q16, M4 first review #1. The item leaves every query, and every lineage result. Its row, inputs and tags stay until an asset reclaim takes one of the assets it names, which hard-deletes it (see POST /assets:reclaim). Until then the delete loses nothing. Its asset, and the assets it used as inputs, stop counting as referenced by it.

Needs the gallery capability.

Go	`Delete(ctx context.Context, id string) error`
Python	`def delete(self, id: str) -> Any`
JavaScript	`delete(id)`

Parameter	In	Type	About
id	path · required	ULID

Status	Body	Means
204		Deleted.
401	Error	No studio token, or a revoked or unknown one. Code `unauthenticated`.
403	Error	The token lacks a capability (`capability_required`, with `details.capability`), the job is not a task the studio may change (`not_a_task`), or the request came from another origin (`bad_origin`).
404	Error	Absent, deleted, or not the caller's to see. Code `not_found`.

GET /gallery/items/{id}/lineage

Upstream provenance — the items whose outputs this item was made from, recursively.

Q16. From the item's inputs to the items whose asset is that input, then onward. Inputs no item produced (a user import) end the walk and are visible in each item's `inputs`. Other studios' items are left out unless the caller holds `gallery.read_all`; the walk still passes through them. Soft-deleted items are left out of the result, and the walk passes through them too. Ordered `created_at` descending.

Needs the gallery capability.

Go	`Lineage(ctx context.Context, id string, params GalleryLineageParams) (ItemPage, error)`
Python	`def lineage(self, id: str, *, limit: Optional[Any] = None, cursor: Optional[Any] = None) -> Any`
JavaScript	`lineage(id, params = {})`

Parameter	In	Type	About
id	path · required	ULID
limit	query	integer
cursor	query	string	The `next_cursor` of the previous page, unchanged.

Status	Body	Means
200	ItemPage	A page of items.
400	Error	The request is malformed. Codes: `bad_request`, `bad_filter`, `bad_cursor`, `invalid_document`.
401	Error	No studio token, or a revoked or unknown one. Code `unauthenticated`.
403	Error	The token lacks a capability (`capability_required`, with `details.capability`), the job is not a task the studio may change (`not_a_task`), or the request came from another origin (`bad_origin`).
404	Error	Absent, deleted, or not the caller's to see. Code `not_found`.