Clients
API client
Overview
Umami API Client is built in TypeScript and contains functions to call every API endpoint available in Umami.

Requirements
Node.js version 18.18 or newer
Installation
npm install @umami/api-client

Configure
The following environment variables are required to call your own API.

UMAMI_API_CLIENT_USER_ID
UMAMI_API_CLIENT_SECRET
UMAMI_API_CLIENT_ENDPOINT

To access Umami Cloud, these environment variables are required.

UMAMI_API_KEY
UMAMI_API_CLIENT_ENDPOINT

More details on accessing Umami Cloud can be found under API key.

Usage
Import the configured api-client and query using the available class methods.

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

const client = getClient();

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

The result will come back in the following format.

{
  ok: boolean;
  status: number;
  data?: T;
  error?: any;
}

API Client function mapping
Me
getMe() ⇒ GET /me
updateMyPassword(data) ⇒ POST /me/password
getMyWebsites() ⇒ GET /me/websites

Users
getUsers() ⇒ GET /users
createUser(data) ⇒ POST /users
getUser(id) ⇒ GET /users/{id}
updateUser(id, data) ⇒ POST /users/{id}
deleteUser(id) ⇒ DEL /users/{id}
getUserWebsites(id) ⇒ GET /users/{id}/websites
getUserUsage(id, data) ⇒ GET /users/{id}/usage

Teams
getTeams() ⇒ GET /teams
createTeam(data) ⇒ POST /teams
joinTeam(data) ⇒ POST /teams/join
getTeam(id) ⇒ GET /teams/{id}
updateTeam(id) ⇒ POST /teams/{id}
deleteTeam(id) ⇒ DEL /teams/{id}
getTeamUsers(id) ⇒ GET /teams/{id}/users
deleteTeamUser(teamId, userId): DEL /teams/{teamId}/users/{userId}
getTeamWebsites(id) ⇒ GET /teams/{id}/websites
createTeamWebsites(id, data) ⇒ GET /teams/{id}/websites
deleteTeamWebsite(teamId, websiteId) ⇒ DEL /teams/{teamId}/websites/{websiteId}

Websites
getWebsites() ⇒ GET /websites
createWebsite(data) ⇒ POST /websites
getWebsite(id) ⇒ GET /websites/{id}
updateWebsite(id, data) ⇒ POST /websites/{id}
deleteWebsite(id) ⇒ DEL /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
resetWebsite(id) ⇒ GET /websites/{id}/reset
getWebsiteStats(id, data) ⇒ GET /websites/{id}/stats

Event Data
getEventDataEvents(id, data) ⇒ GET /event-data/events
getEventDataFields(id, data) ⇒ GET /event-data/fields
getEventDataStats(id, data) ⇒ GET /event-data/stats

Environment Variables
UMAMI_API_CLIENT_USER_ID = <user uuid>

The USER_ID of the User performing the API calls. Permission restrictions will apply based on application settings.

UMAMI_API_CLIENT_SECRET = <random string>

A random string used to generate unique values. This needs to match the APP_SECRET used in the Umami application.

UMAMI_API_CLIENT_ENDPOINT = <API endpoint>

The endpoint of your Umami API. Example: https://{yourserver}/api/

UMAMI_API_KEY = <API Key string>

A unique string provided by Umami Cloud.


Clients
Node Client
Overview
The Umami node client allows you to send data to Umami on the server side.

Installation
npm install @umami/node

Usage
import umami from '@umami/node';

umami.init({
  websiteId: '50429a93-8479-4073-be80-d5d29c09c2ec', // Your website id
  hostUrl: 'https://umami.mywebsite.com', // URL to your Umami instance
});

umami.track({ url: '/home' });

If using Umami Cloud, you can use https://cloud.umami.is as the host URL.

The properties you can send using the .track function are:

hostname: Hostname of server
language: Client language (eg. en-US)
referrer: Page referrer
screen: Screen dimensions (eg. 1920x1080)
title: Page title
url: Page url
name: Event name (for custom events)
data: Event data properties