Developer Reference

Gilded Art Works API

Build integrations with our REST API. Manage artworks, generate documents, configure webhooks, and automate your art documentation workflow.

Base URL: https://www.gildedartworks.com/apiAuth: Supabase session cookieFormat: JSON

Authentication

Authenticated endpoints read the Supabase session cookie set when you sign in, and return 401 Unauthorized when there is none. That is the only authentication path implemented.

Keys with a ga_live_ prefix can be minted from Dashboard Settings and are stored hashed, but no route checks one. An Authorization header is never read — a request carrying one is treated exactly as a request without it. Programmatic access from outside a browser session is not available yet.

# From a signed-in browser session (cookie sent automatically):
fetch('/api/artworks').then(r => r.json())

Endpoints

GET/api/artworksAuth

List all artworks in your library

Response: { artworks: Artwork[] }

POST/api/artworksAuth

Create a new artwork record

Parameter	Type	Required
`title`	string	✓
`artist_name`	string	✓
`medium`	string	—
`year`	number	—
`dimensions`	string	—

Response: { artwork: Artwork }

POST/api/documents/pdfAuth

Generate a PDF document (certificate, brochure, customs form)

Parameter	Type	Required	Notes
`type`	string	✓	certificate \| brochure \| customs \| bill-of-sale \| condition-report \| provenance
`artwork_id`	string	✓

Response: PDF binary (application/pdf)

GET/api/searchAuth

Full-text search across artworks, documents, and audit logs

Parameter	Type	Required	Notes
`q`	string	✓	Min 2 characters
`scope`	string	—	all \| artworks \| documents \| audit
`limit`	number	—	Max 50

Response: { artworks: [], documents: [], audit: [], total: number }

GET/api/exportAuth

Export data as CSV or JSON

Parameter	Type	Required	Notes
`type`	string	✓	artworks \| documents \| analytics \| audit \| webhooks
`format`	string	—	csv \| json (default: csv)

Response: File download

POST/api/batchAuth

Execute bulk operations (max 50 per batch)

Parameter	Type	Required	Notes
`operations`	BatchOperation[]	✓	{ action, resource, id?, data? }

Response: { total, success, errors, results: BatchResult[] }

GET/api/verify/[artworkId]

Public verification endpoint for artwork authenticity

Parameter	Type	Required	Notes
`artworkId`	string	✓	URL parameter

Response: { verified: boolean, artwork: { title, artist, year } }

GET/api/webhooks/manageAuth

List your webhook subscriptions

Response: { subscriptions: WebhookSub[], supported_events: string[] }

POST/api/webhooks/manageAuth

Create a webhook subscription

Parameter	Type	Required
`url`	string	✓
`events`	string[]	✓
`description`	string	—

Response: { subscription: WebhookSub, secret: string }

POST/api/webhooks/testAuth

Send a test event to a webhook subscription

Parameter	Type	Required	Notes
`subscription_id`	string	✓
`event`	string	✓

Response: { delivery_id, status, response_code, duration_ms, payload_sent }

GET/api/keysAuth

List your API keys (masked)

Response: { keys: ApiKey[] }

POST/api/keysAuth

Generate a new API key (max 5 per account)

Parameter	Type	Required	Notes
`name`	string	✓
`scopes`	string[]	—

Response: { id, name, key, warning }

GET/api/activityAuth

Unified activity timeline (documents, artworks, shares, audit)

Response: { events: ActivityEvent[], total: number }

GET/api/health

Platform health check (database, auth, payments)

Response: { status, services: { db, auth, stripe }, latency_ms }

Webhook Events

Subscribe to platform events and receive HMAC-SHA256 signed payloads at your endpoint. Verify signatures using the X-Gilded-Signature header.

artwork.createdartwork.updatedartwork.deleteddocument.generateddocument.downloadedverification.checkedorder.createdorder.shippedpayment.receivedteam.member_added

Rate Limits

All API endpoints are rate-limited using a sliding-window algorithm. When rate-limited, you'll receive a 429 response withRetry-After and X-RateLimit-Reset headers.

Endpoint	Limit	Window
/api/shipping	10	1 minute
/api/checkout	5	1 minute
/api/documents/pdf	15	1 minute
/api/artworks	20	1 minute
/api/verify	30	1 minute
/api/batch	10	1 minute