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" } }