Getting started

The Gallery Platform REST API lets you read and manage a gallery's content over HTTP — inventory, CRM, sales, invoices, offers, and more. Every endpoint lives under /api/v1, and the API is gallery-scoped: you authenticate with a gallery API key and the gallery is implicit in the key.

The API is served from the same origin as the app — the base URL is your platform host plus /api/v1. The examples below use gallery.example as a stand-in for that host.

1. Mint an API key

API keys are created in the app, from the gallery sidebar's Developer → API keys section. A key is shown once at creation — copy it immediately; it's stored only as a non-reversible hash and can't be retrieved again.

• Gallery keys are prefixed gpk_ and act as one gallery.
• Organization keys are prefixed opk_ and act as one organization, for the cross-gallery /api/v1/org/* endpoints. They're created from the organization's Settings page.

When you create a key you choose its access per resource — None, Read, or Read & write — much like Stripe's restricted keys. See Authentication for how that maps to scopes.

2. Send the key

Send the key as a bearer token on every request; the x-api-key header is accepted as an alternative:

Authorization: Bearer gpk_your_key_here

x-api-key: gpk_your_key_here

A missing or malformed key returns 401 Unauthorized (error format). Keys are secrets — use them only from a server, never from a browser.

3. Your first requests

Read the gallery the key is scoped to:

curl https://gallery.example/api/v1/gallery \
  -H "Authorization: Bearer gpk_your_key_here"

List its artworks (newest first, paginated):

curl "https://gallery.example/api/v1/gallery/artworks?limit=20" \
  -H "Authorization: Bearer gpk_your_key_here"

Create an artwork:

curl -X POST https://gallery.example/api/v1/gallery/artworks \
  -H "Authorization: Bearer gpk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Untitled (2026)" }'

The full, always-current endpoint list — with request/response schemas and an in-browser playground — is the API reference, generated from our OpenAPI document.

What's next

• Authentication — principals, scopes, and key handling.
• Errors — the RFC 9457 application/problem+json envelope.
• Pagination — the cursor model for list endpoints.
• Rate limits — the RateLimit headers and 429 behavior.
• Idempotency — safely retry writes with Idempotency-Key.
• Webhooks — receive signed events when content changes.

The OpenAPI document

The machine-readable spec is public and CORS-open at GET /api/v1/openapi.json — point your own code generators and tooling at it. This documentation site is generated from that same document.