API documentation

Read your catalogue and upload preview documents programmatically. Machine-readable spec: openapi.json.

Authentication

Create a key in Settings → Connections and send it as a Bearer token on every request. Keep it secret, like a password (server-side only, never in a browser).

curl https://app.vitryne.art/api/v1/artworks \
  -H "Authorization: Bearer vit_your_key"

Base URL: https://app.vitryne.art/api/v1. All responses are JSON.

Errors

Errors use a consistent envelope and standard HTTP status codes:

{ "error": { "code": "quota_exceeded", "message": "Document quota reached for your plan." } }

401 unauthorized / invalid_key: missing or wrong key
402 quota_exceeded: document quota reached
403 plan_required: the workspace is on the free plan (the API is part of Studio and Unlimited)
404 not_found · 400 validation_error · 500 internal_error

Pagination

List endpoints accept limit (default 50, max 100) and offset, and return a pagination block:

{ "data": [ ... ], "pagination": { "limit": 50, "offset": 0, "total": 1234, "nextOffset": 50 } }

Reading your catalogue

GET/api/v1/artworks

List artworks. Query: q, availability, gallery (id), previewId, sort (recent · price_desc · price_asc · artist · position), limit, offset.

GET/api/v1/artworks/{id}

A single artwork with its images and source preview.

GET/api/v1/galleries

List galleries (senders) with preview + artwork counts.

GET/api/v1/galleries/{id}

A gallery by id or slug.

GET/api/v1/previews

List previews (uploaded documents).

GET/api/v1/previews/{id}

A preview's status. Add ?include=artworks for its works.

POST/api/v1/previews/{id}/retry

Run a failed import again, from its stored PDF or its viewing room link.

DELETE/api/v1/previews/{id}

Delete a preview with its works and files, e.g. a failed import.

GET/api/v1/stats

Totals: artworks, previews, counts by availability.

curl "https://app.vitryne.art/api/v1/artworks?availability=available&sort=price_desc&limit=20" \
  -H "Authorization: Bearer vit_your_key"

Connect an AI agent (MCP)

Vitryne is also an MCP server, so AI assistants and agents can query your catalogue directly: ask ChatGPT, Claude or Perplexity about your works, run valuations against your own prices, cross-reference availability, or import a gallery link. They can't change or delete anything.

ChatGPT and Claude: in Settings → Connectors, add a custom connector with the server URL below. You sign in with your Vitryne account and allow access: no key to copy.

Server URL   https://app.vitryne.art/api/mcp
Transport    Streamable HTTP
Auth         OAuth (sign in with Vitryne), or your vit_ key
             as a Bearer token (or X-API-Key header)

Perplexity (Pro / Max / Enterprise): Settings → Connectors → Custom connector → Remote. Paste the server URL, pick Streamable HTTP as transport and API Key as authentication, then paste your key. Your catalogue becomes a source Perplexity can search and cite.

Claude: add a custom connector with the same URL, or in Claude Code:

claude mcp add --transport http vitryne https://app.vitryne.art/api/mcp \
  --header "Authorization: Bearer vit_your_key"

Available tools:

search_artworks · search by artist, title, medium, availability, gallery, price sort
get_artwork · full details, images, preview price and your sale price
list_galleries · get_gallery · senders and their documents
list_previews · get_preview · uploaded documents and their works
get_stats · catalogue totals
import_preview_link · add a preview from an Artlogic private view or website viewing room, an Arternal viewing room or a PDF link
retry_preview · run a failed import again
delete_preview · delete a preview, e.g. a failed import

Uploading a document

Upload is a three-step flow so large PDFs go straight to storage:

Ask for a signed upload URL:

curl -X POST https://app.vitryne.art/api/v1/uploads \
  -H "Authorization: Bearer vit_your_key" \
  -H "content-type: application/json" \
  -d '{"filename":"lisson-frieze.pdf","size":8200000}'
# → { "data": { "uploadUrl": "https://…", "path": "<org>/incoming/<uuid>.pdf", "token": "…" } }

PUT the PDF bytes to uploadUrl:

curl -X PUT "<uploadUrl>" \
  -H "content-type: application/pdf" \
  --data-binary @lisson-frieze.pdf

Create the preview to start extraction:

curl -X POST https://app.vitryne.art/api/v1/previews \
  -H "Authorization: Bearer vit_your_key" \
  -H "content-type: application/json" \
  -d '{"path":"<path>","filename":"lisson-frieze.pdf"}'
# → 201 { "data": { "id": "<previewId>", "status": "processing" } }

Or skip the upload and send a link instead: an Artlogic private view or website viewing room, an Arternal viewing room or a direct link to a PDF.

curl -X POST https://app.vitryne.art/api/v1/previews \
  -H "Authorization: Bearer vit_your_key" \
  -H "content-type: application/json" \
  -d '{"url":"https://privateviews.artlogic.net/…"}'
# → 201 { "data": { "id": "<previewId>", "status": "processing" } }

Then poll until extraction finishes, and read the works:

curl "https://app.vitryne.art/api/v1/previews/<previewId>?include=artworks" \
  -H "Authorization: Bearer vit_your_key"
# status: "processing" → "done" (or "error"); artworkCount rises as works are found

Fair use

Uploads and imported links count toward your plan's document allowance (5 documents on the free plan, 50 a month on Studio, no limit on Unlimited). Reads are subject to fair use; sustained abuse may be throttled.