Update an artwork

Updates an artwork's editable fields. For a member, edits accumulate in the working draft and the published state the site serves is unchanged until the next save; for an API key or an installed app, they land on the record itself. Pass `draft=true` or `draft=false` to choose; the response's `applied_to` says where the write went.

Updates an artwork's editable fields. For a member, edits accumulate in the working draft and the published state the site serves is unchanged until the next save; for an API key or an installed app, they land on the record itself. Pass draft=true or draft=false to choose; the response's applied_to says where the write went.

Authorization

bearerAuth artworks:update

AuthorizationBearer <token>

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

In: header

Scope: artworks:update

Path Parameters

id*string

The artwork id.

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.

Fields to update on an artwork (all optional).

title?string

Display title.

Length1 <= length <= 200000

artist_id?|

The artist id.

artists?array<>

The makers on the roster.

Itemsitems <= 50

dimensions?array<>

Component dimensions of the work.

Itemsitems <= 50

inventory_number?|

The gallery's own inventory number.

ownership_status?string

Who owns the work; the schema's enum lists the values.

Value in

"owned"
"consigned_in"
"ex_inventory"
"third_party"

availability_state?string

Sale availability; the schema's enum lists the values.

Value in

"available"
"reserved"
"on_hold"
"under_offer"
"on_approval"
"on_loan"
"sold"
"not_for_sale"
"returned"
"destroyed"
"damaged"
"gift_donated"

custom_status_id?|

The custom status id.

medium?|

Medium or materials, as displayed.

year?|

Year, as a four-digit number.

end_year?|

End year of a range, as a four-digit number.

date_precision?string

How precise the date is; the schema's enum lists the values.

Value in

"year"
"circa"
"decade"
"century"
"range"
"unknown"

date_display?|

The date as it should be displayed, when the structured date is not enough.

description?|

Free-text description.

dimension_unit?string

Unit the dimensions are entered in; the schema's enum lists the values.

Value in

"in"
"cm"

height_cm?|

Height in centimetres.

width_cm?|

Width in centimetres.

depth_cm?|

Depth in centimetres.

framed_height_cm?|

Framed height in centimetres.

framed_width_cm?|

Framed width in centimetres.

framed_depth_cm?|

Framed depth in centimetres.

dimensions_text?|

Dimensions as free text, when the numeric fields do not fit.

location_id?|

The location id.

price_cents?|

Price, in the currency's minor unit (cents).

currency?|

ISO 4217 currency code, e.g. USD.

is_edition?boolean

Whether the work is part of an edition.

edition_number?|

This work's number within the edition.

edition_size?|

Total number in the edition.

edition_type?|

Edition kind; the schema's enum lists the values.

coa_status?string

Certificate-of-authenticity status; the schema's enum lists the values.

Value in

"not_required"
"requested"
"ready_to_send"
"sent"
"available"

coa_tracking_number?|null

condition_status?|

Condition grade; the schema's enum lists the values.

condition_notes?|

Condition notes.

provenance?|

Provenance history, as displayed.

exhibition_history?|

Exhibition history, as displayed.

literature?|

Literature references, as displayed.

catalogue_raisonne?|

Catalogue raisonné reference.

market?|

Market segment; the schema's enum lists the values.

show_price_publicly?boolean

Whether the price is shown on public surfaces.

metadata?|

Free-form JSON the caller owns; stored and returned verbatim, never interpreted.

Response Body

`application/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",  "applied_to": "draft"}

{  "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}

Authorization

Path Parameters

Query Parameters

Header Parameters

Request Body

Response Body

200application/json

400application/problem+json

401application/problem+json

403application/problem+json

404application/problem+json

429application/problem+json

503application/problem+json

`application/json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`

`application/problem+json`