Save an artwork
Saves the artwork's pending edits: promotes them onto the record and snapshots a new version. Publication is unchanged — use `/go-live` to serve the saved version publicly.
Saves the artwork's pending edits: promotes them onto the record and snapshots a new version. Publication is unchanged — use /go-live to serve the saved version publicly.
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.
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}Preview a work to scale in a room POST
Renders the work hanging to true scale in the chosen room scene and returns a short-lived signed image URL. Deterministic and cached by storage path.
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.