Gallery Platform API
Reference

Invoke an action

Runs one declared action by key, with its input checked against the schema `GET /gallery/ontology/actions` lists. The action runs exactly as its named route runs it: the same handler, access rules and change log. A key needs every scope the action's named route requires: `artworks:create` for `create_artwork`, `artworks:update` for `update_artwork`, `artworks:delete` with `artworks:update` for `delete_artwork`, `contacts:create` with `gallery:read` for `create_party`, `contacts:update` with `gallery:read` for `update_party`, `contacts:delete` with `contacts:update` for `delete_party`, `contacts:delete` with `contacts:update` and `gallery:read` for `merge_parties`, `artists:create` for `create_artist`, `artists:update` for `update_artist`, `artists:delete` for `delete_artist`, `shows:update` with `artworks:read` for `add_to_show`, `shows:update` for `update_show_work` and `remove_from_show`, and `shows:update` with `shows:delete` and `artworks:read` for `convert_show_type`; without them the answer is 403. A gated or outward action, and any destructive one, needs `confirm: true`; without it the answer is 400 with `details.reason` `approval_required` and nothing changes. An action with no binding answers 400 with `details.reason` `not_invocable`, and input that fails the action's schema answers 400 with `details.reason` `invalid_input`. `draft` places a record write as the named PATCH places it: the working draft for `true`, the record for `false`, the principal's default when omitted. `update_artist` answers `applied_to` as `PATCH /gallery/artists/{id}` does, and delivers `artist.updated` only for an edit that lands on the record. `update_party` answers `applied_to` as `PATCH /gallery/parties/{id}` does, and refuses a key's or app's `null` sub-profile with 403. `merge_parties` takes the survivor as `target` and `merged_id` in `input`, answers the survivor as `POST /gallery/parties/{id}/merge` does, refuses a party merged into itself with 400 and `details.field` `merged_id`, and delivers the survivor's `contact.updated` (webhook action `contact.merged`), then the merged party's `contact.deleted`. The Show actions take the show as `target` (`artwork_id` in `input` names the work), answer as their `/gallery/shows/{showId}/…` routes do, and deliver one `show.updated` when the call changed the show. `dry_run=true` returns the effect the action would have and commits nothing: it runs the same scope, target and input checks and refuses a caller the write would refuse, but needs no `confirm`, which the real call still does.

POST
/gallery/actions/invoke

Runs one declared action by key, with its input checked against the schema GET /gallery/ontology/actions lists. The action runs exactly as its named route runs it: the same handler, access rules and change log. A key needs every scope the action's named route requires: artworks:create for create_artwork, artworks:update for update_artwork, artworks:delete with artworks:update for delete_artwork, contacts:create with gallery:read for create_party, contacts:update with gallery:read for update_party, contacts:delete with contacts:update for delete_party, contacts:delete with contacts:update and gallery:read for merge_parties, artists:create for create_artist, artists:update for update_artist, artists:delete for delete_artist, shows:update with artworks:read for add_to_show, shows:update for update_show_work and remove_from_show, and shows:update with shows:delete and artworks:read for convert_show_type; without them the answer is 403. A gated or outward action, and any destructive one, needs confirm: true; without it the answer is 400 with details.reason approval_required and nothing changes. An action with no binding answers 400 with details.reason not_invocable, and input that fails the action's schema answers 400 with details.reason invalid_input. draft places a record write as the named PATCH places it: the working draft for true, the record for false, the principal's default when omitted. update_artist answers applied_to as PATCH /gallery/artists/{id} does, and delivers artist.updated only for an edit that lands on the record. update_party answers applied_to as PATCH /gallery/parties/{id} does, and refuses a key's or app's null sub-profile with 403. merge_parties takes the survivor as target and merged_id in input, answers the survivor as POST /gallery/parties/{id}/merge does, refuses a party merged into itself with 400 and details.field merged_id, and delivers the survivor's contact.updated (webhook action contact.merged), then the merged party's contact.deleted. The Show actions take the show as target (artwork_id in input names the work), answer as their /gallery/shows/{showId}/… routes do, and deliver one show.updated when the call changed the show. dry_run=true returns the effect the action would have and commits nothing: it runs the same scope, target and input checks and refuses a caller the write would refuse, but needs no confirm, which the real call still does.

Authorization

AuthorizationBearer <token>

A gallery API key, sent as Authorization: Bearer gpk_… (or the x-api-key header).

In: header

Scope: artworks:create

Query Parameters

draft?string

Where the write lands. true: the working draft (a member's default). false: the record itself, reconciling any pending draft (a key's default). Omit for the principal's default.

dry_run?boolean

Preview this operation without committing it. When true, the request is authenticated, scoped, and validated, but no side effect runs — no write, no idempotency claim, no audit event, no outbound delivery. The response is HTTP 200 with an X-Dry-Run: true header and a body of { "dry_run": true }, plus an effect object describing what the real call would change when this operation can resolve one.

Header Parameters

Idempotency-Key?string

Optional. Send a unique key per logical operation to make retries safe: a retry with the same key replays the stored success for 14 days instead of re-running the write. Reusing a key with a different body returns 400.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

{  "action": "string",  "type": "string",  "data": {    "property1": null,    "property2": null  }}