Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

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

  1. Open the Modem dashboard and go to Settings → API Keys. Any member of the organization can create and revoke keys.
  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:

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.

Was this page helpful?