API

The vitrine API lets you manage models, configure scenes, and generate embed codes from any HTTP client — your own scripts, CI pipelines, or AI agents.

Base URL

https://api.vitrine3d.com

Authentication

API Key

Generate a key in the dashboard under Account → API Keys. Include it in the Authorization header:

Authorization: Bearer vt_abc123...

Supabase JWT

If you already have a Supabase session (e.g. from the dashboard), you can use the JWT directly. The API accepts both API keys and JWTs.

Anonymous

If no credentials are provided on a write request, the API creates an anonymous session automatically. Anonymous uploads expire after 48 hours. Link them to a permanent account by signing up.

Quick Start

List your models:

curl https://api.vitrine3d.com/v1/models \
  -H "Authorization: Bearer vt_abc123..."

Upload a GLB file:

curl -X POST https://api.vitrine3d.com/v1/models \
  -H "Authorization: Bearer vt_abc123..." \
  -F [email protected] \
  -F name="Running Shoe"

Configure the scene:

curl -X PATCH https://api.vitrine3d.com/v1/models/MODEL_ID/config \
  -H "Authorization: Bearer vt_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "bg_mode": "transparent",
    "hdri_preset": "studio_small_08_4k",
    "bloom_enabled": true,
    "bloom_intensity": 0.15
  }'

Publish and get embed code:

curl -X PATCH https://api.vitrine3d.com/v1/showcases/MODEL_ID \
  -H "Authorization: Bearer vt_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"published": true}'

curl https://api.vitrine3d.com/v1/showcases/MODEL_ID/embed \
  -H "Authorization: Bearer vt_abc123..."

Endpoints

Models

Method	Path	Description
`GET`	`/v1/models`	List your models
`POST`	`/v1/models`	Upload a GLB file (multipart)
`GET`	`/v1/models/:id`	Model details with merged config
`DELETE`	`/v1/models/:id`	Delete model and storage

Config

Method	Path	Description
`GET`	`/v1/models/:id/config`	Get merged scene config (look + layout + overrides)
`PATCH`	`/v1/models/:id/config`	Apply config patch

Showcases

Method	Path	Description
`PATCH`	`/v1/showcases/:id`	Update name, publish status, look, or layout
`GET`	`/v1/showcases/:id/embed`	Get embed HTML for a published model

Looks

Method	Path	Description
`GET`	`/v1/looks`	List your looks
`POST`	`/v1/looks`	Create a look from a config
`PATCH`	`/v1/looks/:id`	Update look name or config
`DELETE`	`/v1/looks/:id`	Delete look

Thumbnails

Method	Path	Description
`POST`	`/v1/models/:id/thumbnail`	Trigger server-side thumbnail render

Feedback

Method	Path	Description
`POST`	`/v1/feedback`	Submit a bug report or feature request

Account

Method	Path	Description
`GET`	`/v1/account`	Current user, plan, and usage
`POST`	`/v1/account/api-keys`	Generate a new API key
`DELETE`	`/v1/account/api-keys/:id`	Revoke an API key

Reference (no auth required)

Method	Path	Description
`GET`	`/v1/hdris`	List available HDRI presets
`GET`	`/v1/config-schema`	Scene config JSON schema

Config Patch Format

Only include fields you want to change. The patch is merged on top of the existing config:

{
  "bg_mode": "transparent",
  "bloom_enabled": true,
  "bloom_intensity": 0.15,
  "hdri_preset": "studio_small_08_4k",
  "auto_rotate": true
}

Use GET /v1/config-schema to see all available fields, types, enums, and defaults.

Rate Limits

Auth mode	Limit
Anonymous	20 requests/min
API Key (Free)	60 requests/min
API Key (Pro)	300 requests/min

Rate limit status is returned in the X-RateLimit-Remaining header.

Errors

All errors return a JSON body with error and message fields:

{
  "error": "model_not_found",
  "message": "No model found with ID 'abc123'"
}

Status	Meaning
400	Invalid request (bad config patch, missing field)
401	Not authenticated
403	Not authorized (wrong owner, plan limit reached)
404	Resource not found
429	Rate limited — check `Retry-After` header

On this page