> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emitkit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete EmitKit API documentation

## 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:

```bash theme={null}
Authorization: Bearer emitkit_xxxxxxxxxxxxxxxxxxxxx
```

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

<Note>
  Keep in mind that API keys are scoped to organizations and projects.
</Note>

## 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:

```bash theme={null}
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:

```json theme={null}
{
  "success": true,
  "data": { ... },
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

Include the request ID when contacting support.

## Response Format

All successful responses follow this format:

```json theme={null}
{
  "success": true,
  "data": {
    // Response data
  },
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

Error responses:

```json theme={null}
{
  "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:

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

## Endpoints

### Events

<Card title="POST /v1/events" icon="bolt" href="#post-v1events">
  Create a new event and optionally send notifications
</Card>

### Identity

<Card title="POST /v1/identify" icon="user" href="#post-v1identify">
  Create or update user identity with properties and aliases
</Card>

### Meta

<Card title="GET /openapi.json" icon="file-code" href="#get-openapijson">
  Get the OpenAPI 3.1 specification
</Card>

## SDKs

We provide official SDKs for easy integration:

<CardGroup cols={2}>
  <Card title="TypeScript/JavaScript" icon="js" href="/sdk/typescript">
    Official SDK with full type safety

    ```bash theme={null}
    npm install @emitkit/js
    ```
  </Card>

  <Card title="cURL Examples" icon="terminal">
    Direct HTTP requests for any language

    See code examples on each endpoint
  </Card>
</CardGroup>

## Quick Example

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { EmitKit } from '@emitkit/js';

  const client = new EmitKit('emitkit_xxxxxxxxxxxxxxxxxxxxx');

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

  ```bash cURL theme={null}
  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}
    }'
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="SDK Documentation" icon="book" href="/sdk/typescript">
    Learn about the TypeScript SDK
  </Card>

  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Send your first event in 5 minutes
  </Card>

  <Card title="Core Concepts" icon="lightbulb" href="/concepts/overview">
    Understand EmitKit's architecture
  </Card>

  <Card title="Self-Hosting" icon="server" href="/self-hosting/overview">
    Deploy your own EmitKit instance
  </Card>
</CardGroup>