Admin API: blocklist registries

Eight methods manage the same things as the Settings → PL registry («Настройки → Реестр PL») tab: lists of blocked domains, checking them and the auto-replacement log. All methods require a token with Full access («Полный доступ») (full).

Authorization is described on the Admin API: overview and authorization page, and the request format and common error codes on the Request, response and error format page. How auto-replacement works is described on the Blocklist registry (PL) and automatic domain replacement page.

Registry object

The list, create, update and check methods return a registry in this form:

{
  "id": "5b1f0c1e-6f0a-4d0e-9a3b-2c7d8e9f0a11",
  "workspace_id": "0d9c8b7a-1234-4abc-8def-001122334455",
  "name": "PL registry",
  "url": "https://registry.example.com/domains.txt",
  "geo": "PL",
  "enabled": true,
  "auto_replace": true,
  "interval_min": 30,
  "reserve_group_id": "7a6b5c4d-3e2f-4a1b-8c9d-0e1f2a3b4c5d",
  "last_fetch_at": "2026-10-04T09:30:00Z",
  "last_error": "",
  "entry_count": 48213,
  "created_at": "2026-10-01T12:00:00Z"
}

Registries

List registries

GET /api/v1/blocklist-sources

Returns all of the team's registries. No parameters.

Response — code 200 and an array of registry objects sorted by creation date, oldest first. If there are no registries, an empty array is returned.

Add a registry

POST /api/v1/blocklist-sources

Creates a registry. The tracker checks an enabled registry on its own on schedule; to avoid waiting, call the check.

Response — code 201 and a registry object.

curl -X POST https://panel.example.com/api/v1/blocklist-sources \
  -H "Api-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"PL registry","url":"https://registry.example.com/domains.txt","geo":"PL","interval_min":30,"reserve_group_id":"7a6b5c4d-3e2f-4a1b-8c9d-0e1f2a3b4c5d"}'

Errors:

Edit a registry

PUT /api/v1/blocklist-sources/{id}

Replaces the registry's settings. {id} is the registry ID.

The body has the same fields as on creation; url is required. The record is replaced as a whole, so pass all fields, not only the changed ones:

• without name, the name becomes empty;
• without enabled and auto_replace, both switches are turned on;
• without interval_min, the interval becomes 30;
• without reserve_group_id, the reserve group is reset;
• without geo or with an empty string, the country code stays the same.

Response — code 200 and a registry object. The last_fetch_at, last_error and entry_count fields are kept on update.

Errors — the same as on creation, plus 404 not_found if there is no registry with this {id}, and 400 bad_request if {id} is not in UUID format.

Delete a registry

DELETE /api/v1/blocklist-sources/{id}

Deletes a registry. The replacement log entries remain.

Response — code 204 with no body. If there is no such registry, you get 404 not_found; if {id} is not in UUID format, 400 bad_request.

Check and test fetch

Both methods are subject to a rate limit.

Check a registry now

POST /api/v1/blocklist-sources/{id}/check

Downloads the list, compares the domains against it and, if the registry has auto-replacement enabled, replaces domains in streams. The Check («Проверить») button in the registry's row does the same. The method also works for a registry with enabled: false. No request body is needed.

The response comes after the check finishes — code 200 and a registry object with updated last_fetch_at, entry_count and last_error.

Code 200 does not mean the check passed without remarks. Read last_error: it keeps a warning, for example автозамена не выполнена: не выбрана резервная группа доменов — менять не на что (auto-replacement not performed: no reserve domain group selected — nothing to replace with). The messages are covered in the If something went wrong section.

Errors:

Examples of message with code 502:

• реестр ответил 404 Not Found (the registry responded 404 Not Found) — the list server returned a code other than 200;
• ответ реестра больше 64 МиБ — принимать нельзя, снимок был бы неполным (the registry response is larger than 64 MiB — it cannot be accepted, the snapshot would be incomplete);
• в ответе реестра не найдено ни одного домена — источник отдал не тот формат или заглушку (no domains found in the registry response — the source returned the wrong format or a placeholder);
• Get "https://registry.example.com/domains.txt": … — a network error; its text follows the colon, for example слишком много редиректов (too many redirects).

Test-fetch a list

POST /api/v1/blocklist-sources/test

Downloads the list from the address and shows what was recognized in it and which of the team's domains it contains. Saves and changes nothing. In the panel, this is the Check button next to the List URL («Адрес списка») field.

Response — code 200:

curl -X POST https://panel.example.com/api/v1/blocklist-sources/test \
  -H "Api-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://registry.example.com/domains.txt"}'

{
  "total": 48213,
  "sample": ["blocked-one.example", "blocked-two.example"],
  "matched": ["go.example.com"]
}

If total is 0, there is no list of domains in a recognizable format at the address.

Errors:

Replacement log

List replacements

GET /api/v1/domain-replacements

Returns entries about automatic domain replacements in streams, newest first.

Response — code 200 and an array of entries. If there were no replacements, an empty array is returned.

Roll back a replacement

POST /api/v1/domain-replacements/{id}/revert

Puts the previous domain back into the stream and removes its “in the registry” mark. {id} is the log entry ID. No request body is needed.

Only the domain changes in the stream's link. The log entry gets reverted: true. If the domain is still in the list, the next check will mark and replace it again.

Response — code 204 with no body.

Errors:

Rate limit

POST /api/v1/blocklist-sources/{id}/check and POST /api/v1/blocklist-sources/test accept no more than 10 requests per minute from one IP address. The counter is shared by both methods. It also counts clicks on the Check button in the panel from the same IP address, as well as license activation requests and saving IP2Proxy settings. When the limit is exceeded, code 429 is returned:

{"code": "rate_limited", "message": "слишком много запросов, попробуйте позже"}

The message means “too many requests, try again later”. Try again in a minute. The limit does not apply to the other methods in the group.