Set an artwork's status
Sets the artwork's availability (and, optionally, its custom status label and ownership status) on the record now — live for every reader, whoever sends it. A pending draft that named the field is reconciled and the editor is told. Use this, not `PATCH`, for a state change.
Sets the artwork's availability (and, optionally, its custom status label and ownership status) on the record now — live for every reader, whoever sends it. A pending draft that named the field is reconciled and the editor is told. Use this, not PATCH, for a state change.
Authorization
bearerAuth artworks:updateA gallery API key, sent as Authorization: Bearer gpk_… (or the x-api-key header).
In: header
Scope: artworks:update
Path Parameters
The artwork id.
Query Parameters
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.
Set an artwork's status — live on the record now.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
{ "id": "string", "title": "string", "artist_id": "string", "artists": [ { "artist_id": "string", "role": "primary", "position": -9007199254740991, "artist_name": "string" } ], "dimensions": [ { "component": "overall", "label": "string", "height_cm": 0, "width_cm": 0, "depth_cm": 0, "position": -9007199254740991, "note": "string" } ], "artist_name": "string", "thumbnail_url": "string", "inventory_number": "string", "ownership_status": "owned", "availability_state": "available", "medium": "string", "year": -9007199254740991, "end_year": -9007199254740991, "date_precision": "year", "date_display": "string", "description": "string", "dimension_unit": "in", "height_cm": 0, "width_cm": 0, "depth_cm": 0, "framed_height_cm": 0, "framed_width_cm": 0, "framed_depth_cm": 0, "dimensions_text": "string", "location_id": "string", "price_cents": -9007199254740991, "currency": "string", "is_edition": true, "edition_number": -9007199254740991, "edition_size": -9007199254740991, "edition_type": "numbered", "edition_overrides": [ "string" ], "parent_artwork_id": "string", "coa_status": "not_required", "coa_tracking_number": "string", "condition_status": "excellent", "condition_notes": "string", "provenance": "string", "exhibition_history": "string", "literature": "string", "catalogue_raisonne": "string", "market": "primary", "custom_status_id": "string", "show_price_publicly": true, "published_at": "string", "published_version": -9007199254740991, "save_state": "new", "source_system": "string", "source_external_id": "string", "formats": [ { "id": "string", "artwork_id": "string", "label": "string", "height_cm": 0, "width_cm": 0, "depth_cm": 0, "dimension_unit": "in", "medium": "string", "edition_size": -9007199254740991, "stock_quantity": -9007199254740991, "availability_state": "available", "price_cents": -9007199254740991, "currency": "string", "position": -9007199254740991, "metadata": { "property1": "string", "property2": "string" }, "created_at": "string", "updated_at": "string" } ], "metadata": { "property1": "string", "property2": "string" }, "created_at": "string", "updated_at": "string"}{ "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}Find visually similar artworks GET
Returns artworks whose cover image is visually most similar to this one, most similar first, excluding the artwork itself. Empty until the work has been indexed by the visual-embedding worker.
Summarize inventory GET
Server-computed aggregates over the gallery's artworks for a filter set: the matching total, counts by work status, value totals summed per currency, and the unpriced count. Accepts the same filters as the list endpoint (status, artist_id, price/year bands, unpriced, published). Use this — not paging the list — to answer 'how many' / 'how much' questions correctly at any scale.