API Reference

All API routes live under /api/v1.

Core endpoints

• POST /api/v1/convert
• GET /api/v1/preview
• POST /api/v1/palettes/extract
• POST /api/v1/batch
• GET /api/v1/batch/:jobId
• GET /api/v1/usage

/api/v1/preview and /api/v1/convert both accept an optional projectId query parameter. When provided, PaletteForge loads recent project verdicts and returns a critic-policy profile alongside the normal recommendation and quality payloads, making project memory an explicit part of the API contract instead of an editor-only concern.

Those same project-scoped flows now also return trajectoryPlan, which projects the next one to three intervention steps from the live queue. The planner exposes per-path projected quality, risk, confidence, and per-step notes so API consumers can replay the recommended opener without re-deriving the route client-side.

Authentication

Mutation routes accept either a valid session or an API key in the Authorization: Bearer pf_xxx header.

Server-side plan enforcement applies to authenticated API traffic:

• API keys must include the required route permissions.
• Upload payloads respect the active plan upload cap.
• Conversion and analysis quotas are enforced per billing cycle.
• Export routes only allow formats included in the active plan.