API 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
Authentication
Every request must include an organization API key in the Authorization header:
Authorization: Bearer modem_your_api_key_here
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.
Create your first key
- Open the Modem dashboard and go to Settings → API Keys. Any member of the organization can create and revoke keys.
- Click Create Key and give it a name.
- 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:
curl https://api.modem.dev/v1/topics \
-H "Authorization: Bearer modem_your_api_key_here"
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.
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.
curl https://api.modem.dev/v1/companies \
-X POST \
-H "Authorization: Bearer modem_your_api_key_here" \
-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.
Errors
Errors use standard HTTP status codes and a JSON body:
| Status | Meaning |
|---|---|
400 |
The request failed validation |
401 |
Missing, invalid, or expired API key |
403 |
The key’s organization does not match the requested organization, or the endpoint does not accept this kind of credential |
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 |
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.