Umami is a privacy-first web and product analytics platform. Traffic, campaigns, behavior, conversions, and revenue in one place. No cookies, no surveillance, self-hosted or in the cloud.
OpenAPI contracts
Umami generates public/openapi.json for every App Router API handler. It statically infers a
baseline contract from route source and replaces that baseline with a colocated, Zod-backed
contract wherever one exists.
public/openapi.json is an ignored build artifact and must not be committed. Generate it locally
with pnpm openapi:generate before running checks or generating the API client.
Commands
pnpm openapi:generateregenerates the public OpenAPI document.pnpm openapi:contractsrefreshes source-controlled contracts for routes without a curatedcontract.tsmodule.pnpm openapi:checkvalidates contract alignment and checks that the generated file is current.pnpm openapi:check --explicitalso fails while any non-OPTIONS API route lacks a hand-authored contract.pnpm openapi:check --verboselists operations that still use inferred contracts.
The normal and Docker builds run the generator before the Next.js build. CI generates the artifact and runs the check before tests and build steps.
Adding an operation
Run pnpm openapi:contracts to create a contract.generated.ts next to every route that does not
have a curated contract. Generated contracts use the route's Zod request validation and TypeScript
response types. They are checked in so operation IDs and client-facing schemas remain stable.
For examples or runtime-shared Zod response models, replace the generated
module with a contract.ts that exports an operations array. Define request and response shapes
with Zod, and import the same request schema into the route handler for parseRequest validation.
Contract modules must remain safe to import from a build script. They must not import route handlers, database clients, Redis clients, or modules with environment-dependent side effects.
The generated artifact contains all audiences. Every operation declares one of:
publicoperations are intended for API consumers.internaloperations support the Umami application or deployment.collectoperations identify tracker ingestion APIs.
Route paths and HTTP methods are discovered independently from src/app/api/**/route.ts. The check
requires all discovered non-OPTIONS operations in the artifact and rejects duplicate contracts,
duplicate operation IDs, orphaned contracts, and mismatched dynamic path parameters.
New operations are initially marked with x-umami-contract: inferred and their source file. The
inference layer extracts path parameters, Zod request fields, authentication, typed response bodies,
response status helpers, and response media types without importing route modules. Running
pnpm openapi:contracts snapshots that behavior into an explicit contract. Curated contract.ts
modules remain the way to add examples and custom operation IDs.
Summaries and descriptions
Edit src/openapi/operation-descriptions.ts to maintain plain-language documentation without
maintaining a full contract. This file is hand-written, committed, and never overwritten by
either OpenAPI generator. Keys combine the uppercase HTTP method and the OpenAPI path:
'POST /api/links/{linkId}/shares': {
summary: 'Create a share for a link',
description: 'Creates a named share for the specified link with optional parameters.',
},
The document builder applies these fields after loading explicit and inferred contracts. A summary is required for each entry; the longer description is optional. Omitted fields retain their contract values, and operations without an entry retain their existing documentation. Schemas and operation IDs continue to come from the contracts.
Run pnpm generate:api after editing to refresh the OpenAPI document and API client. Generation and
pnpm openapi:check reject entries that do not match a discovered route and method. Entries are
optional, so documentation can be improved incrementally.
Field documentation lives in src/openapi/field-descriptions.ts. The document builder fills missing
query/path parameter and request/response property descriptions after converting contracts to
OpenAPI, including nested schemas and shared components. Existing contract descriptions take
precedence. Keep shared wording limited to fields with consistent meanings; use endpoint-specific
wording for fields such as the dashboard's parameters. Unknown fields are left undocumented
rather than given an automatically generated label. Examples and schema validation rules are not
modified. Run pnpm generate:api after editing this file as well.
Operation IDs
Operation IDs are public: they become method names in @umami/api-client. Routes with a curated
contract.ts set operationId directly. For inferred contracts, src/openapi/operation-ids.ts
overrides the mechanical path-based name (getWebsitesWebsiteIdStats -> getWebsiteStats).
Never rename an operation ID without a migration note for the client.
Generated API client
pnpm generate:api regenerates the OpenAPI document and packages/api-client/src/generated.
pnpm check:api:client fails in CI when the generated client is stale.