Betterumami API Client Reference (@umami/api-client)

The @umami/api-client package is a fully-typed TypeScript client that wraps every Betterumami REST endpoint in a simple function call. Rather than constructing raw HTTP requests, you import a pre-configured client, call the method you need, and get back a typed response object — no boilerplate required. The client works with both Betterumami Cloud and self-hosted instances.

Requirements: Node.js 18.18 or newer.

Setup

Install the package

Add @umami/api-client to your project using your preferred package manager.

npm install @umami/api-client

yarn add @umami/api-client

pnpm add @umami/api-client

Configure environment variables

The client reads its credentials and target endpoint from environment variables. Which variables you set depends on whether you are using Betterumami Cloud or a self-hosted instance.Betterumami Cloud

UMAMI_API_KEY=<your Cloud API key>
UMAMI_API_CLIENT_ENDPOINT=https://api.umami.is/v1

Variable	Description
`UMAMI_API_KEY`	The API key generated in your Betterumami Cloud account settings.
`UMAMI_API_CLIENT_ENDPOINT`	The Cloud API base URL. Always `https://api.umami.is/v1` for Cloud.

Self-hosted instance

UMAMI_API_CLIENT_USER_ID=<user UUID>
UMAMI_API_CLIENT_SECRET=<random string>
UMAMI_API_CLIENT_ENDPOINT=https://your-instance.example.com/api/

Variable	Description
`UMAMI_API_CLIENT_USER_ID`	The UUID of the user performing API calls. Permission restrictions apply based on that user’s role.
`UMAMI_API_CLIENT_SECRET`	A random string used to generate unique tokens. Must match the secret configured in your Betterumami instance.
`UMAMI_API_CLIENT_ENDPOINT`	The full URL to your self-hosted API, including the trailing `/api/` path.

Call the API

Import getClient from the package, create a client instance, and call any available method. Every method is async and returns a consistent response shape.

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

const client = getClient();

const { ok, data, status, error } = await client.getWebsites();

Every response follows this TypeScript shape, where T is the typed payload for the specific endpoint:

{
  ok: boolean;     // true when the request succeeded (2xx status)
  status: number;  // HTTP status code
  data?: T;        // Typed response payload, present when ok is true
  error?: any;     // Error detail, present when ok is false
}

Function reference

Me

These functions operate on the currently authenticated user.

Function	Method	Endpoint
`getMe()`	`GET`	`/me`
`updateMyPassword(data)`	`POST`	`/me/password`
`getMyWebsites()`	`GET`	`/me/websites`
`getMyApiKeys()`	`GET`	`/me/api-keys`
`createMyApiKey(data)`	`POST`	`/me/api-keys`
`deleteMyApiKey(id)`	`DELETE`	`/me/api-keys/{id}`
`getMyTeams()`	`GET`	`/me/teams`

Websites

These functions let you list, create, update, delete, and query analytics data for websites.

Function	Method	Endpoint
`getWebsites()`	`GET`	`/websites`
`createWebsite(data)`	`POST`	`/websites`
`getWebsite(id)`	`GET`	`/websites/{id}`
`updateWebsite(id, data)`	`POST`	`/websites/{id}`
`deleteWebsite(id)`	`DELETE`	`/websites/{id}`
`getWebsiteActive(id)`	`GET`	`/websites/{id}/active`
`getWebsiteEvents(id, data)`	`GET`	`/websites/{id}/events`
`getWebsiteMetrics(id, data)`	`GET`	`/websites/{id}/metrics`
`getWebsitePageviews(id, data)`	`GET`	`/websites/{id}/pageviews`
`getWebsiteStats(id, data)`	`GET`	`/websites/{id}/stats`
`resetWebsite(id)`	`POST`	`/websites/{id}/reset`

Teams

These functions manage teams and their associated users and websites.

Function	Method	Endpoint
`getTeams()`	`GET`	`/teams`
`createTeam(data)`	`POST`	`/teams`
`joinTeam(data)`	`POST`	`/teams/join`
`getTeam(id)`	`GET`	`/teams/{id}`
`updateTeam(id, data)`	`POST`	`/teams/{id}`
`deleteTeam(id)`	`DELETE`	`/teams/{id}`
`getTeamUsers(id)`	`GET`	`/teams/{id}/users`
`deleteTeamUser(teamId, userId)`	`DELETE`	`/teams/{teamId}/users/{userId}`
`getTeamWebsites(id)`	`GET`	`/teams/{id}/websites`
`createTeamWebsites(id, data)`	`POST`	`/teams/{id}/websites`
`deleteTeamWebsite(teamId, websiteId)`	`DELETE`	`/teams/{teamId}/websites/{websiteId}`

Event data

These functions query custom event data collected by the tracking script.

Function	Method	Endpoint
`getEventDataEvents(id, data)`	`GET`	`/event-data/events`
`getEventDataFields(id, data)`	`GET`	`/event-data/fields`
`getEventDataStats(id, data)`	`GET`	`/event-data/stats`

Overview

Websites

Stats & Events

Node Client

Betterumami API Client Reference (@umami/api-client)

Setup

Function reference

Me

Websites

Teams

Event data

​Setup

​Function reference

​Me

​Websites

​Teams

​Event data

Setup

Function reference

Me

Websites

Teams

Event data