Registry API v1

Artworks

The core resource. Every artwork carries a permanent Collect24 Art ID (C24-1234) that stays stable across ownership, gallery, status and location changes.

Endpoints

Method	Path	Scope
GET	`/api/v1/artworks`	`artworks:read`
POST	`/api/v1/artworks`	`artworks:write`
GET	`/api/v1/artworks/{id}`	`artworks:read`
PATCH	`/api/v1/artworks/{id}`	`artworks:write`

{id} accepts a collect24_id or the record uuid.

Query parameters

Parameter	Type	Notes
`q`	string	Free text over title, artist name and medium.
`artist`	string	Artist slug or uuid.
`gallery`	string	Gallery slug or uuid.
`museum`	string	Museum slug or uuid.
`collection`	string	Collection slug or uuid.
`medium`	string	Partial match on medium.
`year`	string	Year of creation as recorded.
`availability`	string	for_sale, not_for_sale, on_loan, private_collection and other public states.
`collect24_id`	string	Exact permanent id lookup.
`price_min`	number	Only works with a public price.
`price_max`	number	Only works with a public price.
`updated_since`	ISO 8601	Switches ordering to ascending (updated_at, id).
`limit`	1–100	Default 25.
`offset`	0–100000	Default 0.

Query strings are strict: an unknown parameter returns 400 invalid_query with per-parameter issues, rather than being silently ignored. Filter values are sanitised before they reach the database, so commas, parentheses and operator syntax cannot alter a filter.

400 invalid_query

{
  "error": {
    "code": "invalid_query",
    "message": "One or more query parameters are invalid.",
    "issues": [{ "path": "limit", "message": "Number must be less than or equal to 100" }]
  }
}

Artwork object

Field	Type	Notes
`object`	string	Always `"artwork"`.
`collect24_id`	string	Permanent identifier. Store this.
`id`	uuid	Record uuid, also accepted in paths.
`title`	string \| null
`artist`	object \| null	id, name, slug.
`year_created`	string \| null	As recorded, may be a range or circa.
`medium`	string \| null
`dimensions_cm`	object \| null	height, width, depth.
`availability`	string	Public availability state.
`price`	object \| null	amount and currency, only when public.
`location`	object \| null	Country only, and only when shown publicly.
`current_collection`	object \| null	slug, name, type, city, country.
`images`	object	cover_url and thumbnail_url when available.
`provenance_summary`	string \| null	Public provenance statement.
`links`	object	self and public_page.
`created_at`	ISO 8601
`updated_at`	ISO 8601	Use for incremental sync.

Serializers are explicit allow-lists. Owner and user identifiers, private notes, valuations, acquisition prices, ownership rows, documents, offers, transactions, private provenance, admin review columns and internal pipeline state are never returned.

Publishing an artwork

POST /api/v1/artworks

curl -X POST https://collect24.art/api/v1/artworks \
  -H "Authorization: Bearer c24_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: INV-2024-113" \
  -d '{
    "title": "Untitled",
    "artist_name": "Jane Doe",
    "year_created": "2024",
    "medium": "Oil on linen",
    "height_cm": 120,
    "width_cm": 90,
    "depth_cm": null,
    "availability": "for_sale",
    "price": { "amount": 8500, "currency": "EUR" },
    "cover_image_url": "https://gallery.example/img/1.jpg",
    "external_id": "INV-2024-113",
    "source_url": "https://gallery.example/works/untitled",
    "inventory_ref": "INV-2024-113"
  }'

Result	Meaning
201, duplicate: false	Registered. The response contains the new collect24_id.
200, duplicate: true	An existing artwork matched; it is returned and nothing is created.
`403 no_write_target`	Your organisation has no linked gallery or collection profile.
`422 invalid_body`	Zod issues per field.
`422 protected_field`	You sent a field Collect24 manages.

Protected fields

Bodies are validated strictly: an unknown field returns 422 invalid_body. Fields that determine ownership or placement return 422 protected_field listing the offending names — collection_id, gallery_id, organization_id, owner_id, claimed_by, collect24_ref, id, source, match_fingerprint, timestamps and admin/review columns. Placement is derived server-side from your key's organisation.

422 protected_field

{
  "error": {
    "code": "protected_field",
    "message": "These fields are managed by Collect24 and cannot be set.",
    "fields": ["collection_id", "owner_id"]
  }
}

Updating an artwork

PATCH accepts the same fields, all optional, and only updates artworks inside your own profile — anything else returns 403 not_permitted. Moving a work to availability: "fully_private" withdraws it from the public projection: the response is 200 with data: null and public: false, and later reads return 404 artwork_not_found.

PATCH /api/v1/artworks/{id}

curl -X PATCH https://collect24.art/api/v1/artworks/C24-4711 \
  -H "Authorization: Bearer c24_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "availability": "not_for_sale", "medium": "Oil and wax on linen" }'

Full error reference: Errors.