Endpoints

The API speaks JSON, follows REST conventions, and returns standard HTTP status codes. Auth required for everything except the /library reads.

Library

GET /api/library/brands
GET /api/library/brands/:slug

List or fetch curated brand entries. No auth required. Returns { brands: [...] } for the index, { brand: {...} } for the detail.

Reviews

GET    /api/library/:slug/reviews
POST   /api/library/:slug/reviews
DELETE /api/library/:slug/reviews

GET returns { data: { histogram, reviews, myReview }, viewer }. POST + DELETE require auth; both upsert/delete the caller's own review.

Jobs (URL extraction)

POST /api/jobs
GET  /api/jobs/:id

POST enqueues a job with shape { type: 'extract_design_system', input: { url } }. Response is { success: true, jobId } (202) or { error, ...} (400/401/429/503). GET returns the row for the requesting user only — 404 if you don't own it.

Job rows include status, progress (jsonb of { stage, percent, message }), confidence (high / medium / low), output (the DesignSystem when status='succeeded'), and error.

Bookmarks

GET    /api/bookmarks
POST   /api/bookmarks/:slug
DELETE /api/bookmarks/:slug

Auth required. POST creates idempotently (duplicate POST returns 201 without inserting). DELETE removes silently when not present.

Account

GET    /api/me
GET    /api/me/export
DELETE /api/me

/me/export returns a JSON download of all your data (GDPR right of access). DELETE removes your account and cascades to bookmarks, reviews, sessions, and saved designs. All three require auth.

Auth

POST /api/auth/sign-up/email
POST /api/auth/sign-in/email
GET  /api/auth/sign-in/social/:provider
POST /api/auth/sign-out

Email + OAuth flows. Owned by better-auth; see their docs for the full surface.

Response envelope

All endpoints follow:

{ "success": true, "data": ... }
{ "success": false, "error": "human-readable message", "details": {...} }

except auth which uses better-auth's native shape ({ token, user }).