API Reference

Overview

The EmitKit API provides a simple, RESTful interface for monitoring critical product moments and sending real-time alerts. Base URL: https://api.emitkit.com

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer emitkit_xxxxxxxxxxxxxxxxxxxxx

Create API keys in your dashboard at Settings → API Keys.

Keep in mind that API keys are scoped to organizations and projects.

Rate Limiting

Default: 100 requests per minute per API key
Rate limit information is returned in response headers:
- X-RateLimit-Limit: Maximum requests allowed
- X-RateLimit-Remaining: Remaining requests in current window
- X-RateLimit-Reset: Unix timestamp when limit resets

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response.

Idempotency

To safely retry requests without creating duplicates, include an Idempotency-Key header:

Idempotency-Key: payment-123-retry-1

Idempotency keys are valid for 24 hours
Replayed requests return the original response with an X-Idempotent-Replay: true header
Use this for webhooks, payment processing, or any operation you want to make retry-safe

Request IDs

Every response includes a requestId field for debugging and support purposes:

{
  "success": true,
  "data": { ... },
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Include the request ID when contacting support.

Response Format

All successful responses follow this format:

{
  "success": true,
  "data": {
    // Response data
  },
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Error responses:

{
  "success": false,
  "error": "Error message",
  "details": [
    // Validation errors (if applicable)
  ],
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Error Handling

HTTP Status Codes

200 - Success (identify endpoint)
201 - Created (event created)
400 - Bad Request (validation error)
401 - Unauthorized (missing or invalid API key)
429 - Too Many Requests (rate limit exceeded)
500 - Internal Server Error

Validation Errors

When your request fails validation, you’ll receive a 400 response with details:

{
  "success": false,
  "error": "Validation error",
  "details": [
    {
      "path": ["channelName"],
      "message": "Required"
    }
  ],
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Endpoints

Events

POST /v1/events

Create a new event and optionally send notifications

Identity

POST /v1/identify

Create or update user identity with properties and aliases

GET /openapi.json

Get the OpenAPI 3.1 specification

SDKs

We provide official SDKs for easy integration:

TypeScript/JavaScript

Official SDK with full type safety

npm install @emitkit/js

cURL Examples

Direct HTTP requests for any languageSee code examples on each endpoint

Quick Example

import { EmitKit } from '@emitkit/js';

const client = new EmitKit('emitkit_xxxxxxxxxxxxxxxxxxxxx');

await client.events.create({
  channelName: 'payments',
  title: 'Payment Received',
  metadata: { amount: 99.99 }
});

curl -X POST https://api.emitkit.com/v1/events \
  -H "Authorization: Bearer emitkit_xxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channelName": "payments",
    "title": "Payment Received",
    "metadata": {"amount": 99.99}
  }'

Next Steps

SDK Documentation

Learn about the TypeScript SDK

Quick Start

Send your first event in 5 minutes

Core Concepts

Understand EmitKit’s architecture

Self-Hosting

Deploy your own EmitKit instance

API Documentation

Events

Identity

Meta

Overview

Authentication

Rate Limiting

Idempotency

Request IDs

Response Format

Error Handling

HTTP Status Codes

Validation Errors

Endpoints

Events

POST /v1/events

Identity

POST /v1/identify

Meta

GET /openapi.json

SDKs

TypeScript/JavaScript

cURL Examples

Quick Example

Next Steps

SDK Documentation

Quick Start

Core Concepts

Self-Hosting

​Overview

​Authentication

​Rate Limiting

​Idempotency

​Request IDs

​Response Format

​Error Handling

​HTTP Status Codes

​Validation Errors

​Endpoints

​Events

POST /v1/events

​Identity

POST /v1/identify

​Meta

GET /openapi.json

​SDKs

TypeScript/JavaScript

cURL Examples

​Quick Example

​Next Steps

SDK Documentation

Quick Start

Core Concepts

Self-Hosting

Overview

Authentication

Rate Limiting

Idempotency

Request IDs

Response Format

Error Handling

HTTP Status Codes

Validation Errors

Endpoints

Events

Identity

Meta

SDKs

Quick Example

Next Steps