Registry API v1
Authentication
Every endpoint requires an API key. Keys are server-to-server credentials tied to one partner organisation and a fixed set of scopes.
Passing your key
Either header works; use the bearer form unless your HTTP client makes that awkward.
Authorization: Bearer c24_live_<48 hex>
# or
x-api-key: c24_live_<48 hex>curl https://collect24.art/api/v1 \
-H "Authorization: Bearer c24_live_..."Collect24 stores only a SHA-256 hash of your key: it is displayed once, at creation, and cannot be recovered. If it is lost or exposed, ask us to revoke it and we issue a new one. Keys may carry an expiry date, and every authenticated call records the moment the key was last used.
Key errors
| Status | Code | Meaning |
|---|---|---|
| 401 | missing_api_key | No key was presented. |
| 401 | invalid_api_key | The key is unknown or not linked to an organisation. |
| 401 | revoked_api_key | The key was revoked. |
| 401 | expired_api_key | The key passed its expiry date. |
| 403 | organisation_inactive | The organisation's API access is not active. |
| 403 | missing_scope | The key does not carry the scope the endpoint requires. |
Scopes
Scopes are fixed per key. Requesting an endpoint outside your scopes returns 403 missing_scope.
| Scope | Grants |
|---|---|
artworks:read | Read and search artworks, including collection, gallery and museum listings. |
artworks:write | Create and update artworks inside your own organisation profile. |
artists:read | Read artist records and biographies. |
artists:write | Reserved for verified artist and representation partners. |
galleries:read | Read gallery profiles. |
museums:read | Read museum profiles. |
certificates:read | Read certificate metadata for works in your own profile. |
provenance:read | Read public provenance statements. |
webhooks:manage | Required for webhook-related access on your organisation. |
Write permission is more than a scope
artworks:write allows writing, but never outside your own data. Your key's organisation maps to exactly one collection profile (and optionally one gallery profile). A POST lands inside that profile; a PATCH is refused with 403 not_permitted unless the target artwork already sits in it. Fields that determine ownership or placement are rejected outright with 422 protected_field.
If your organisation has no linked profile yet, publishing returns 403 no_write_target — contact us to link your gallery, museum or collection.
Rate limits
Per key, per minute, with a default of 120 requests per minute. The counter is incremented atomically, so parallel requests cannot exceed the ceiling.
| Header | Meaning |
|---|---|
x-ratelimit-limit | Requests allowed in the current minute. |
x-ratelimit-remaining | Requests left in the window. |
x-ratelimit-reset | Unix seconds at which the window resets. |
Retry-After | Seconds to wait, sent with 429 responses. |
{
"error": {
"code": "rate_limited",
"message": "Too many requests. Retry after the current minute window.",
"limit": 120,
"retry_after_seconds": 24
}
}Handling keys safely
The API sets no Access-Control-Allow-Origin header, so browser JavaScript on other origins cannot read responses. Keep keys on your server, in environment variables or a secret manager — never in a browser bundle, mobile app or public repository. Every call is logged with method, path, status, duration, a truncated hash of the calling IP and the user agent; request and response bodies are never stored and credential-shaped query parameters are redacted before logging.
Need a key? Request access.