Skip to main content
POST
/
api
/
v1
/
events
Track event
curl --request POST \
  --url https://api.example.com/api/v1/events \
  --header 'Content-Type: application/json' \
  --data '
{
  "external_user_id": "<string>",
  "name": "<string>",
  "properties": {}
}
'
{
  "data.accepted": true
}

Documentation Index

Fetch the complete documentation index at: https://docs.vibefollow.com/llms.txt

Use this file to discover all available pages before exploring further.

Emit a single event for a user. The endpoint accepts both the 9 canonical lifecycle event names and any custom name you choose.

​
Request

POST /api/v1/events HTTP/1.1
Host: api.vibefollow.com
Authorization: Bearer sk_live_••••
Content-Type: application/json
Idempotency-Key: 7b6c7e9e-2c2d-4a8d-9d3a-4f3d2c1b0a99

​
Body

{
  "external_user_id": "usr_42",
  "name": "user_signed_up",
  "properties": {
    "plan": "trial",
    "source": "organic"
  }
}
​
external_user_id
string
required
External user ID. Should match the ID used in Upsert user. If the user hasn’t been identified yet, the event is buffered and attached when they’re first seen.
​
name
string
required
Event name. One of the canonical 9 or any custom string (snake_case recommended).
​
properties
object
JSON-serialisable property bag. Optional — defaults to {}.

​
Response

HTTP/1.1 202 Accepted
Content-Type: application/json

{ "data": { "accepted": true } }
​
data.accepted
boolean
Always true on success. The event is enqueued and processed asynchronously.

​
Examples

import { VibeFollow } from '@vibefollow/sdk';

const vf = new VibeFollow({ apiKey: process.env.VIBEFOLLOW_API_KEY! });

// Typed helper for canonical events
await vf.users.signedUp('usr_42', { plan: 'trial', source: 'organic' });

// Generic track for custom events
await vf.events.track('dashboard_created', 'usr_42', {
  source: 'wizard',
});

​
Common errors

Missing or malformed Authorization header.
API key valid but not authorised for this resource.
Body failed schema validation; errors[0].field indicates the offending field.
Wait Retry-After seconds.
Retry — the Idempotency-Key prevents duplicates.