Typed TypeScript client for the Umami API. Every method is generated from Umami's OpenAPI contract (public/openapi.json in the main repository), so the client can never drift from the server.

pnpm add @umami/api-client

Usage

import { UmamiClient } from '@umami/api-client';

// Umami Cloud
const umami = new UmamiClient({ apiKey: process.env.UMAMI_API_KEY });

// Self-hosted
const umami = new UmamiClient({
  baseUrl: 'https://analytics.example.com/api',
  token: process.env.UMAMI_API_TOKEN, // API key (umami_…) or login token
});

const websites = await umami.listWebsites();

const stats = await umami.getWebsiteStats({
  websiteId,
  startAt: Date.now() - 7 * 24 * 60 * 60 * 1000,
  endAt: Date.now(),
});

const pages = await umami.getWebsiteMetrics({ websiteId, startAt, endAt, type: 'path', limit: 10 });

Every method takes one object that merges path parameters, query parameters and the request body. Method names are the OpenAPI operationIds; hover in your editor for the parameter and response types, or import OperationInput<'getWebsiteStats'> / OperationOutput<'…'>.

Options

Option	Description
`baseUrl`	API root. Defaults to `https://api.umami.is/v1`. Self-hosted: `https://your-umami/api`.
`token`	Bearer token: login token or self-hosted API key.
`apiKey`	Umami Cloud API key (sent as `x-umami-api-key`; also sent as a bearer token when `token` is not provided).
`headers`	Extra headers for every request.
`fetch`	Custom `fetch` (tests, other runtimes, in-process dispatch).
`timeout`	Per-request timeout in milliseconds.

Errors

Non-2xx responses throw UmamiApiError with status, code (unauthorized, forbidden, not-found, bad-request, …), message and the parsed body.

import { isUmamiApiError } from '@umami/api-client';

try {
  await umami.getWebsite({ websiteId });
} catch (error) {
  if (isUmamiApiError(error) && error.isNotFound) {
    // …
  }
}

Escape hatch

umami.call('operationId', input) invokes any operation by ID; operations exports the full table of methods, paths and parameters.

Regenerating

From the Umami repository root:

pnpm generate:api      # public/openapi.json → packages/api-client/src/generated
pnpm check:api:client  # CI: fail if generated files are stale

See MIGRATION.md if you are upgrading from the previous hand-written client.