> ## Documentation Index
> Fetch the complete documentation index at: https://docs.betterumami.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Install and use the @umami/api-client TypeScript package to call every Betterumami REST endpoint from Node.js with complete type safety.

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.

<Note>
  **Requirements:** Node.js 18.18 or newer.
</Note>

## Setup

<Steps>
  <Step title="Install the package">
    Add `@umami/api-client` to your project using your preferred package manager.

    <CodeGroup>
      ```bash npm theme={null}
      npm install @umami/api-client
      ```

      ```bash yarn theme={null}
      yarn add @umami/api-client
      ```

      ```bash pnpm theme={null}
      pnpm add @umami/api-client
      ```
    </CodeGroup>
  </Step>

  <Step title="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**

    ```dotenv theme={null}
    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**

    ```dotenv theme={null}
    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. |
  </Step>

  <Step title="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.

    ```js theme={null}
    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:

    ```typescript theme={null}
    {
      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
    }
    ```
  </Step>
</Steps>

## 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` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.