API Reference

Interactive docs (Scalar)

When the API dev server is running (pnpm dev:api), open:

• Scalar UI: /scalar — interactive API reference
• OpenAPI JSON: /doc — machine-readable OpenAPI 3.0 spec

Example (local Wrangler default):

http://localhost:8787/scalar
http://localhost:8787/doc

Routes

Health and docs

Method	Path	Description
GET	/health	Health check with Zod-validated JSON response
GET	/doc	OpenAPI 3.0 JSON spec
GET	/scalar	Scalar API reference UI

Session

Method	Path	Auth	Description
GET	/api/me	Optional	Current user session or null

Better Auth email/password routes are served at /api/auth/* (not part of the OpenAPI spec).

Creator quizzes (authenticated)

Method	Path	Description
GET	/api/quizzes	List quizzes for the signed-in user
POST	/api/quizzes	Create a draft quiz
GET	/api/quizzes/{id}	Fetch quiz detail (owner only)
PATCH	/api/quizzes/{id}	Update a draft quiz
DELETE	/api/quizzes/{id}	Delete a quiz
POST	/api/quizzes/{id}/publish	Publish draft → 6-char permalink

Published quizzes cannot be edited (PATCH returns 409).

Public quizzes (anonymous)

Method	Path	Description
GET	/api/public/quizzes/{permalink}	Load published quiz (answers redacted)
POST	/api/public/quizzes/{permalink}/submit	Submit answers; returns score

Shared schemas

Request and response schemas live in @quiz-builder/types with .openapi() metadata. The API registers routes via createRoute and OpenAPIHono.openapi() from @hono/zod-openapi.

Example schema (simplified):

import { z } from "@hono/zod-openapi";

export const HealthResponseSchema = z.object({ status: z.literal("ok") }).openapi("HealthResponse");

New endpoints should follow the same pattern: define the schema in packages/types, create a route in apps/api, and Scalar will pick it up automatically from /doc.

Production URLs

Set deployed API base URLs in CI/CD variables and link them here once Cloudflare Workers deploy jobs are configured.