API Reference

The Neemias API follows the contract defined below. The OpenAPI 3.1 specification is automatically generated from the code and validated against the Workers routes.

Documents

Document	Description
API Contract	Complete textual contract — endpoints, auth, idempotency, errors, conflicts
OpenAPI 3.1 Specification	Guia da especificação OpenAPI — como consultar, regenerar e usar no Swagger Editor
OpenAPI 3.1 Spec (JSON)	Spec automatically generated via pnpm docs:openapi. 25 endpoints, 29 schemas
TypeDoc	Documentação de API gerada automaticamente via TypeDoc — schemas, permissões, workers

Regenerating the spec

pnpm docs:openapi

The script:

1. Reads workers/src/router.ts and extracts all 25 routes
2. Validates that each route has a registry entry (scripts/openapi-registry.ts)
3. Converts Zod schemas to JSON Schema via zod-to-json-schema
4. Writes docs/reference/api/openapi.json and docs/public/reference/api/openapi.json

If a new route is not documented in the registry, pnpm docs:build fails.

Consuming the API

• Base URL (production): https://api.neemias.app/api/v1
• Base URL (local): http://localhost:8788/api/v1
• Authentication: Bearer token JWT obtained via POST /auth/login