# API reference

Source: https://docs.rocketverifier.com/api

> The RocketVerifier API is a JSON REST API at https://api.rocketverifier.com/v1. Authenticate every call with an API key or OAuth access token in the Authorization Bearer header, branch on the error code when a call fails, and read the X-RateLimit headers to pace your traffic.

Every RocketVerifier product, from the dashboard to the MCP server, runs on this API. It speaks JSON over HTTPS, uses one error shape everywhere and answers most single verifications in under half a second.

## Make your first request

Send the key in the `Authorization` header and JSON in the body. This call checks your balance and costs nothing.

cURL:

```bash
curl https://api.rocketverifier.com/v1/credits \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"
```

Node.js:

```js
import RocketVerifier from "@rocketverifier/sdk";

const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY);
const balance = await rv.getCredits();
console.log(balance.credits);
```

Python:

```python
import os
from rocketverifier import RocketVerifier

rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"])
print(rv.get_credits().credits)
```

All paths in this reference start with `/v1`. Request bodies are `application/json`, except file uploads, which use `multipart/form-data`. Timestamps are ISO 8601 in UTC.

## Authenticate requests

Every endpoint that touches your account needs `Authorization: Bearer <credential>`. The credential is one of:

| Credential | Prefix | Use it for |
| --- | --- | --- |
| Live API key | `rv_live_` | Server-side calls on your own account. |
| Sandbox API key | `rv_test_` | Tests and CI. Accepts only `@sandbox.rocketverifier.com` addresses and never charges. |
| Organization API key | `rv_live_` | Calls billed to an organization, with its shared rate limit and IP allowlist. |
| OAuth access token | `rv_at_` | Apps acting for other RocketVerifier users through RocketVerifier Connect. |

API keys carry scopes, and each endpoint checks one. A missing scope returns `403 insufficient_scope`. Keys can also have an expiry date, an IP allowlist and a monthly spend cap. The [authentication guide](https://docs.rocketverifier.com/authentication) covers each, and [OAuth scopes](https://docs.rocketverifier.com/oauth/scopes) lists what apps can request.

| Scope | Endpoints |
| --- | --- |
| `verify:single` | `POST /v1/verify`, `POST /v1/finder` |
| `verify:bulk` | `POST /v1/verify/bulk`, `POST /v1/verify/bulk/upload`, `/preview`, `/confirm` |
| `jobs:read` | `GET /v1/jobs` and every `GET /v1/jobs/{jobId}` endpoint |
| `jobs:write` | `DELETE /v1/jobs/{jobId}` |
| `monitors:read` | `GET /v1/monitors`, `GET /v1/monitors/{monitorId}`, `/runs` |
| `monitors:write` | `POST`, `PATCH` and `DELETE` on `/v1/monitors`, and `/run` |
| `webhooks:manage` | Every `/v1/webhooks` endpoint except `/events` |
| `credits:read` | `GET /v1/credits` |
| `account:read` | `GET /v1/me` for OAuth tokens. API keys can always call it. |

## Choose a result version

The `RocketVerifier-Version` header picks how catch-all addresses map onto `status`. With `2026-11-01`, a catch-all address is `risky`. With `2025-01-01`, it is `unknown`. Without the header, the key's own version applies, and keys created from November 2026 use `2026-11-01`.

cURL:

```bash
curl -X POST https://api.rocketverifier.com/v1/verify \
  -H "Authorization: Bearer $ROCKETVERIFIER_API_KEY" \
  -H "RocketVerifier-Version: 2026-11-01" \
  -H "Content-Type: application/json" \
  -d '{"email": "maya@northwind.io"}'
```

The header applies to `POST /v1/verify`, job results and job downloads. [Result versions](https://docs.rocketverifier.com/versioning) explains when to move.

## Retry safely with Idempotency-Key

An `Idempotency-Key` header makes a write safe to retry: the same key within 24 hours returns the first response and never charges again. Use any unique string, such as a UUID.

- **Accepted on:** `POST /v1/verify`, `POST /v1/verify/bulk` and `POST /v1/verify/bulk/upload`.
- **Scope:** keys are stored per account, so two accounts never collide.
- **Store unavailable:** a call with a key gets `503 idempotency_unavailable` instead of running unprotected. Retry it, or drop the header.

The Node.js and Python SDKs send a fresh key on every write, so their automatic retries never double charge.

## Handle errors

Every error, on every endpoint, has the same shape. Branch on `error.code`, show `error.message` to people and read `error.details` for context.

Error body:

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "Need 1000 credits, have 640",
    "details": { "required": 1000, "available": 640 }
  }
}
```

| Status | Typical codes | Meaning |
| --- | --- | --- |
| 400 | `no_emails`, `job_not_complete`, `invalid_domain` | The request is well formed but cannot run. |
| 401 | `unauthorized`, `api_key_expired`, `invalid_token` | The credential is missing, wrong, revoked or expired. |
| 402 | `insufficient_credits`, `api_key_spend_cap_reached` | The balance or the key's monthly cap does not cover the charge. |
| 403 | `insufficient_scope`, `insufficient_credits`, `sandbox_key_restricted`, `ip_not_allowed`, `account_suspended` | The credential cannot make this call. A zero balance is refused here, before any work runs. |
| 404 | `not_found` | The resource does not exist or belongs to another account. |
| 409 | `job_not_cancellable`, `job_not_awaiting_confirmation` | The resource changed state. |
| 422 | `validation_error` | The body or a parameter failed validation. `details.errors` lists each problem. |
| 429 | `rate_limited`, `daily_limit_reached` | Slow down. Wait for `Retry-After` seconds. |
| 503 | `maintenance`, `idempotency_unavailable`, `service_unavailable` | Retry after a short wait. |

The [errors reference](https://docs.rocketverifier.com/errors) lists every code with the fix.

## Stay within rate limits

Limits are counted per minute over a sliding window, per account (organization keys share one bucket per organization). Every response carries the current state:

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | Requests allowed per minute. |
| `X-RateLimit-Remaining` | Requests left in the current window. |
| `X-RateLimit-Reset` | Unix time when the oldest request leaves the window. |
| `Retry-After` | On `429` only: seconds to wait. |

Free and trial accounts get 30 requests per minute, pay as you go accounts 300, and subscriptions 600. Calls without a key get 5 per minute per IP address. A key can carry its own limit. [Rate limits](https://docs.rocketverifier.com/rate-limits) has the details and retry patterns.

## Paginate lists

List endpoints take `page` (starting at 1) and `limit`, and return `total`, `page`, `limit` and `has_more`. Request the next page while `has_more` is `true`.

| Endpoint | Default `limit` | Max `limit` |
| --- | --- | --- |
| `GET /v1/jobs` | 20 | 100 |
| `GET /v1/jobs/{jobId}/results` | 100 | 1,000 |
| `GET /v1/webhooks/{webhookId}/logs` | 50 | 100 |
| `GET /v1/monitors/{monitorId}/runs` | 20 | 100 |

`GET /v1/webhooks` and `GET /v1/monitors` return the full list as an array. To export every result of a job in one response, use [the download endpoint](https://docs.rocketverifier.com/api/batch#download-results) instead of paging.

## Trace a request

Every response carries an `X-Request-ID` header. Send your own (up to 128 characters) to follow a call through your logs, and include it when you contact support.

## Check API status

`GET /v1/status` returns the health of the API and its components. It needs no key.

`GET /v1/status`

cURL:

```bash
curl https://api.rocketverifier.com/v1/status
```

Response 200:

```json
{
  "status": "healthy",
  "version": "1.1.0",
  "uptime_seconds": 86412.37,
  "timestamp": "2026-11-11T09:42:17.208114+00:00",
  "components": [
    { "name": "database", "status": "healthy", "latency_ms": 3.12, "details": null },
    { "name": "redis", "status": "healthy", "latency_ms": 0.84, "details": null },
    { "name": "verification_nodes", "status": "healthy", "latency_ms": null, "details": "12/12 healthy" },
    { "name": "engine", "status": "healthy", "latency_ms": null, "details": null },
    { "name": "worker_queue", "status": "healthy", "latency_ms": null, "details": "4 queued jobs" }
  ],
  "sandbox_domain": "sandbox.rocketverifier.com",
  "docs_url": "https://docs.rocketverifier.com"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `status` | enum | `degraded` when a core component is unhealthy, no node is healthy, or the engine is in maintenance. one of `healthy`, `degraded` |
| `version` | string |  |
| `uptime_seconds` | number |  |
| `timestamp` | string (date-time) |  |
| `components` | array of objects |  |
| `components.name` | enum | one of `database`, `redis`, `verification_nodes`, `engine`, `worker_queue` |
| `components.status` | enum | one of `healthy`, `degraded`, `unhealthy`, `maintenance`, `unknown` |
| `components.latency_ms` | number or null | Round trip time, for the database and Redis. |
| `components.details` | string or null | Context such as `12/12 healthy` for the node fleet or the queue depth. |
| `sandbox_domain` | string |  |
| `docs_url` | string |  |

`status` is `degraded` when the database or Redis is unhealthy, when no verification node is healthy, or while the engine is in maintenance. An `engine` component with status `maintenance` explains what is paused in `details`.

## Every endpoint

### Verification

| Method | Path | What it does |
| --- | --- | --- |
| POST | [`/v1/verify`](https://docs.rocketverifier.com/api/verify) | Verify one address in real time. |
| POST | [`/v1/verify/bulk`](https://docs.rocketverifier.com/api/batch#create-a-bulk-job) | Start a bulk job from a JSON list of up to 100,000 addresses. |
| POST | [`/v1/verify/bulk/upload`](https://docs.rocketverifier.com/api/bulk-upload) | Start a bulk job from a CSV, TSV, TXT or XLSX file or a URL. |
| POST | [`/v1/verify/bulk/{jobId}/preview`](https://docs.rocketverifier.com/api/bulk-upload#get-the-free-list-health-preview) | Read the free list health preview of an upload. |
| POST | [`/v1/verify/bulk/{jobId}/confirm`](https://docs.rocketverifier.com/api/bulk-upload#confirm-and-start-the-job) | Charge and start a previewed upload. |
| GET | [`/v1/jobs`](https://docs.rocketverifier.com/api/batch#list-jobs) | List your bulk jobs. |
| GET | [`/v1/jobs/{jobId}`](https://docs.rocketverifier.com/api/batch#get-job-status) | Get a job's status and counters. |
| GET | [`/v1/jobs/{jobId}/progress`](https://docs.rocketverifier.com/api/batch#track-progress) | Poll progress, throughput and ETA. |
| GET | [`/v1/jobs/{jobId}/results`](https://docs.rocketverifier.com/api/batch#read-results-page-by-page) | Page through per-address results. |
| GET | [`/v1/jobs/{jobId}/download`](https://docs.rocketverifier.com/api/batch#download-results) | Download every result as CSV or JSON. |
| DELETE | [`/v1/jobs/{jobId}`](https://docs.rocketverifier.com/api/batch#cancel-a-job) | Cancel a job and refund what was not processed. |
| POST | [`/v1/finder`](https://docs.rocketverifier.com/api/finder) | Find an address from a name and a company domain. |

### Automation

| Method | Path | What it does |
| --- | --- | --- |
| POST | [`/v1/monitors`](https://docs.rocketverifier.com/api/monitors#create-a-monitor) | Create a list health or domain authentication monitor. |
| GET | [`/v1/monitors`](https://docs.rocketverifier.com/api/monitors#list-get-update-and-delete-monitors) | List monitors. |
| GET | [`/v1/monitors/{monitorId}`](https://docs.rocketverifier.com/api/monitors#list-get-update-and-delete-monitors) | Get a monitor and its latest result. |
| PATCH | [`/v1/monitors/{monitorId}`](https://docs.rocketverifier.com/api/monitors#list-get-update-and-delete-monitors) | Update, pause or resume a monitor. |
| DELETE | [`/v1/monitors/{monitorId}`](https://docs.rocketverifier.com/api/monitors#list-get-update-and-delete-monitors) | Delete a monitor. |
| POST | [`/v1/monitors/{monitorId}/run`](https://docs.rocketverifier.com/api/monitors#run-a-monitor-now) | Run a monitor now. |
| GET | [`/v1/monitors/{monitorId}/runs`](https://docs.rocketverifier.com/api/monitors#read-run-history) | Read a monitor's run history. |
| GET | [`/v1/webhooks/events`](https://docs.rocketverifier.com/api/webhooks#list-event-types) | List the events you can subscribe to. |
| POST | [`/v1/webhooks`](https://docs.rocketverifier.com/api/webhooks) | Register a webhook endpoint. |
| GET | [`/v1/webhooks`](https://docs.rocketverifier.com/api/webhooks#list-get-update-and-delete-webhooks) | List webhook endpoints. |
| GET | [`/v1/webhooks/{webhookId}`](https://docs.rocketverifier.com/api/webhooks#list-get-update-and-delete-webhooks) | Get one endpoint. |
| PATCH | [`/v1/webhooks/{webhookId}`](https://docs.rocketverifier.com/api/webhooks#list-get-update-and-delete-webhooks) | Update, pause or resume an endpoint. |
| DELETE | [`/v1/webhooks/{webhookId}`](https://docs.rocketverifier.com/api/webhooks#list-get-update-and-delete-webhooks) | Delete an endpoint. |
| POST | [`/v1/webhooks/{webhookId}/test`](https://docs.rocketverifier.com/api/webhooks#send-a-test-event) | Send a signed test event. |
| GET | [`/v1/webhooks/{webhookId}/logs`](https://docs.rocketverifier.com/api/webhooks#read-delivery-logs) | Read delivery attempts. |
| POST | [`/v1/webhooks/{webhookId}/rotate-secret`](https://docs.rocketverifier.com/api/webhooks#rotate-the-signing-secret) | Issue a new signing secret. |

### Tools and account

| Method | Path | What it does |
| --- | --- | --- |
| GET | [`/v1/tools/mx-lookup`](https://docs.rocketverifier.com/api/domain#look-up-mx-records) | MX records for a domain. |
| GET | [`/v1/tools/disposable-check`](https://docs.rocketverifier.com/api/domain#check-for-disposable-domains) | Is a domain or address disposable. |
| GET | [`/v1/tools/domain-auth`](https://docs.rocketverifier.com/api/domain#check-spf-dkim-and-dmarc) | SPF, DKIM and DMARC with a score. |
| GET | [`/v1/tools/blacklist-monitor`](https://docs.rocketverifier.com/api/domain#check-dns-blacklists) | DNS blacklist listings for a domain or IP. |
| POST | [`/v1/tools/verify-free`](https://docs.rocketverifier.com/api/domain#run-a-free-test-lookup) | Free syntax, MX and disposable lookup. |
| GET | [`/v1/tools/activity/{email}`](https://docs.rocketverifier.com/api/domain#read-your-verification-history-for-an-address) | Your own verification history of an address. |
| GET | [`/v1/credits`](https://docs.rocketverifier.com/api/credits) | Credit balance and usage. |
| GET | [`/v1/me`](https://docs.rocketverifier.com/api/account) | The account behind the credential. |
| GET | [`/v1/status`](#check-api-status) | API health. |

## Use an SDK

The official SDKs wrap every endpoint above with typed results, retries on `429` and automatic idempotency keys.

- [Node.js SDK](https://docs.rocketverifier.com/sdks/nodejs)
`npm install @rocketverifier/sdk`
- [Python SDK](https://docs.rocketverifier.com/sdks/python)
`pip install rocketverifier`
- [CLI](https://docs.rocketverifier.com/sdks/cli)
Verify addresses and lists from your terminal.
- [MCP server](https://docs.rocketverifier.com/mcp)
Give Claude, Cursor and other assistants the same tools.

## Frequently asked questions

### Is there a test mode?

Yes. Sandbox keys start with `rv_test_` and return fixed results for `@sandbox.rocketverifier.com` addresses on every verification endpoint, without spending credits. Live keys start with `rv_live_`.

### Can I send the API key in an X-API-Key header?

No. Every `/v1` endpoint reads the key from `Authorization Bearer` only. Requests that send the key any other way get `401 unauthorized`.

### How do I avoid double charges when I retry?

Send an `Idempotency-Key` header on `POST /v1/verify`, `POST /v1/verify/bulk` and `POST /v1/verify/bulk/upload`. A retry with the same key within 24 hours returns the original response and charges nothing. The official SDKs add one to every write automatically.

### Which endpoints work without an API key?

`GET /v1/status`, `GET /v1/webhooks/events` and the lookup tools under `/v1/tools` (except activity history). Calls without a key are limited to 5 per minute per IP address.
