User-Agent header so the server can correctly parse the client environment.
POST /api/send
Use this endpoint to record a single event — a pageview, a named custom event, a user identification call, or a performance measurement. Cloud endpoint:https://cloud.umami.is/api/sendSelf-hosted endpoint:
https://<your-instance>/api/send
Unlike most Betterumami API endpoints,
/api/send does not require an Authorization header. Your Website ID (set in payload.website) is the only credential needed to associate the event with your account.Parameters
All fields live inside apayload object. The top-level type field selects the event category.
The category of event to record. One of:
event— a pageview or named custom eventidentify— a user identification payload that enriches subsequent eventsperformance— a web performance measurement (e.g. Core Web Vitals)
The Website ID of the site this event belongs to. Find this value under Settings → Websites in your Betterumami dashboard.
The page URL path where the event occurred (e.g.
/blog/my-post). For pageviews, this is the canonical URL of the page.The visitor’s screen resolution formatted as
"widthxheight" (e.g. "1920x1080"). Used for device breakdowns.The name of the custom event (e.g.
"signup", "add-to-cart"). Required when recording a named event rather than a plain pageview.A client-generated session identifier. If omitted, the server generates one. Pass a stable value to join events across multiple requests into the same session.
An optional key-value map of custom properties to attach to the event (e.g.
{"plan": "pro", "trial": true}). Values can be strings, numbers, or booleans.Sample request and response
Building the payload from browser APIs
When calling/api/send from a browser context, you can derive most payload fields directly from native browser APIs:
POST /api/batch
Use/api/batch to send multiple events in a single HTTP request. This is more efficient than making one /api/send call per event and is the recommended pattern when you’re replaying buffered events, ingesting offline data, or flushing a client-side queue on page unload.
Cloud endpoint: https://cloud.umami.is/api/batchSelf-hosted endpoint:
https://<your-instance>/api/batch
The request body is a JSON array where each element has the same shape as a single /api/send body. All type values and payload fields supported by /api/send are supported here too.
Like
/api/send, the /api/batch endpoint does not require an Authorization header, but it does require a valid User-Agent header.