Skip to main content

​
Create Pixel

Create a new tracking pixel for monitoring events where JavaScript tracking isn’t available, such as email opens.

​
Endpoint

POST /api/pixels

​
Headers

​
Authorization
string
required
Bearer token for authentication

​
Request Body

​
name
string
required
Pixel name (max 100 characters)
​
slug
string
required
Unique pixel slug (max 100 characters). Must be unique across all pixels.
​
teamId
string
Team UUID if creating a team pixel. Omit for personal pixel.
​
id
string
Optional custom UUID for the pixel. Generated automatically if not provided.

​
Response

​
id
string
Pixel UUID
​
name
string
Pixel name
​
slug
string
Pixel slug
​
userId
string
Owner user UUID (null for team pixels)
​
teamId
string
Team UUID (null for personal pixels)
​
createdAt
string
ISO 8601 timestamp of creation

​
Example Request

curl -X POST "https://your-umami-instance.com/api/pixels" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Email Campaign Tracker",
    "slug": "email-campaign"
  }'

​
Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Email Campaign Tracker",
  "slug": "email-campaign",
  "userId": "660e8400-e29b-41d4-a716-446655440001",
  "teamId": null,
  "createdAt": "2024-03-15T09:20:00.000Z"
}

​
Creating a Team Pixel

To create a pixel owned by a team, include the teamId parameter:
curl
curl -X POST "https://your-umami-instance.com/api/pixels" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Newsletter Tracker",
    "slug": "newsletter",
    "teamId": "880e8400-e29b-41d4-a716-446655440003"
  }'

​
Using the Pixel

After creating a pixel, you can use it in HTML by embedding it as an image: 
<img src="https://your-umami-instance.com/api/send?slug=email-campaign" width="1" height="1" alt="" />
You must have permission to create websites for the team. The slug must be unique across all pixels in the system.

Build docs developers (and LLMs) love

Get started for freeTalk to us