Gilded Art Works
API Reference
The endpoints below are the ones the application itself calls, and they authenticate with the signed-in browser session. There is no token-based access path yet, so you cannot drive them from a server, a script or another product today. This page documents what exists so that you can judge the shape of the integration before it opens — and so that nothing here sends you at a route that will 404.
Authentication
Every endpoint on this page resolves the caller from the Supabase session cookie set when you sign in, and returns 401 Unauthorized when there is none. That is the only authentication path implemented. Requests carrying an Authorization header are not rejected — the header is simply never read, and the request is treated as unauthenticated.
You can already mint keys with a ga_live_ prefix under Dashboard → Settings → API Keys, and they are stored hashed, capped at five active keys per account and individually revocable. They are not yet accepted as request credentials by any route. Generating one now means the key exists when key authentication ships; it does not let you call anything today.
https://www.gildedartworks.com/apiRate Limits
Limits are per route and per minute, and they are the same on every plan — Essentials and Enterprise are throttled identically. Two layers apply: a per-IP window held in memory, then a per-user counter in the database. The database layer fails open, so a limiter outage relaxes the limit rather than taking the route down. Checkout is tighter than the rest at five requests a minute.
Rate-limit headers appear only on a 429 response — Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A successful response carries none of them, so you cannot track your remaining budget from the headers; count your own calls.
Endpoints
These five are the complete set of documented endpoints. Other routes exist under /api to serve the application, but they are internal, undocumented and free to change without notice — treat anything not listed here as unsupported.
/api/documents/pdfSessionGenerate one document covering one or more artworks.
Returns the finished document as HTML (Content-Type: text/html), not JSON and not a PDF binary — open it and print, or save as PDF from the print dialog. Returns 402 with code "limit_reached" when the account has spent its monthly document allowance, and 400 on an unknown document_type, theme or image_data that is not a base64 PNG, JPEG or WebP data URI.
{
"document_type": "certificate" | "customs" | "brochure" |
"bill-of-sale" | "condition-report" | "provenance" | ...,
"gallery": { "name": "string", "contact_email": "string",
"address": "string", "artist": "string" },
"artworks": [
{
"title": "string",
"artist": "string",
"year": "string",
"medium": "string",
"dimensions": "string",
"price": 18500,
"image_data": "data:image/jpeg;base64,..."
}
],
"format": "a4" | "letter" | "a3" | "a5",
"theme": "classic" | "modern" | "formal" | "luxury" |
"editorial" | "nordic" | "heritage" | "couture",
"shipment": { "destination_country": "CH", "carrier": "string" }
}HTTP/1.1 200 OK Content-Type: text/html; charset=utf-8 Content-Disposition: inline; filename="certificate-1754006400000.html" <!DOCTYPE html><html>… the rendered document …</html>
/api/documentsSessionList the documents already generated on this account.
Paginated. `type` filters on document_type. Newest first.
?page=1&per_page=20&type=certificate
{
"documents": [
{
"id": "uuid",
"document_type": "certificate",
"gallery_name": "string",
"artist_name": "string",
"artworks": [ ... ],
"created_at": "2026-05-06T19:00:00Z",
"storage_url": "string",
"download_count": 0
}
],
"total": 42,
"page": 1,
"per_page": 20
}/api/artworksSessionList every artwork saved to the account library.
Returns the full library in one response, most recently updated first. There is no pagination or search parameter on this handler.
{ "artworks": [ { "id": "uuid", "title": "string", ... } ] }/api/artworksSessionSave an artwork to the account library.
`title` and `artist` are required. The library is not available on Essentials — that plan returns 403, as does an account already at its library ceiling (50 on Professional, 200 on Studio).
{
"title": "string",
"artist": "string",
"year": "string",
"medium": "string",
"dimensions": "string",
"price": 18500,
"origin_country": "US",
"hs_code": "string",
"image_url": "string",
"notes": "string"
}{ "artwork": { "id": "uuid", ... } }/api/billing/usageSessionCurrent tier, documents used this calendar month, and limits.
Unlimited allowances serialize as null rather than as a number — an unlimited plan is not a very large plan.
{
"tier": "professional",
"usage": {
"docs_this_month": 12,
"docs_limit": null,
"artworks_total": 8,
"artworks_limit": 50
}
}Webhooks
A subscription can be created today under Dashboard → Settings → Webhooks. You supply an endpoint URL and choose from the ten event names below; the platform issues a signing secret with a whsec_ prefix and will send a signed test delivery to your endpoint so you can verify the HMAC-SHA256 signature end to end.
What is not wired up yet is automatic dispatch. Generating a document or saving an artwork does not currently fire the corresponding event — the dispatcher exists and delivers, but nothing in the product calls it outside the test path. Build against these names if you like; do not build a workflow that assumes deliveries will arrive on their own.
artwork.createdAn artwork is added to the libraryartwork.updatedAn artwork record is editedartwork.deletedAn artwork is removed from the librarydocument.generatedA document is generateddocument.downloadedA stored document is retrievedverification.checkedA verification page is readorder.createdAn order is createdorder.shippedAn order is marked shippedpayment.receivedA payment settlesteam.member_addedA team member is addedWaiting on something specific?
Key-based authentication and automatic webhook dispatch are the two pieces between this reference and a usable integration. Tell us which system you want to wire this into and what you need it to do — that is what decides the order they are built in.