Skip to main content
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
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.

​
Authentication

Every request must include an organization API key in the Authorization header:
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.
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.

​
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:
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.
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.

​
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.
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.
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.

​
Errors

Errors use standard HTTP status codes and a JSON body:
StatusMeaning
401Missing, invalid, or expired API key
404The resource does not exist (or isn’t in your org)
409Idempotency conflict — the Idempotency-Key was reused with a different payload, or a request with the same key is still in progress
422The request failed validation
429The key exceeded its rate limit — back off and retry
500An unexpected server error
Browse the endpoints in the sidebar to see request/response schemas and try them live.