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

# Introduction

> Authenticate and make your first request to the Modem API.

The Modem API is a REST API for reading and acting on the product signals Modem
aggregates — topics, people, companies, groups, and more. It's the same data you
see in the dashboard, available programmatically.

* **Base URL:** `https://api.modem.dev/v1`
* **Auth:** organization API key via a bearer token
* **Format:** JSON over HTTPS

<Note>
  The interactive playground on each endpoint page lets you make live, authenticated requests. Paste an API key into the **Authorization**
  field to try it out.
</Note>

## Authentication

Every request must include an organization API key in the `Authorization` header:

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

An API key is scoped to a single organization — it resolves to that org and can only
read and act on that org's data. A key is its own credential; it is not tied to a
member's account or role. Every key carries the `modem_` prefix.

<Warning>
  Treat API keys like passwords. Never commit them to source control or expose them in client-side code. The full key is shown only once,
  at creation time.
</Warning>

## Create your first key

1. Open the Modem dashboard and go to **Settings → API Keys**. (Key management is
   restricted to organization **owners**.)
2. Click **Create Key** and give it a name.
3. Copy the key immediately — it is displayed once and cannot be retrieved again. If
   you lose it, revoke it and create a new one.

## Make a request

List the most recent topics for your organization:

```bash theme={null}
curl https://api.modem.dev/v1/topics \
  -H "Authorization: Bearer modem_xxxxxxxxxxxxxxxxxxxx"
```

A missing or invalid key returns `401 Unauthorized`. A key for one organization can
never read another organization's data.

## Rate limits

Each API key is rate limited to **120 requests per minute**. When a key exceeds its
limit, requests return `429 Too Many Requests` until the window resets — back off and
retry. Limits are per key, so you can isolate workloads by minting separate keys.

<Note>
  A shared edge firewall also applies coarse, IP-based protection in front of the per-key limit. Well-behaved clients will only ever
  encounter the per-key `429`.
</Note>

## Idempotency

Write requests (`POST` and `PATCH`) accept an optional `Idempotency-Key` header so that a
retried request — after a network blip, a timeout, or an ambiguous failure — can't create
duplicate people or companies, or re-trigger a cost-bearing enrichment. Idempotency is
opt-in: omit the header and the request runs normally, and safe methods (`GET`, `HEAD`)
ignore it entirely.

Send a unique value per logical operation, and reuse the **same** key when you retry that
operation. A UUID or ULID is ideal; keys can be up to 255 characters.

```bash theme={null}
curl https://api.modem.dev/v1/companies \
  -X POST \
  -H "Authorization: Bearer modem_xxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 3f6b9c1e-8a2d-4e57-b1c0-2f9d4e7a1b6c" \
  -H "Content-Type: application/json" \
  -d '{"companies":[{"name":"Acme","domain":"acme.com"}]}'
```

The first request under a given key runs once and stores its response. A later retry with
the **same key and the same payload** returns that stored response verbatim, without
running the operation again. Stored responses are replayable for **24 hours**; after that
the key is reclaimable.

Only successful responses are cached. If a request fails, its key is released, so you can
safely retry with the same key.

<Warning>
  Reusing a key with a *different* request payload returns `409 Conflict`, as does sending a second request with the same key while the
  first is still in progress. Mint a fresh key for each new operation.
</Warning>

## Errors

Errors use standard HTTP status codes and a JSON body:

| Status | Meaning                                                                                                                               |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | Missing, invalid, or expired API key                                                                                                  |
| `404`  | The resource does not exist (or isn't in your org)                                                                                    |
| `409`  | Idempotency conflict — the `Idempotency-Key` was reused with a different payload, or a request with the same key is still in progress |
| `422`  | The request failed validation                                                                                                         |
| `429`  | The key exceeded its rate limit — back off and retry                                                                                  |
| `500`  | An unexpected server error                                                                                                            |

Browse the endpoints in the sidebar to see request/response schemas and try them live.