API Overview
Relevant source files
The following files were used as context for generating this wiki page:The Umami application exposes a comprehensive RESTful API for managing its core resources, such as users, teams, and websites. This API is the primary interface for the frontend application and can also be used for programmatic access and integration with external systems. The API is built using Next.js API Routes and is responsible for both resource management (CRUD operations) and high-volume analytics data collection via a separate tracking endpoint.
All management endpoints are located under the /api/ path and require authentication. Data collection is handled by a dedicated endpoint, typically /api/send, which is designed for high-throughput, asynchronous event processing.
Architecture and Configuration
The API is implemented as a series of Next.js API Routes, where files within the src/app/api/ directory map to API endpoints. The core routing, headers, and rewrite rules are defined in the next.config.ts file.
Sources: next.config.ts, src/app/api/links/route.ts
Request Flow and Headers
All requests to /api/:path* are configured with specific HTTP headers to handle Cross-Origin Resource Sharing (CORS) and caching. This allows the API to be accessed from different domains.
The diagram below illustrates the general flow of an API request.
This diagram shows how a client request is routed by the Next.js server to the appropriate API handler, with CORS headers being applied before the response is sent back.
Sources: next.config.ts:80-83
The following CORS headers are applied to all API routes:
| Header | Value | Purpose |
|---|---|---|
Access-Control-Allow-Origin | * | Allows requests from any origin. |
Access-Control-Allow-Headers | * | Allows any headers to be sent in the request. |
Access-Control-Allow-Methods | GET, DELETE, POST, PUT | Specifies the allowed HTTP methods. |
Access-Control-Max-Age | 86400 (or CORS_MAX_AGE env var) | Caches the preflight response for 24 hours. |
Cache-Control | no-cache | Prevents caching of API responses. |
Sources: next.config.ts:68-78
Authentication
API requests are authenticated using a JSON Web Token (JWT) provided as a Bearer token in the Authorization header. The frontend client retrieves this token and includes it in every request via the useApi hook.
// src/components/hooks/useApi.ts:17-20
const defaultHeaders = {
authorization: `Bearer ${getClientAuthToken()}`,
[SHARE_TOKEN_HEADER]: shareToken?.token,
};
Sources: src/components/hooks/useApi.ts:17-20, cypress/e2e/api-user.cy.ts:15
The following sequence diagram shows the authentication flow.
This diagram shows the process of logging in to get a token, which is then used for subsequent authenticated API calls.
Sources: cypress/support/e2e.ts:12-24
Frontend API Client
The frontend interacts with the API through the useApi custom hook. This hook abstracts away the details of making HTTP requests, including URL construction and adding necessary authentication headers.
Sources: src/components/hooks/useApi.ts
useApi Hook
The useApi hook provides get, post, put, and del methods. It automatically prepends the API base path (/api) to URLs and includes the Authorization and x-umami-share-token headers in every request. It also handles the response, resolving the data on success or rejecting with a formatted error on failure.
The diagram below shows how a frontend component uses the useApi hook to fetch data.
This sequence illustrates a frontend component calling the get method from the useApi hook, which then handles the full lifecycle of the API request.
Sources: src/components/hooks/useApi.ts:28-33
Core API Endpoints
The API provides a set of RESTful endpoints for managing core entities. The functionality of these endpoints is demonstrated in the Cypress end-to-end tests.
Users API
The User API manages user accounts, roles, and their associated teams and websites.
Sources: cypress/e2e/api-user.cy.ts
| Method | Endpoint | Description |
|---|---|---|
POST | /api/users | Creates a new user. |
GET | /api/admin/users | Returns all users (Admin access required). |
GET | /api/users/{userId} | Retrieves a specific user by their ID. |
POST | /api/users/{userId} | Updates a specific user's details (e.g., role). |
DELETE | /api/users/{userId} | Deletes a user. |
GET | /api/users/{userId}/websites | Gets all websites that belong to a user. |
GET | /api/users/{userId}/teams | Gets all teams that belong to a user. |
Sources: cypress/e2e/api-user.cy.ts:10-109
Teams API
The Teams API manages teams, team membership, and team-owned websites.
Sources: cypress/e2e/api-team.cy.ts
| Method | Endpoint | Description |
|---|---|---|
POST | /api/teams | Creates a new team. |
GET | /api/teams/{teamId} | Retrieves a specific team by its ID. |
POST | /api/teams/{teamId} | Updates a team's details (e.g., name). |
DELETE | /api/teams/{teamId} | Deletes a team. |
GET | /api/teams/{teamId}/users | Gets all users belonging to a team. |
POST | /api/teams/{teamId}/users | Adds a user to a team with a specific role. |
DELETE | /api/teams/{teamId}/users/{userId} | Removes a user from a team. |
GET | /api/teams/{teamId}/websites | Gets all websites belonging to a team. |
Sources: cypress/e2e/api-team.cy.ts:31-164
Websites API
The Websites API manages the websites being tracked by Umami.
Sources: cypress/e2e/api-website.cy.ts
| Method | Endpoint | Description |
|---|---|---|
POST | /api/websites | Creates a new website for a user or a team. Can accept a pre-defined UUID. |
GET | /api/websites | Returns all websites the authenticated user has access to. |
GET | /api/websites/{websiteId} | Retrieves a specific website by its ID. |
POST | /api/websites/{websiteId} | Updates a website's details (e.g., name, domain, shareId). |
POST | /api/websites/{websiteId}/reset | Resets a website, removing all its collected data. |
DELETE | /api/websites/{websiteId} | Deletes a website. |
Sources: cypress/e2e/api-website.cy.ts:29-178
Data Collection API
Separate from the management API, the data collection API is designed to receive high-volume analytics events from the tracker script.
Sources: src/tracker/index.js, next.config.ts
Tracker Script
The tracker script (/script.js) is embedded on tracked websites. It collects pageviews and custom events and sends them to the collection endpoint. The script can be configured via data-* attributes on the script tag.
The following diagram shows the data collection flow.
This diagram shows how the tracker script, once loaded, sends pageview and custom event data to the collection endpoint on the Umami server.
Sources: src/tracker/index.js:154-162, src/app/(main)/console/[websiteId]/TestConsolePage.tsx:10-100
The collection endpoint is defined by the COLLECT_API_ENDPOINT environment variable, which can be used to rewrite a custom path (e.g., /my-stats) to the actual handler at /api/send. This is configured in next.config.ts.
Sources: next.config.ts:91-98