The Serus API lets you integrate Serus security intelligence into your own systems. Use it to verify an API key, start darkweb scans, retrieve scan results, and stream findings as they are discovered.

Authentication

Every request must include a Serus API key in the Authorization header:

Authorization: Bearer ak_...

Create and manage API keys in the Serus dashboard at Settings → Developer → API Keys. When you create a key, choose the permissions it should have and copy the secret immediately — Serus only shows the secret once.

Keys can be edited, rotated, or revoked from the same page. Once you revoke a key, the next request with that key returns 401 invalid_api_key.

Versioning

The current API version is v1. All public endpoints are served from:

https://api.serus.ai/v1

We make additive changes within a major version. Existing endpoints, fields, and errors remain stable until the next major version. See the stability policy for details.

Getting Started

1. Sign in to the Serus dashboard.
2. Open Settings → Developer → API Keys.
3. Create a key with the permissions your integration needs.
4. Copy the key secret and store it securely.
5. Call GET /v1/hello to confirm the key works.

Track usage and credit spend in Settings → Developer → API Spend.

Credits

Some API operations consume Serus credits. Starting a new darkweb scan currently costs 0.25 credits. Reading scan results, revealing unmasked scan data, and verifying a key do not consume credits.

If the account or organization tied to the key does not have enough credits, paid endpoints return 402 insufficient_balance. Add credits in the dashboard before retrying.

Rate Limits

Rate limits are applied to the account or organization that owns the API key. Multiple keys for the same account share the same rate-limit allowance.

Limits are tiered by endpoint type and reset every second:

Responses include rate-limit headers:

When the limit is exceeded, the API returns 429 rate_limit_error with a standard Retry-After header (seconds to wait).

Errors

Errors return a consistent JSON envelope:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "API key is invalid, revoked, or expired",
    "request_id": "0193cf9b-..."
  }
}

Common status codes:

Permissions

Each Serus API key has one or more permissions. Permissions limit what the key can do. If a key calls an endpoint without the required permission, the API returns 403 feature_not_allowed with code: "scope_not_granted".

Choose permissions when creating or editing a key in Settings → Developer → API Keys.

In API responses these are exposed as the scopes array (for example, in GET /v1/hello) — same concept, kept under that name for OAuth/standards compatibility.

Available Permissions

Choosing Permissions

Use the smallest set of permissions your integration needs.

If a permission is not selectable in the dashboard, the current account or organization does not have access to it. Contact your Serus admin or support contact to enable it.

Quickstart

1. Create an API Key

Sign in to Serus and open Settings → Developer → API Keys.

Click Create key, give the key a recognizable name, choose the permissions your integration needs, and select an expiration. Copy the secret immediately after creation — Serus only shows the secret once.

For a first test, grant account:read. To run darkweb scans, grant darkweb:scan.

2. Verify the Key

Call GET /v1/hello to confirm the key is valid and see the permissions attached to it:

curl https://api.serus.ai/v1/hello \
  -H "Authorization: Bearer ak_..."

Example response:

{
  "subject": "org_3C1xG2fbP68VhAI6oCQl5s01ltf",
  "scopes": ["account:read", "darkweb:scan", "darkweb:read"],
  "credits_remaining": 1000
}

The subject field returns the ID of the Serus account or organization that owns this API key. Personal-account keys return a user ID prefixed with user_; organization keys return an organization ID prefixed with org_. The scopes array lists the permissions granted to the key — same concept as "permissions" in the dashboard, kept under the name scopes for OAuth/standards compatibility.

3. Start a Darkweb Scan

Use POST /v1/darkweb/scans to scan an identifier such as an email, phone number, username, domain, keyword, origin, or password:

curl https://api.serus.ai/v1/darkweb/scans \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{"identifierType":"email","identifierValue":"jane@example.com"}'

Example response:

{
  "id": "3DJ09m3jBkxrgA31nwfnqdWSBxI",
  "status": "processing",
  "identifierType": "email"
}

Store the id. You will use it to retrieve results.

4. Fetch Results

Poll GET /v1/darkweb/scans/{scanId} until the scan reaches success or failed:

curl https://api.serus.ai/v1/darkweb/scans/3DJ09m3jBkxrgA31nwfnqdWSBxI \
  -H "Authorization: Bearer ak_..."

By default, sensitive breach values are masked. To retrieve unmasked values, call the same endpoint with ?reveal=true using a key that has darkweb:reveal.

5. Monitor Usage

Open Settings → Developer → API Spend to review credit usage by key, feature, and time range. If paid API requests return 402 insufficient_balance, add credits in the dashboard before retrying.

Stability Policy

Serus API versions are designed to be stable for external integrations. We make additive changes within a major version. Existing endpoints, fields, and errors remain stable until the next major version.

Changes We May Make Without Notice

These changes should not break tolerant clients:

Changes We Avoid Within A Major Version

Breaking Changes

Breaking changes ship in a new major version such as /v2. When that happens, the previous major version remains supported for a migration window so integrations can move safely.