Gallery Platform API
Reference

Get an object

Returns one object by its public id, whatever its type: the id prefix names the type, and the answer is that type's own read, with the same access and field visibility. A key needs the scopes of the type's named read: `artworks:read` and `artists:read` for an artwork, `locations:read` for a location, `contacts:read` and `gallery:read` for a party, `artists:read` for an artist, `shows:read` for a booth, `artworks:update` and `contacts:read` for a hold; without them the answer is 403. `expand` follows the named links one level, and each far-end type needs its own read scopes too. An id whose prefix no declared type owns answers 404, and so does a merged-away party or artist id; a declared type with no read answers 400 with `details.reason` `not_readable`.

GET
/gallery/objects/{id}

Returns one object by its public id, whatever its type: the id prefix names the type, and the answer is that type's own read, with the same access and field visibility. A key needs the scopes of the type's named read: artworks:read and artists:read for an artwork, locations:read for a location, contacts:read and gallery:read for a party, artists:read for an artist, shows:read for a booth, artworks:update and contacts:read for a hold; without them the answer is 403. expand follows the named links one level, and each far-end type needs its own read scopes too. An id whose prefix no declared type owns answers 404, and so does a merged-away party or artist id; a declared type with no read answers 400 with details.reason not_readable.

Authorization

AuthorizationBearer <token>

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

In: header

Scope: artworks:read

Path Parameters

id*string

The object id.

Query Parameters

expand?array<>

Comma-separated link keys to follow one level, as describe_ontology lists them on the type (for example in-custody-of). owns and created-by are not expanded; traverse follows them. Each far-end object is read through its own type's read.

Itemsitems <= 10

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

{  "type": "artwork",  "data": {    "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",    "work_type": "painting",    "custom_status_id": "string",    "show_price_publicly": true,    "published_at": "string",    "published_version": -9007199254740991,    "save_state": "new",    "source_system": "string",    "source_external_id": "string",    "ulan": "string",    "wikidata": "string",    "isni": "string",    "viaf": "string",    "lei": "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"  },  "links": {    "property1": {      "type": "artwork",      "data": [        {          "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",          "work_type": "painting",          "custom_status_id": "string",          "show_price_publicly": true,          "published_at": "string",          "published_version": -9007199254740991,          "save_state": "new",          "source_system": "string",          "source_external_id": "string",          "ulan": "string",          "wikidata": "string",          "isni": "string",          "viaf": "string",          "lei": "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"        }      ],      "has_more": true    },    "property2": {      "type": "artwork",      "data": [        {          "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",          "work_type": "painting",          "custom_status_id": "string",          "show_price_publicly": true,          "published_at": "string",          "published_version": -9007199254740991,          "save_state": "new",          "source_system": "string",          "source_external_id": "string",          "ulan": "string",          "wikidata": "string",          "isni": "string",          "viaf": "string",          "lei": "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"        }      ],      "has_more": true    }  }}

Aggregate objects POST

Counts, sums or averages one declared type's records, grouped by up to three declared properties and narrowed by the type's own list filters. The rows are the ones the type's list returns to this caller, so drafts it cannot see, other galleries and anything access rules hide are never counted. A key needs the scopes of the type's named list: `artworks:read` and `artists:read` for `artwork`, `locations:read` for `location`, `contacts:read` for `party`, `artists:read` for `artist`, `shows:read` for `booth`, `artworks:update` and `contacts:read` for `hold`; without them the answer is 403. Refusals answer 400 with `details.reason`: `withheld` for a withheld property, `restricted` for a property the caller's role cannot read, `hidden_from_key` for a field a read-only key's reads hide, `not_numeric` for a sum or average over a non-numeric property, `currency_required` for a money sum not grouped by its currency, `unknown_type`, `not_readable` for a type with no list read, `unknown_property`, `not_groupable`, `unknown_filter`, `invalid_filter`, `duplicate`, and `group_restricted` for a party property outside `kind`, `contact_type`, `lead_status` and `do_not_email`, since a party's text values are never group keys, for an artist property other than `visibility`, for a booth property other than `show_id`, `hall` and `sector`, and for a hold property other than `artwork_id`, `party_id`, `ends_on` and `released_reason`. A scan reads a bounded number of rows; `capped` says when a cap cut the answer.

Traverse links from an object POST

Follows a path of declared link types from one object, one link type per hop, up to three hops, and returns each object reached once, at its nearest hop, with the edge that led there and the path from the start. Time-bounded edges are filtered at `as_of` (now when omitted). Fan-out and the object count are capped, and the response says which caps cut the walk. The walk never leaves the gallery and never passes an object the caller cannot read; such a start answers 404. Needs a signed-in member: an API key answers 403.