Skip to main content
POST

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:
​
metadata
object

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

Example:
​
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"