# The Ahem API

Base address: `https://api.useahem.com`

This is the text version of the docs at https://app.useahem.com/docs, all pages in one file, written from the same content.

## Start

One request puts an event into a channel. Ahem stores it, shows it in the inbox at once, and decides for each person whether their devices should buzz.

### Send your first event

1. Create an API key on your project’s page in the app. It starts with `ak_live_` and is shown once. Keep it on your server, in the `AHEM_KEY` environment variable.
2. Send a request to a channel’s address: your project’s address, a slash, and the channel’s name.

curl:

```sh
curl -X POST https://api.useahem.com/v1/channels/my-app/payments \
  -H "Authorization: Bearer $AHEM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello from my app 👋","level":"success","type":"app.hello"}'
```

Node:

```js
await fetch("https://api.useahem.com/v1/channels/my-app/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AHEM_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Hello from my app 👋",
    level: "success",
    type: "app.hello"
  }),
});
```

Python:

```python
import json, os, urllib.request

request = urllib.request.Request(
    "https://api.useahem.com/v1/channels/my-app/payments",
    data=json.dumps({
        "title": "Hello from my app 👋",
        "level": "success",
        "type": "app.hello",
    }).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['AHEM_KEY']}",
        "Content-Type": "application/json",
    },
)
urllib.request.urlopen(request)
```

PHP:

```php
$ch = curl_init("https://api.useahem.com/v1/channels/my-app/payments");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("AHEM_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "title" => "Hello from my app 👋",
        "level" => "success",
        "type" => "app.hello",
    ]),
]);
curl_exec($ch);
```

The answer is `202 Accepted` with the event’s id. The event is in the inbox by the time you look.

- [Events](https://app.useahem.com/docs/events.md): Send and read events: every field, channels, notifications and retries.
- [People](https://app.useahem.com/docs/people.md): Who your events are about: how people appear, their details, and erasing someone.
- [Playground](https://app.useahem.com/docs/playground): Send events into your own channels from this page.

### API keys

Every request carries a key in the `Authorization: Bearer ak_live_…` header. A key belongs to one project and can do what its scopes allow:

- `events:write`: send events, and add, change or erase people.
- `channels:create`: sending to a channel name that does not exist yet creates the channel.
- `events:read`: read events and people. New keys do not have it unless you tick it.

All requests and answers are JSON. Names are `snake_case`, and times are ISO 8601 in UTC.

### Errors

An error is a JSON object with a sentence for people and, where it helps, a `code` for your program:

```json
{
  "title": "The request is not valid.",
  "status": 400,
  "code": "validation_failed",
  "errors": {
    "title": ["'title' is required."],
    "level": ["'level' must be one of: info, success, warning, error."]
  }
}
```

| Status | Code | What happened |
|---|---|---|
| 400 | `validation_failed` | A field breaks a rule. `errors` has a message for each field. |
| 400 | `invalid_request` | The body is not valid JSON, or is missing. The message says where. |
| 400 | `channel_limit_reached` | The project already has 100 channels, so a new one was not created. |
| 401 | — | The API key is missing, misspelled or revoked. |
| 403 | `missing_scope` | The key is not allowed to do this. The message names the scope it needs. |
| 403 | `insights_required` | Details about people are part of the Maker plan. |
| 404 | `not_found` | No such channel (and the key may not create it), or no such person. |
| 413 | `request_too_large` | The body is larger than 64 KB. |
| 429 | `rate_limited` | More than 10 requests a second for the project, after a burst of 100. `Retry-After` says how long to wait. |
| 429 | `quota_exhausted` | The workspace sent ten times its monthly events. Nothing more is accepted until next month or an upgrade. |

### Limits

- 10 requests a second for each project, counted across all its keys, with room for a burst of 100. Sending events and changing people share it.
- A request body of at most 64 KB. A project has at most 100 channels and 20 keys.
- The Free plan includes 3,000 events a month and keeps them for 7 days. Maker includes 100,000 and keeps them for a year.
- Going over the month’s events never breaks your app: events are accepted and stored, and only notifications pause. Requests are refused only at ten times the month’s events.

## Events

An event is one thing that happened in your app: a payment, a sign-up, a failed job. You send it to a channel, and it is shown to everyone in the project.

### Send an event

`POST /v1/channels/{project}/{channel}`

`POST /v1/channels/{channel_id}`

The key needs the `events:write` scope. The body is JSON, at most 64 KB. Only `title` is required.

| Field | Type | Required | Rules |
|---|---|---|---|
| `title` | string | yes | What happened, in one line. 1 to 200 characters. |
| `body` | string | no | The details, as Markdown. Up to 10,000 characters. |
| `level` | string | no | `info` (the default), `success`, `warning` or `error`. Decides the colour, and who is notified. |
| `type` | string | no | A machine-readable name such as `payment.received`: words of lower-case letters, digits and `_`, joined by dots. Up to 100 characters. Defaults to `event`. |
| `url` | string | no | A link that belongs to the event, shown as “Open link”. An absolute http or https address, up to 2,048 characters. |
| `icon` | string | no | An emoji shown next to the title. Up to 16 characters. |
| `metadata` | object | no | Any JSON object, up to 8 KB. Its top-level values can be searched and filtered: `plan:pro`. |
| `user` | object | no | Who the event is about: `{ id, name, email }`, each optional, each up to 200 characters. Events with the same `id` (or the same `email`, without an id) are one person, on the People page. With Maker, `properties` and `properties_once` keep details about them (see People). |
| `tags` | string[] | no | Up to 10 short labels, 50 characters each. |
| `group` | string | no | A name that ties related events together, such as `order:1042`. Events of a project with the same group are shown as one thread. Up to 200 characters. |
| `notify` | string | no | `default` follows each person’s setting for the channel. `loud` notifies whatever the level. `silent` never notifies. |
| `timestamp` | string | no | When it happened, if not now: an ISO 8601 date and time with `Z` or an offset. Not more than a day ahead. |

The answer names the event and the channel it went to:

```json
{
  "id": "evt_01m7c9k2x4…",
  "channel": "my-app/payments",
  "created_at": "2026-11-13T09:41:00.512+00:00"
}
```

### Channels and addresses

A channel has two addresses. `my-app/payments` is the project’s address and the channel’s name, which reads well in code. `ch_…` is its id, which never changes. Both are in the channel’s ⋯ menu in the app.

Sending to a channel name that does not exist yet creates the channel, if the key has the `channels:create` scope. New keys have it. Without it the answer is `404`. The event is checked first, so a refused event never leaves an empty channel behind.

### Who gets notified

Every event is stored and shown. Whether it also reaches someone’s devices is decided for each person, in this order:

1. `"notify": "silent"` never notifies anyone. Use it for backfills and high-volume events.
2. A person who switched the channel’s bell off is not notified, whatever the event says.
3. `"notify": "loud"` notifies everyone else, whatever the level.
4. Someone watching the person the event is about is notified of their events (or only their errors), even where the channel is quieter.
5. Otherwise the `level` is compared with the person’s choice for the channel: every event, warnings and errors, or errors only.

Past the workspace’s monthly events, nothing is notified until the next month. Events are still stored.

### Sending the same event twice

When a request fails halfway, your code cannot know whether the event arrived. Send an `Idempotency-Key` header with a value of your own (up to 200 characters, such as `order-1042-paid`) and retry freely: the second request with the same key answers `200` with the first event and stores nothing new. A key counts within one project, and is forgotten if the event is deleted.

### Read events

`GET /v1/events`

Lists the events of the key’s project, newest first. The key needs the `events:read` scope.

| Field | Type | Required | Rules |
|---|---|---|---|
| `channel` | string | no | A channel id (`ch_…`) or its name (`payments`). Without it, every channel of the key’s project. |
| `level` | string | no | `info`, `success`, `warning` or `error`. |
| `type` | string | no | An exact type, or a prefix with a wildcard: `payment.*`. |
| `group` | string | no | Events that were sent with this `group`. |
| `user` | string | no | Events about one person: the `user.id` or the `user.email` they were sent with. |
| `person` | string | no | Exactly one person’s events, by their key: the `user.id`, or the `user.email` of events sent without an id. |
| `meta` | string | no | A metadata value, as `key:value`. Repeat it to ask for several. |
| `q` | string | no | Words to find in the title, body and type. |
| `limit` | number | no | How many events to return. 50 by default, 100 at most. |
| `cursor` | string | no | The `next_cursor` of the previous page. |

```sh
curl "https://api.useahem.com/v1/events?level=error&limit=20" \
  -H "Authorization: Bearer $AHEM_KEY"
```

The answer is `{ "items": [...], "next_cursor": "…" }`. Each item has the fields you sent, plus `id`, `project_id`, `channel_id`, `channel` and `created_at`. What a person does with an event in the app (reading, starring, archiving) is theirs alone and is not part of it. `next_cursor` is `null` on the last page.

## People

A person is someone your events are about: a customer, a user of your app. Each one has a page in the app with every event about them, and the details you keep about them.

### How someone becomes a person

Send an event with a `user`, and that person appears on the People page. They are known by `user.id`, or by `user.email` when you send no id. Name and email are optional. Send the same id every time, so all their events land on one person.

```json
{
  "title": "Upgraded to Maker",
  "type": "subscription.started",
  "user": {
    "id": "u_381",
    "name": "Maria",
    "email": "maria@example.com",
    "properties": { "plan": "maker" },
    "properties_once": { "signup_source": "app_store" }
  }
}
```

A person belongs to one project. An id is up to 200 characters, and cannot be `.` or `..`.

### Details

Details are what you know about someone, such as their plan. They come with an event (`user.properties`) or with a request of their own (below). The same rules hold either way:

- The newest value wins, and `null` removes a detail.
- `properties_once` sets a detail only where the person has none yet, such as where they signed up.
- Values are text (up to 500 characters), numbers or true/false. At most 50 details, 8 KB in all.
- Keys are names that search can use, such as `plan` or `app.version`. They cannot be `level`, `type`, `channel` or `user`.
- Details are part of Maker. On Free, events still make people, without details.

### Add or change someone

Without an event, for example when a payment webhook changes someone’s plan:

`PUT /v1/people/{id}`

| Field | Type | Required | Rules |
|---|---|---|---|
| `name` | string | no | Up to 200 characters. `null` clears it. Left out, it stays as it is. |
| `email` | string | no | Up to 200 characters. `null` clears it. Left out, it stays as it is. |
| `properties` | object | no | Details about them, such as `{ "plan": "maker" }`: text (up to 500 characters), numbers or true/false, at most 50, 8 KB in all. The newest value wins; `null` removes a detail. Keys are names and cannot be `level`, `type`, `channel` or `user`. Maker. |
| `properties_once` | object | no | Details to set only where the person has none yet, such as where they signed up. Maker. |

```sh
curl -X PUT "https://api.useahem.com/v1/people/u_381" \
  -H "Authorization: Bearer $AHEM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"properties":{"plan":"maker","seats":3}}'
```

The answer is the person: `201` when they are new, `200` when they were there. With no body it just adds them. The key needs `events:write`. An id that holds a `/` is sent as `%2F`.

### Find people

`GET /v1/people`

`GET /v1/people/{id}`

The list is the most recently seen first. The key needs the `events:read` scope.

| Field | Type | Required | Rules |
|---|---|---|---|
| `q` | string | no | Words find a name, an email or an id. `plan:maker` finds a detail, and `user:u_381` an id or email exactly. |
| `limit` | number | no | How many people to return. 50 by default, 100 at most. |
| `cursor` | string | no | The `next_cursor` of the previous page. |

Each person comes as:

```json
{
  "id": "u_381",
  "name": "Maria",
  "email": "maria@example.com",
  "properties": { "plan": "maker", "signup_source": "app_store" },
  "events": 42,
  "errors": 1,
  "first_seen_at": "2026-10-02T08:12:44Z",
  "last_seen_at": "2026-11-13T09:41:00Z",
  "created_at": "2026-10-02T08:12:44Z",
  "updated_at": "2026-11-13T09:41:00Z"
}
```

### Erase someone

`DELETE /v1/people/{id}`

Erases the person and every event about them, with their notification history: for a request to delete someone’s data. It cannot be undone. The answer is `204`. The key needs `events:write`.

## Playground

Send events into your own channels and watch them arrive, without writing code. Start from an example, change anything, and send. The request beside the form is the same one, for your code.

### Send an event

The playground is a form on the page, for people: https://app.useahem.com/docs/playground
