@umami/api-client

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.