Sending events
The write endpoints, every field they take, and what comes back.
Every request is JSON, sent with two headers:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
The key names the project, so project is optional in every body. If you send it, it must be the project’s slug.
Events
POST https://api.snekot.co/v1/log
| Field | Type | |
|---|---|---|
channel |
string | Required. Lowercase letters, digits and dashes, up to 64 characters. |
event |
string | Required. The event’s name, up to 200 characters. |
description |
string | Up to 4,000 characters. |
icon |
string | One emoji, or a shortcode such as :moneybag:. |
notify |
boolean | Send it as a push notification. Off unless set. |
tags |
object | Keys are lowercase letters, digits and dashes. Values are strings, numbers or booleans. Up to 50, and a text value up to 1,000 characters. |
ip, user_agent |
string | From a server only: the address and user agent of the person who did it. They tie the event to that visitor’s page views for funnels, and are not stored. Events sent from a web page are tied to their visitor without them. |
user_id |
string | The person this event is about. |
parser |
"markdown" or "text" |
With markdown, the description renders bold, italic, inline code and links. |
timestamp |
number | Unix seconds. Stores the event at that time. See below. |
The answer is 201 with the stored event, including its id and created_at.
Dry run
Add "dry_run": true to the body, or ?dry_run=1 to the address, to check a call without sending it. The key, the project, the channel and every field are checked as usual, and a mistake gets the same refusal. A correct call gets 200:
{ "dry_run": true, "project": "acme-store", "key": "public", "channel": "orders", "event": "Order placed", "message": "This event is valid. Nothing was stored." }
Nothing is stored, counted towards the plan, announced or forwarded. A dry run does not check whether the month’s allowance is used up.
Backfilling
An event sent with a timestamp is a backfill. It is stored at that moment and takes its place in the feed and charts, but it is not announced on the live feed and never sends a push notification. A public key can set a timestamp only within the last 7 days, which is what an app does when it was offline; anything older or in the future gets a 403. With any key, a timestamp more than five minutes ahead of now gets a 400.
Insights
An insight is a single value with a title, shown as a tile: MRR, signups today, orders in transit.
POST https://api.snekot.co/v1/insight sets it:
{ "title": "MRR", "value": "$1,289", "icon": "📈" }
PATCH https://api.snekot.co/v1/insight adds to it, starting from 0 if it does not exist. Use a negative number to subtract:
{ "title": "Orders in transit", "value": { "$inc": 1 } }
An insight holding text, such as "$1,289", cannot be incremented; the request is refused and says so. Insights need a private key.
People
POST https://api.snekot.co/v1/identify sets properties on a person. Keys sent again replace their old values; the rest are kept.
{ "user_id": "user-123", "properties": { "name": "Jane Park", "email": "[email protected]", "plan": "pro" } }
A person also appears without being identified, the first time an event carries their user_id. Their page shows a name or email property in place of the id when there is one, and People can be searched by any property.
Groups
POST https://api.snekot.co/v1/group describes a group, such as a company or a team, and puts a user in it when user_id is given.
{ "group_id": "acme", "user_id": "user-123", "properties": { "name": "Acme", "seats": 12 } }
Newsletter signups
POST https://api.snekot.co/v1/subscribe puts an address on the project’s list of subscribers. See Newsletter signups.
{ "email": "[email protected]", "name": "Jane Park", "source": "/blog/launch" }
Page views
POST https://api.snekot.co/v1/page records a page view. The browser script sends these by itself; you rarely call it by hand. Page views are not counted against a plan’s events.
{ "user_id": "user-123", "payload": { "path": "/pricing", "title": "Pricing", "referrer": "https://example.com" } } Next SDKs