A small JSON api, documented to the byte

Base URLs

Two authentication mechanisms

The account surface (projects, assets, key management) uses a JWT sent as Authorization: Bearer <token>. Tokens come from register/login and live for 7 days. The public v1 surface uses a developer key sent as x-api-key: pf_…. Keys are issued from the account surface and never expire until revoked.

Quickstart: zero to a keyed request

This full flow runs verbatim against the Docker deployment (see deployment) — substitute your domain for http://localhost. On a bare-metal dev api, drop the /api prefix and use http://localhost:4000 instead. Each step shows the real response shape:

curl -X POST http://localhost/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@example.com","password":"s3cure-passphrase","name":"Dev"}'

{
  "user": {
    "id": "cml4k9x2b0000jq8f3h5a1d2e",
    "email": "dev@example.com",
    "name": "Dev",
    "createdAt": "2026-08-06T10:15:30.000Z"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"
}

curl -X POST http://localhost/api/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"

{
  "apiKey": {
    "id": "cml4ka7cd0001jq8f9b2c4e6a",
    "userId": "cml4k9x2b0000jq8f3h5a1d2e",
    "key": "pf_9f2c4e6a8b0d1f3e5a7c9b8d7e6f5a4b3c2d1e0f9a8b7c6d",
    "createdAt": "2026-08-06T10:16:02.000Z"
  }
}

curl http://localhost/api/v1/templates \
  -H "x-api-key: pf_9f2c4e6a8b0d1f3e5a7c9b8d7e6f5a4b3c2d1e0f9a8b7c6d"

{
  "templates": [ { "id": "mailer-box", "name": "Mailer Box", … }, … ],
  "total": 11,
  "categories": [ { "id": "folding-cartons", "label": "Folding Cartons", "count": 1 }, … ]
}

The error contract: ApiError

Every failure — validation, auth, not-found, oversized uploads, unexpected server errors — returns the same JSON shape. A single error handler normalizes Fastify, ajv, JWT, multipart, and Prisma errors into it:

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Project not found."
}

Notes for AI agents

This api is built to be consumed programmatically, including by LLM-driven agents:

• JSON-first. Every request and response body is JSON, except POST /assets which is multipart/form-data by necessity. Dates are ISO 8601 strings; ids are cuid strings.
• Machine-readable errors. Always the ApiError shape above — branch on statusCode, display message, never regex the body.
• Strict schemas. Bodies and query strings reject unknown fields (additionalProperties: false). Send exactly the documented fields.
• Small, stable catalog. /v1/templates returns all 11 templates in one call — no pagination to choreograph.
• Typed contract. Response shapes are the exported types of @pacfully/shared (User, Project, Asset, ApiKey, ParametricTemplate, ApiError) — import them if you are in TypeScript, mirror them otherwise.

Endpoint index

Continue to auth endpoints →