Skip to main content
POST
/
v1
/
events
import { EmitKit } from '@emitkit/js';
const client = new EmitKit('emitkit_xxxxxxxxxxxxxxxxxxxxx');

const result = await client.events.create({
  channelName: 'payments',
  title: 'Payment Received',
  description: 'User upgraded to Pro plan',
  icon: '💰',
  metadata: {
    amount: 99.99,
    currency: 'USD'
  }
});

console.log('Event created:', result.data.id);
{
  "success": true,
  "data": {
    "id": "event_xxxxxxxxxxxxxxxxxxxxx",
    "channelId": "ch_xxxxxxxxxxxxxxxxxxxxx",
    "channelName": "payments",
    "title": "Payment Received",
    "createdAt": "2025-01-15T10:30:00.000Z"
  },
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Authorizations

​
Authorization
string
header
required

API key authentication. Format: emitkit_xxxxxxxxxxxxxxxxxxxxx

Create API keys in your EmitKit dashboard. Keys are scoped to a specific organization and project.

Headers

​
Idempotency-Key
string

Unique key to ensure idempotent request processing. Prevents duplicate events from retries or webhook replays. Valid for 24 hours.

Required string length: 1 - 255

Body

application/json
​
channelName
string
required

Channel name for organizing events. Channels are automatically created if they don't exist. Use kebab-case for consistency (e.g., 'user-signups').

Required string length: 1 - 255
Example:

"payments"

​
title
string
required

Event title - the main message

Required string length: 1 - 500
Example:

"Payment Received"

​
description
string

Optional detailed description

Maximum string length: 5000
Example:

"User upgraded to Pro plan"

​
icon
string

Single emoji icon to display with the event

Maximum string length: 10
Example:

"💰"

​
tags
string[]

Array of tags for filtering and organization

Maximum array length: 20
Maximum string length: 50
Example:
["payment", "upgrade"]
​
metadata
object

Custom JSON metadata. Any valid JSON structure is accepted. Use this to attach custom data to events for filtering or display.

Example:
{
  "amount": 99.99,
  "currency": "USD",
  "plan": "pro",
  "userId": "user_123"
}
​
userId
string | null

Optional user identifier to associate with this event. Supports both direct user IDs and aliases (email, username, etc.) created via the /v1/identify endpoint. Aliases are automatically resolved to canonical user IDs.

Maximum string length: 255
Example:

"user_123"

​
notify
boolean
default:true

Whether to send push notifications to connected devices (PWA or browsers with accepted notifications). Set to false for silent event logging.

Response

Event created successfully

​
success
boolean
required

Indicates successful event creation

Example:

true

​
data
object
required
​
requestId
string<uuid>
required

Unique request identifier for debugging and support

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"