---
title: Public API
description: Authenticate with an API key, then create events and identify users within your Organization.
sidebar:
  order: 0
---

The EmitKit API v1 has three operations:

- `createEvent` sends an event to a named Channel. EmitKit creates the Channel
  when it doesn't exist yet.
- `identifyUser` creates or updates the identity of one of your users.
- `deleteIdentity` erases an identity, so you can honour one of your users'
  erasure requests without waiting for retention.

The base URL is `https://api.emitkit.com`. Every `/v1/*` route is also served
at `/api/v1/*`.

**[Create Event](/reference/events/create-event)**

The request, response, and retry contract.

**[Identify User](/reference/identity/identify-user)**

Identities, properties, and aliases.

**[Delete Identity](/reference/identity/delete-identity)**

Erase one person's identity and aliases.

**[API keys](/api/api-keys)**

Create, rotate, and revoke keys.

**[Complete reference](/reference)**

Every schema, example, and error response.

## Authentication

Send an EmitKit API key in one of these headers:

```http
Authorization: Bearer emitkit_REPLACEWITHKEY
```

```http
X-API-Key: emitkit_REPLACEWITHKEY
```

If you send both, they must carry the same key. A key belongs to one
Organization and is bound to one Project. EmitKit takes the Organization and
Project from the key; IDs in a request body never select them.

## Limits

- **Rate limit:** up to 100 requests per API key in a 60-second window. The
  window starts again 60 seconds after the key's last accepted request.
  Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and
  `X-RateLimit-Reset`. Over the limit you get `429 Too Many Requests` with
  `Retry-After`.
- **Request size:** request bodies are limited to 1 MiB, checked before
  authentication (`413`).
- **Event size:** a stored event is limited to 16 KB across its fields,
  including metadata (`413`).

## Errors and request IDs

Every response carries an `X-Request-ID` header, and error bodies repeat it as
`requestId`. Include it when you contact support. Error bodies never contain
credentials or internal details.

## Erasing a user

`DELETE /v1/identities/{user_id}` erases one person's identity: its properties
and aliases are deleted. The events you already sent are kept for their normal
90 days, but the dashboard no longer shows that person on events recorded
before the erasure. Titles and metadata aren't changed, so don't put personal
data you may need to erase there.

Pass the canonical `user_id`; an alias isn't accepted. The response is
`200 OK` with `"status": "erased"`, or `404 Not Found` when EmitKit doesn't
know the user, so repeating a completed erasure doesn't report success. Any
API key of the Organization can erase an identity.