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.
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.
A gallery API key, sent as Authorization: Bearer gpk_… (or the x-api-key header).
In: header
Scope: artworks:create
Query Parameters
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.
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
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 }}{ "type": "../dictionary", "title": "string", "status": 0, "detail": "string", "code": "invalid_request", "retry": "permanent", "details": null}{ "type": "../dictionary", "title": "string", "status": 0, "detail": "string", "code": "invalid_request", "retry": "permanent", "details": null}{ "type": "../dictionary", "title": "string", "status": 0, "detail": "string", "code": "invalid_request", "retry": "permanent", "details": null}{ "type": "../dictionary", "title": "string", "status": 0, "detail": "string", "code": "invalid_request", "retry": "permanent", "details": null}{ "type": "../dictionary", "title": "string", "status": 0, "detail": "string", "code": "invalid_request", "retry": "permanent", "details": null}{ "type": "../dictionary", "title": "string", "status": 0, "detail": "string", "code": "invalid_request", "retry": "permanent", "details": null}Invoicing & payments
Create invoices through the API and collect payment on the gallery's Stripe — get a hosted checkout link in the create response and settle via webhooks.
List artist connections GET
Lists the gallery's artist studio connections, newest first, with cursor pagination. Filter with ?status=active.