Skip to main content

​
Send Event

Track pageviews, custom events, and user identification data. This is the primary endpoint for collecting analytics data.
This endpoint does not require authentication via Bearer token. It uses website IDs and optional tracking IDs for identification.

​
Endpoint

POST /api/send

​
Request Body

​
type
string
required
Event type. Must be one of:
  • event - Track pageviews or custom events
  • identify - Associate user data with a session
​
payload
object
required
Event payload data

​
Payload for Event Type

​
payload.website
string
Website UUID (required unless using link or pixel)
​
payload.link
string
Link UUID (for link tracking)
​
payload.pixel
string
Pixel UUID (for pixel tracking)
​
payload.hostname
string
Hostname (max 100 characters)
​
payload.language
string
Browser language (max 35 characters)
​
payload.referrer
string
Referrer URL or path
​
payload.screen
string
Screen resolution (max 11 characters, e.g., “1920x1080”)
​
payload.title
string
Page title
​
payload.url
string
Page URL or path
​
payload.name
string
Custom event name (max 50 characters)
​
payload.data
object
Custom event data (key-value pairs)
​
payload.tag
string
Event tag for categorization (max 50 characters)
​
payload.timestamp
number
Unix timestamp in seconds (optional, defaults to current time)
​
payload.id
string
Distinct user ID for tracking across sessions

​
Headers

​
x-umami-cache
string
Cache token from previous request (improves performance)

​
Response

​
cache
string
Cache token to include in subsequent requests
​
sessionId
string
Session UUID
​
visitId
string
Visit UUID

​
Example Requests

curl -X POST https://your-umami-instance.com/api/send \
  -H "Content-Type: application/json" \
  -d '{
    "type": "event",
    "payload": {
      "website": "550e8400-e29b-41d4-a716-446655440000",
      "hostname": "example.com",
      "language": "en-US",
      "referrer": "https://google.com",
      "screen": "1920x1080",
      "title": "Home Page",
      "url": "/"
    }
  }'

​
Example Response

{
  "cache": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "sessionId": "ff0e8400-e29b-41d4-a716-446655440010",
  "visitId": "gg0e8400-e29b-41d4-a716-446655440011"
}

​
UTM Parameters

UTM parameters are automatically extracted from the URL:
  • utm_source
  • utm_medium
  • utm_campaign
  • utm_content
  • utm_term

​
Click IDs

Click IDs are automatically captured from these parameters:
  • gclid (Google)
  • fbclid (Facebook)
  • msclkid (Microsoft)
  • ttclid (TikTok)
  • li_fat_id (LinkedIn)
  • twclid (Twitter)

​
Bot Detection

Bot traffic is automatically filtered unless DISABLE_BOT_CHECK is set in your environment.

​
Caching

Include the cache token from the response in subsequent requests via the x-umami-cache header to improve performance: 
curl -X POST https://your-umami-instance.com/api/send \
  -H "Content-Type: application/json" \
  -H "x-umami-cache: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{...}'
You must provide exactly one of website, link, or pixel in the payload.

Build docs developers (and LLMs) love

Get started for freeTalk to us