Skip to main content

​
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

​
Meta

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 }
});

​
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