Gallery Platform API
Reference

Search objects

Runs one declared type's saved-query document and returns one page of matches, with cursor pagination, the type's sort and its free-text search. The rows, their order and the cursor are the ones the type's own query route returns to this caller: for `artwork`, `POST /gallery/artworks/query`, for `party`, `GET /gallery/parties`, and for `artist`, `GET /gallery/artists`, so drafts the caller cannot see, other galleries and fields a read-only key's reads hide never appear. A key needs the scopes of that route: `artworks:read`, `gallery:read` and `artists:read` for `artwork`, `contacts:read` for `party`, `artists:read` for `artist`; without them the answer is 403. A type is searchable when its list declares saved-query fields. Refusals answer 400 with `details.reason`: `unknown_type` for an undeclared type and `not_searchable` for a declared type with no saved-query fields, `invalid_filter` for a document the type does not declare, `invalid_sort` for a sort key of another type (an artist search takes no `sort` or `dir`: its list has one fixed order), and `unsupported_rule` for a rule the type's list cannot run (for a party, a `none_of`, an `is_empty`, a second rule on one field; for an artist, a second rule on one field).

POST
/gallery/objects/search

Runs one declared type's saved-query document and returns one page of matches, with cursor pagination, the type's sort and its free-text search. The rows, their order and the cursor are the ones the type's own query route returns to this caller: for artwork, POST /gallery/artworks/query, for party, GET /gallery/parties, and for artist, GET /gallery/artists, so drafts the caller cannot see, other galleries and fields a read-only key's reads hide never appear. A key needs the scopes of that route: artworks:read, gallery:read and artists:read for artwork, contacts:read for party, artists:read for artist; without them the answer is 403. A type is searchable when its list declares saved-query fields. Refusals answer 400 with details.reason: unknown_type for an undeclared type and not_searchable for a declared type with no saved-query fields, invalid_filter for a document the type does not declare, invalid_sort for a sort key of another type (an artist search takes no sort or dir: its list has one fixed order), and unsupported_rule for a rule the type's list cannot run (for a party, a none_of, an is_empty, a second rule on one field; for an artist, a second rule on one field).

Authorization

AuthorizationBearer <token>

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

In: header

Scope: artworks:read

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Search one declared type with its saved-query document.

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"    }  ],  "next_cursor": "string"}