Developers

Build with the catalog API.

A typed, read-mostly API over the catalog. Search runs on SQLite FTS5, responses are validated with Zod, and saved items are scoped to an httpOnly anonymous session.

OpenAPI 3.1 spec Health check

Endpoints

GET/api/assets

Search the catalog with full-text relevance, media type, orientation and sorting.

GET/api/suggest

Prefix suggestions for the search combobox.

GET/api/saved

List saved asset ids for the anonymous session.

POST/api/saved

Save or remove an asset. Creates the session cookie on first write.

GET/api/health

Readiness probe with catalog size and process uptime.

GET/api/openapi

This contract as an OpenAPI 3.1 document.

Quickstart

Search

curl -s "http://localhost:3000/api/assets?q=autumn&type=image&pageSize=6" \
  -H "accept: application/json"

{
  "items": [
    {
      "id": "woman",
      "slug": "portrait-in-autumn-light",
      "title": "Portrait in autumn light",
      "author": "Elise Varga",
      "type": "image",
      "tags": ["autumn", "people"],
      "width": 900,
      "height": 1200,
      "premium": true
    }
  ],
  "total": 8,
  "page": 1,
  "pageSize": 6,
  "totalPages": 2
}

Saved items

The first write creates a signed, httpOnly session cookie. Store it and send it with subsequent requests. No API key is required for this demo.

curl -s -X POST "http://localhost:3000/api/saved" \
  -H "content-type: application/json" \
  -b cookies.txt -c cookies.txt \
  -d '{"assetId":"arch","action":"save"}'

Search parameters

Name	Type	Default	Notes
`q`	string	—	Quoted FTS5 prefix tokens; operators are stripped.
`type`	enum	`all`	image, vector, video, music, editorial, sound.
`orientation`	enum	`all`	horizontal, vertical, square.
`sort`	enum	`relevance`	relevance, popular, newest.
`page`	integer	`1`	1-based; capped at 100.
`pageSize`	integer	`24`	1–48.

Security notes

Zod validates every query and mutation; invalid input returns 400 with an issues array.
FTS5 input is tokenised and quoted before it reaches SQL — no raw match syntax.
Saved items use an httpOnly, SameSite=Lax cookie and are never exposed to client JavaScript.
Production ships CSP, HSTS, nosniff, frame-deny and a restrictive permissions policy.