Gallery Platform API
ReferenceGalleryArtworksIdFormats

Create an artwork format

Adds a sellable format/variant to an artwork, appended to the end. A supplied price writes the gated pricing sibling. Rejected on an edition umbrella (only its copies or a standalone work are sellable).

POST
/gallery/artworks/{id}/formats

Adds a sellable format/variant to an artwork, appended to the end. A supplied price writes the gated pricing sibling. Rejected on an edition umbrella (only its copies or a standalone work are sellable).

Authorization

bearerAuth artworks:write
AuthorizationBearer <token>

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

In: header

Scope: artworks:write

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 24h instead of re-running the write.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Create a format/variant on an artwork.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/gallery/artworks/{id}/formats" \  -H "Content-Type: application/json" \  -d '{    "label": "string"  }'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "artwork_id": "1a900bf9-a284-4c99-a359-1f6b482d475f",  "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,  "created_at": "string",  "updated_at": "string"}

List artwork formats GET

Lists an artwork's sellable formats/variants (sizes, papers, framings), each with its own dimensions, edition size, stock, and membership-gated price. A read-only key sees a format's price only when the work is public-priced.

Delete an artwork format DELETE

Permanently deletes a format/variant from an artwork.