Migrate an integration to the editions release

The editions release changes how the API authenticates callers, how it limits them, and the contract of a few endpoints. This page lists every change that affects an integration built against the current production API, and what to update. Each section gives the old behavior, the new behavior, and the guide that covers the topic in full. The page ends with a checklist to run against https://client-api.leak.center once the release is live.

What changes for your integration

If your integration…	What changes	Section
Sends an `Authorization` header	Every request carries an API key in `X-API-Key`	Authenticate with an API key
Sends `org_id`, or serves several client organizations from one credential	A key acts only as its own organization	Act as one organization per key
Reads `license`, `used_credits` or `country.id`, or stores country IDs	The organization profile drops two fields and uses country codes	Read organization data
Tracks credits, paces on per-endpoint daily limits, or expects `402`	Plan features, allowances and capacity slots replace credits and daily limits	Plans replace credits and daily limits
Parses error bodies, or retries every `429`	New `403`, `409` and `429` refusals, and `detail` bodies	Handle the new refusals
Calls `city_list` or `leak_analysis_general_stats`	These routes return `404`	Replace removed endpoints
Calls `start_domain_analysis`	`modules` is ignored, the domain must be a registered asset, and each domain takes a slot	Start Domain monitoring scans
Reads quick search or Telegram search results	The Data Brokers entry answers inline, two new statuses, and `total_is_estimate`	Read quick search and Telegram results
Creates monitors, webhooks, email senders or email templates	Capacity `409`, per-source `403`, and plan-gated delivery settings	Create monitors and set up delivery

Authenticate with an API key

	Before	After
Credential	An `Authorization` header	An API key, sent as `X-API-Key` on every request
Renewal	Renewed before it expires	None. A key works until it expires or you revoke it
Where it comes from	A dashboard user account	Manage → API tokens in the dashboard

To switch:

Create a key

Sign in to the dashboard as an Org Admin or System Admin. Open Manage → API tokens, click Create token, and copy the key from the Save your API token dialog. The key starts with dnst_ and is shown once. Your plan must include an API Calls allowance, or the page offers no Create token button.

Switch to the X-API-Key header

Send the key in the X-API-Key header on every request, and remove the Authorization header everywhere. The API reads Authorization before X-API-Key, so a leftover header decides which account the request acts as, or fails the request with 401.

Confirm the key

Call get_direct_org_info. A 200 with your organization’s id and name confirms the key works and acts as the organization you expect.

curl https://client-api.leak.center/api/service/get_direct_org_info/ \
  -H "X-API-Key: YOUR_API_KEY"

A request with no key returns 401 with {"detail": "Authentication credentials were not provided."}. An unknown, expired or revoked key returns 401 with {"detail": "Invalid or expired API key."}. Store the key in a secret manager, never in source code. Authentication covers expiry, revocation and replacing a key without downtime.

Act as one organization per key

	Before	After
Choosing the organization	One credential could act for several organizations. An `org_id` query parameter or body field picked the client organization	An API key acts only as the organization it was created for
Clients	Loop over client IDs with one credential	Register clients’ assets in your own organization and use its key, or use one key per client workspace

To switch:

Remove org_id from every query string and request body. A key needs no organization parameter.
Expect 403 for another organization. A request that names any organization other than the key’s own returns 403 with {"detail": "You don't have access to this organization"}.
Serve clients from your own organization, or create a key per client workspace. Most partners register each client’s domains and other assets in their own organization, which the dashboard calls a workspace, and use one key for all of them. A client workspace that the client signs in to is a separate organization: as a System Admin, pick it in the workspace switcher at the top of the dashboard sidebar, open Manage → API tokens and create the key there. It belongs to that client workspace. Store a key per client workspace and pick the key, not a parameter. See Client organizations.
A client workspace’s plan applies to its key. A client workspace key gets that workspace’s plan features and allowances, and its requests count toward its API Calls allowance, not yours.
List clients from your own records. With a key, organization_list returns a one-item array with the key’s own organization. organization_info/{org_id} answers only for that organization’s id and returns 404 for any other.

Read organization data

get_direct_org_info, organization_info and organization_list return a smaller profile.

Field	Before	After
`license`	License ID, dates, features, `max_assets` and `is_active`	Removed
`used_credits`	Credits used	Removed
`country`	`{id, name}`, always present	`{code, name}`. `code` is the ISO 3166-1 alpha-2 code, such as `US`. `null` when no valid country is set

{
  "id": 412,
  "name": "Acme Corp",
  "domain": "acme.com",
  "country": { "code": "US", "name": "United States" }
}

The response is trimmed here. Read an organization’s profile lists every field.

Country lookups use codes. country_list returns {code, name} instead of {id, name}, with ISO country names. If you store country IDs, map them to codes once: take each stored country’s name, match it to a name in the new list, and keep the code. ISO names can differ from the names you stored.
No license field replaces license. Your plan is in the dashboard under Manage → Buy more, and your usage under Manage → Usage. At call time, the refusals in Handle the new refusals tell you what the plan does not cover.

Plans replace credits and daily limits

	Before	After
Credits	Calls drew credits, shown as `used_credits`. A spent balance returned `402`	No credits and no `402`
Per-endpoint limits	Each endpoint had a daily limit on top of account-wide caps	No per-endpoint limits
Request rate	Account-wide caps per second and per month	A per-second rate limit for every caller, and a monthly API Calls allowance for API-key requests. Only `2xx` responses use the allowance
What a plan controls	License features	Plan features, metered allowances and capacity slots
`X-RateLimit-*` headers	The tightest of your account-wide and per-endpoint limits	The tightest of your limits, usually the per-second window

Every request now passes these checks:

Check	Applies to	Refusal
License in force	Nearly every endpoint. The organization profile reads still answer	`403`
Plan feature	Endpoints for a source or feature your plan may not include	`403`
Per-second rate limit	Every request	`429`, retry after 1 second
API Calls allowance	Every request made with an API key	`429` until the allowance resets
Metered allowance	Calls that start metered work	`429` until the period resets
Capacity slot	Calls that create a monitor, add a domain to Domain monitoring, or activate a report schedule	`409`

Rate limits explains the per-second limit and the API Calls allowance. Plans and quotas explains plan features, allowances and slots.

Plan features

These areas need a feature in your plan. Without it, the endpoints return 403 with {"detail": "This feature is not included in your plan."}.

If you call…	Your plan needs	Guide
Paste search	Paste Leaks	Pastes
Credit card search (`cc_leaks_search`)	Credit Card Exposure	Credit cards
Cloud storage search	Cloud Storage Exposure	Cloud storage
URL shortener search	URL Shortener Abuse	URL shorteners
App store search	App Store Impersonation	App stores
Telegram or Discord search	Telegram/Discord Monitoring	Telegram, Discord
Ransomware victims and groups	Ransomware Threat Actor Monitoring	Threat actor publications
Tor & I2P live search	Onion Search	Live search
Email References live search	Email Exposure (Surface Web)	Live search
Live Data Broker Search	Live Data Broker	Live Data Broker Search
Code exposure	Exposed Code Detection	Code exposure
Domain monitoring	Domain Monitoring	Domain monitoring
Infra search	Attack Surface Mapping	Infra search
Generating credential comparison reports (`generate_credential_comparison_report`)	Credential Report	Credential comparison reports
Webhooks	Webhooks	Delivery
Creating, updating or deleting email senders and templates	Custom Email Server	Delivery

Monitors check the data source of each rule. See Create monitors and set up delivery.

Metered allowances

These calls take units from a monthly allowance before the work starts. A call that ends in any status other than 2xx gets its units back. Allowances reset at 00:00 UTC on the 1st of each month.

Work	Endpoint	Allowance (`resource`)	Units per call
Infra search scan	`create_infra_search_request`	Attack Surface Mapping (`infra_search_scan`)	1
Credential comparison report	`generate_credential_comparison_report`	Credential Report (`credential_report`)	1
Live Data Broker Search	`live_search_create`	Live Data Broker (`hacker_forum_live_search`)	1
Code exposure keyword scans	`POST /api/code_scan/keyword_scans/`	Code Exposure Keywords (`code_exposure_keyword_search`)	1 per distinct keyword in the request
Code exposure contributor scan	`POST /api/code_scan/contributor_scans/`	Code Exposure Contributors (`code_exposure_contributor_search`)	1

Endpoints that are new in this release, such as Attack Surface assessments and domain takedowns, state their allowances in their own guides: Start an assessment and Domain takedowns.

Capacity slots

Some resources have a fixed number of slots. Creating one more than the plan allows returns 409.

Slot (`resource`)	Taken by	Freed by
Monitored Assets (`monitored_assets`)	Each monitor, and each distinct domain you scan	Deleting the monitor, or every analysis of that domain
Scheduled reports (`automated_reports`)	Each active credential comparison report schedule	Deactivating the schedule

Creating an inactive report schedule takes no slot. Activating it later with update_report_schedule does.

Handle the new refusals

Authentication, license, plan, capacity and allowance refusals now carry a detail field. The rate-limit 429 keeps message. Four new kinds of refusal appear.

Before	After
`401` with `{"error": "Authentication failed."}`	`401` with `detail`, such as `{"detail": "Invalid or expired API key."}`
`403` with a `message` field, such as `{"message": "Access denied"}`	`403` with `detail`. See the table below
`402` when credits ran out	No `402`. Metered work returns the allowance `429`
`429` from a per-endpoint daily limit	`429` from the per-second rate limit or the API Calls allowance

The new refusals:

Status	Body	Cause	What your integration does
`403`	`{"detail": "Your license is not active."}`	Your organization, or its parent organization, has no license in force	Stop and report it. Retrying fails the same way
`403`	`{"detail": "This feature is not included in your plan."}`	The endpoint or data source needs a plan feature you do not have	Skip that source. On an endpoint that needs a plan feature, a license that is not in force returns this same message
`409`	`{"detail": "You have reached your Monitored Assets limit of 50.", "resource": "monitored_assets", "limit": 50}`	Every slot of that resource is in use	Free a slot, or raise the plan’s capacity. Retrying fails until then
`429`	`{"detail": "You have reached your Credential Report limit for this month.", "resource": "credential_report", "period": "month", "limit": 5}`	The metered allowance is spent for the period	Do not retry. Queue the work for the next period. There is no `Retry-After` header
`429`	`{"message": "Rate limit exceeded", "retry_after_seconds": 1}`	The per-second rate limit	Wait for `Retry-After`, then retry
`429`	The same, plus `limit`, `remaining` and `reset_at`	The API Calls allowance is used up	Queue API-key requests until `reset_at`

Where the API reports a license refusal, detail begins with “Your license is not active.” Some endpoints add a sentence after it.

Do not retry every 429. Tell them apart by the body: an allowance 429 has resource and period, a rate-limit 429 has retry_after_seconds. Only the per-second 429 clears within seconds.

A refusal from the license, plan or rate-limit check uses no API call, and an allowance or capacity refusal is refunded. Errors lists every error body the API returns.

Replace removed endpoints

Two routes are removed and return 404.

Before	After
`GET /api/service/city_list/`	None. `country_list` remains, and returns country codes
`GET /api/service/leak_analysis_general_stats/`	None. For credential counts, call `leaked_credentials_stats`, described in Summarize an organization’s credential exposure. For counts from other sources, run a quick search

Start Domain monitoring scans

Domain monitoring is the API tag SpoofGuard. start_domain_analysis has a new contract.

	Before	After
Required fields	`domain` and `modules`	`domain` only
Detection modules	You chose them in `modules`	Domain monitoring picks them. `modules` is ignored and the call still succeeds
`domain`	Any domain	A domain registered as an asset of your organization. A subdomain must be registered as its own asset
Optional fields	`config`, `custom_domains`, `ttl`	Also `logo_id`, `branding_id`, `whitelist_id` and `wordlist_code`

The call also has two new refusals:

Plan feature. Without the Domain Monitoring plan feature, it returns 403 with {"detail": "This feature is not included in your plan."}.
Monitored Assets slots. Each distinct domain you scan takes one Monitored Assets slot, from the same pool as your monitors. When every slot is taken, the call returns 409.

Two optional fields switch on modules: a logo_id adds Google Lens, and a wordlist_code adds domain word combination. Create logos, branding keyword sets, whitelists and word lists first, then pass their IDs. See Set up a brand library.

curl https://client-api.leak.center/api/service/start_domain_analysis/ \
  -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "acme.com", "logo_id": 7}'

A domain that is not a registered asset returns 400:

{
  "domain": ["'acme-login.com' is not a registered domain asset. Subdomains must be registered as their own asset."]
}

Register domains with organization_assets_create or in the dashboard under Manage → Assets. When every Monitored Assets slot is taken, the call returns 409:

{
  "detail": "You have reached your Monitored Assets limit of 10.",
  "resource": "monitored_assets",
  "limit": 10
}

Scan an organization’s domain for look-alikes covers the flow.

Read quick search and Telegram results

The quick search Data Brokers entry answers inline

	Before	After
Entry in `result`	`hf_search_request`	`data_broker_search`
Status	`submitted`, with a `task_id` to poll through `retrieve_hacker_forum_task_results`	`ok`, with the listings in `data`
Search term	The term you sent	The name without its top-level domain, for example `acme` for `acme.com`

{
  "result": {
    "data_broker_search": {
      "status": "ok",
      "data": {
        "items": [],
        "total": 0,
        "next_cursor": null,
        "q": "acme"
      }
    }
  }
}

The response is trimmed to the one entry, and data to a few fields. items holds listings in the shape data_broker_search returns. Stop polling a forum task for the Data Brokers entry. Data Brokers describes the listings.

Two new source statuses

A source your plan excludes, or that a limit refuses, no longer reports submission_failed. It reports one of two new statuses, and the rest of the search goes on.

Status	Cause	Extra fields
`not_entitled`	Your plan does not include that source	`error_message`
`quota_exceeded`	A limit refused that source: its allowance is spent (with `resource`, `period`, `limit`), or the per-second rate limit was hit (without them)	`error_message`, plus `resource`, `period`, `limit` for an allowance

{
  "result": {
    "paste-search-create": {
      "status": "not_entitled",
      "error_message": "This feature is not included in your plan."
    }
  }
}

Treat both as final for that source. Neither uses an allowance unit. Search across all data sources lists every status.

Telegram totals can be estimates

telegram-search-create returns a new boolean, total_is_estimate. When it is true, total is an estimate, not an exact count, so do not present it as exact. Discord search already returned the same field. See Telegram.

Create monitors and set up delivery

A monitor is an alert rule in the API.

	Before	After
Limit on monitors	`400` with `"You have reached your alert rule limit of 100."`	`409` when every Monitored Assets slot is in use. One monitor takes one slot, and deleting it frees the slot
Data source	Any source	Create and update check the rule’s `service` against your plan, and return `403` when the plan lacks that source
Webhooks	Open	All five webhook endpoints need the Webhooks plan feature
Email senders and templates	Open	Create, update and delete need the Custom Email Server plan feature. Reading them needs no plan feature

alert_system_alert_create_alert_rule refuses the create before it reaches the monitoring service when every slot is in use:

{
  "detail": "You have reached your Monitored Assets limit of 50.",
  "resource": "monitored_assets",
  "limit": 50
}

The plan feature each data source needs:

Data source	Plan feature
Credit cards, and BIN and CVV	Credit Card Exposure
Pastes	Paste Leaks
Ransomware	Ransomware Threat Actor Monitoring
Hacker forums	Hacker Forum Access
Cloud storage	Cloud Storage Exposure
URL shorteners	URL Shortener Abuse
App stores	App Store Impersonation
Telegram and Discord	Telegram/Discord Monitoring

Every other source is in every plan. A rule whose service is missing or unknown also returns 403. Create and manage monitors and Delivery cover the rest.

Check the integration after the cut-over

Once the release is live at https://client-api.leak.center, run each check with your API key.

curl https://client-api.leak.center/api/service/get_direct_org_info/ \
  -H "X-API-Key: YOUR_API_KEY"

Check	It passes when
No request sends `Authorization`, and every request sends `X-API-Key`	`get_direct_org_info` returns `200` and your organization’s `id`
No request sends `org_id`	Your calls return `200` for your own organization. Each client key returns that client in `get_direct_org_info`
Your parser no longer reads `license`, `used_credits` or `country.id`	The profile parses, and `country.code` is a two-letter code or `country` is `null`
Stored country IDs are mapped to codes	Every stored country matches a `code` in `country_list`
Your error handler reads `detail`	A `403` and a `409` reach your handler with their `detail` text
Your retry logic tells the `429`s apart	An allowance `429` (with `resource`) is queued, not retried. A rate-limit `429` is retried after `Retry-After`
Each source you call is in your plan	No call returns `403` with “This feature is not included in your plan.”, or your integration skips that source when it does
Code exposure uses `/api/code_scan/`	A keyword scan start returns `201` with `scans`, and an export with `?file_format=csv` returns a file
`start_domain_analysis` sends only `domain` and the optional IDs	A registered domain returns `200`. An unregistered one returns `400`
Quick search reads `data_broker_search` inline	The entry has `status` `ok` and `data`. `not_entitled` and `quota_exceeded` entries do not stop the run
Telegram reads `total_is_estimate`	A `true` value is shown as an estimate
Monitor creation handles `409` and `403`	A create at full capacity, or for a source outside your plan, is reported and not retried

Endpoints

Action	Endpoint
Confirm which organization a key acts as	`get_direct_org_info`
Read the key’s organization by ID	`organization_info/{org_id}`
List the key’s organization	`organization_list`
Look up country codes	`country_list`
Start code exposure keyword scans	`POST /api/code_scan/keyword_scans/`
Start a code exposure contributor scan	`POST /api/code_scan/contributor_scans/`
Export keyword scan results	`GET /api/code_scan/keyword_scans/{scan_id}/export/`
Read credential counts	`leaked_credentials_stats`
Start a Domain monitoring scan	`start_domain_analysis`
Run a quick search on a domain	`domain_quick_search`
Search data broker listings	`data_broker_search`
Search Telegram	`telegram-search-create`
Create a monitor	`alert_system_alert_create_alert_rule`
Delete a monitor and free its slot	`alert_system_alert_delete_alert_rule`
Generate a credential comparison report	`generate_credential_comparison_report`
Create a credential comparison report schedule	`create_report_schedule`

Get started

Search

Leaked credentials

Assess & report

Monitors

Domain monitoring

Downloads & exports

Changelog

Migrate an integration to the editions release

What changes for your integration

Authenticate with an API key

Act as one organization per key

Read organization data

Plans replace credits and daily limits

Plan features

Metered allowances

Capacity slots

Handle the new refusals

Replace removed endpoints

Start Domain monitoring scans

Read quick search and Telegram results

The quick search Data Brokers entry answers inline

Two new source statuses

Telegram totals can be estimates

Create monitors and set up delivery

Check the integration after the cut-over

Endpoints

​What changes for your integration

​Authenticate with an API key

​Act as one organization per key

​Read organization data

​Plans replace credits and daily limits

​Plan features

​Metered allowances

​Capacity slots

​Handle the new refusals

​Replace removed endpoints

​Start Domain monitoring scans

​Read quick search and Telegram results

​The quick search Data Brokers entry answers inline

​Two new source statuses

​Telegram totals can be estimates

​Create monitors and set up delivery

​Check the integration after the cut-over

​Endpoints

What changes for your integration

Authenticate with an API key

Act as one organization per key

Read organization data

Plans replace credits and daily limits

Plan features

Metered allowances

Capacity slots

Handle the new refusals

Replace removed endpoints

Start Domain monitoring scans

Read quick search and Telegram results

The quick search Data Brokers entry answers inline

Two new source statuses

Telegram totals can be estimates

Create monitors and set up delivery

Check the integration after the cut-over

Endpoints