Методы API

Все методы серверного API: параметры, поля ответа, примеры запросов. Рядом с описанием каждого метода — пример запроса и ответа. Все адреса — относительно https://agent-mark.ru.

Найти упоминания

POST/api/find

1 проверка на 20 000 символовсекретный ключ

Находит в тексте упоминания людей и организаций из реестров и возвращает их позиции. Текст не меняется — удобно подсветить найденное в редакторе или проверить статью перед публикацией. Текст — обычный, без HTML.

Тело запроса

Поле	Тип	Описание
`text` обязательно	строка	Текст до 1 000 000 символов.
`registries`	список строк	Какие реестры искать: `foreign_agents`, `undesirable`, `extremist`, `terrorist`, `rfm_organizations`, `rfm_persons`, `narcotics`. Без поля — все реестры с пометками, а перечень наркотиков — если подключена доп. услуга. `narcotics` без услуги не ищется. Реестры, не входящие в тариф сайта, не ищутся и при явном указании — какие входят.

Ответ

Список упоминаний в порядке появления в тексте:

Поле	Тип	Описание
`start`, `end`	число	Позиции в тексте: номера символов с нуля, `end` не включается — подробнее.
`text`	строка	Упоминание как в тексте: «Екатериной Шульман».
`registry`	строка	Код реестра.
`entry_type`	строка	`person` — человек, `organization` — организация, `substance` — вещество из перечня наркотиков.
`name`	строка	Запись как в реестре: «Шульман Екатерина Михайловна».
`variant`	строка	Вариант имени или названия, по которому найдено: «Екатерина Шульман», «ФБК», псевдоним или прежняя фамилия.
`strong`	да / нет	`true` — полное имя или название; `false` — короткая форма (одна фамилия), принятая потому, что в этом же тексте тот же человек упомянут полностью.

Ошибки: 401 — ключ, 403 — нет тарифа и пакета проверок или проверки на месяц закончились, 422 — текст длиннее лимита или неизвестный реестр, 503 — словарь обновляется. Все ошибки.

Запрос

curl https://agent-mark.ru/api/find \
  -H "Authorization: Bearer sk_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"text": "Интервью с Екатериной Шульман о выборах. ФБК опубликовал расследование."}'

import requests

r = requests.post("https://agent-mark.ru/api/find",
    headers={"Authorization": "Bearer sk_ваш_ключ"}, timeout=60,
    json={"text": "Интервью с Екатериной Шульман о выборах. "
                  "ФБК опубликовал расследование."})
for m in r.json():
    print(m["start"], m["end"], m["text"], m["registry"])

Ответ

[
  {
    "start": 11, "end": 29, "text": "Екатериной Шульман",
    "registry": "foreign_agents", "entry_type": "person",
    "name": "Шульман Екатерина Михайловна",
    "variant": "Екатерина Шульман", "strong": true
  },
  {
    "start": 41, "end": 44, "text": "ФБК",
    "registry": "extremist", "entry_type": "organization",
    "name": "Некоммерческая организация «Фонд борьбы с коррупцией»",
    "variant": "ФБК", "strong": true
  }
]

Разметить текст

POST/api/mark

1 проверка на 20 000 символовсекретный ключ

Размечает HTML или обычный текст: вставляет значки, статус в скобках и блок сносок по закону, а при доп. услуге — предупреждение о вреде наркотиков перед текстом. Незаданные параметры берутся из настроек сайта в кабинете. HTML не перестраивается — только вставки; уже размеченный текст можно отправлять повторно.

Тело запроса

Поле	Тип	Описание
`content` обязательно	строка	HTML или текст до 1 000 000 символов.
`format`	строка	`html` (по умолчанию) или `text` — обычный текст: значок после упоминания, сноски строками.
`style`	строка	Вид пометки: `footnote` — значок и сноски, `inline` — статус в скобках, `both` — то и другое.
`mark_every`	да / нет	Значок у каждого упоминания (`true`) или только у первого.
`numbering`	строка	`asterisk` — звёздочка у всех сносок, `numbers` — номера 1, 2, 3.
`inline_red`, `inline_italic`	да / нет	Статус в скобках красным цветом и курсивом (только в HTML, атрибутом `style`).
`registries`	список строк	Какие реестры размечать — коды как у `/api/find`; реестры, не входящие в тариф сайта, не размечаются. `narcotics` здесь не действует: предупреждение включается полем `warning`.
`warning`	да / нет	Предупреждение о вреде наркотиков перед текстом. По умолчанию — если подключена доп. услуга; `false` — не ставить (например, в анонсе). Без услуги не ставится и при `true`.
`url`	строка	Адрес страницы, где будет текст, до 2000 символов. На ней не размечаются однофамильцы, исключённые в кабинете (тариф «медиа»).

Ответ

Поле	Тип	Описание
`content`	строка	Размеченный HTML или текст — что вставляется.
`mentions`	список	Все найденные упоминания, как у `/api/find`, включая те, что пометки не получили (например, автор пометил сам). Для HTML позиции — по видимому тексту.
`footnotes`	список	Сноски: `marker` — значок («*» или номер), `label` — имя в сноске, `registries` — коды реестров, `text` — текст сноски без точки.
`warning`	строка	Текст поставленного предупреждения о вреде наркотиков; пустая строка — не ставили.

Ошибки: 401 — ключ, 403 — нет тарифа и пакета проверок или проверки на месяц закончились, 413 — тело больше 2 МБ, 422 — поле запроса, 503 — словарь обновляется. Все ошибки.

Запрос

curl https://agent-mark.ru/api/mark \
  -H "Authorization: Bearer sk_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<p>Интервью с Екатериной Шульман о выборах.</p><p>ФБК опубликовал расследование.</p>",
    "url": "https://example.ru/news/1"
  }'

import requests

html = ("<p>Интервью с Екатериной Шульман о выборах.</p>"
        "<p>ФБК опубликовал расследование.</p>")
r = requests.post("https://agent-mark.ru/api/mark",
    headers={"Authorization": "Bearer sk_ваш_ключ"}, timeout=60,
    json={"content": html, "url": "https://example.ru/news/1"})
marked = r.json()["content"]   # сохранить вместо исходного HTML

Ответ

{
  "content": "<p>Интервью с Екатериной Шульман<sup class=\"am-mark\" title=\"Екатерина Шульман — иностранный агент\">*</sup> о выборах.</p><p>ФБК<sup class=\"am-mark\" title=\"ФБК — организация признана экстремистской, её деятельность запрещена в России\">*</sup> опубликовал расследование.</p><div class=\"am-footnotes\"><p>* Екатерина Шульман — иностранный агент.</p><p>* ФБК — организация признана экстремистской, её деятельность запрещена в России.</p></div>",
  "mentions": [
    {"start": 12, "end": 30, "text": "Екатериной Шульман", "registry": "foreign_agents",
     "entry_type": "person", "name": "Шульман Екатерина Михайловна",
     "variant": "Екатерина Шульман", "strong": true},
    {"start": 43, "end": 46, "text": "ФБК", "registry": "extremist",
     "entry_type": "organization",
     "name": "Некоммерческая организация «Фонд борьбы с коррупцией»",
     "variant": "ФБК", "strong": true}
  ],
  "footnotes": [
    {"marker": "*", "label": "Екатерина Шульман", "registries": ["foreign_agents"],
     "text": "Екатерина Шульман — иностранный агент"},
    {"marker": "*", "label": "ФБК", "registries": ["extremist"],
     "text": "ФБК — организация признана экстремистской, её деятельность запрещена в России"}
  ],
  "warning": ""
}

Статус в скобках

"style": "inline" — та же статья:

<p>Интервью с Екатериной Шульман <span class="am-inline" style="color:#c4382b">(иностранный агент)</span> о выборах.</p><p>ФБК <span class="am-inline" style="color:#c4382b">(организация признана экстремистской, деятельность запрещена в РФ)</span> опубликовал расследование.</p>

Сведения о сайте

GET/api/site

проверкой не считаетсясекретный ключ

Сайт, которому принадлежит ключ: домены, настройки пометок, доп. услуги и версия словаря. Так плагины раз в час узнают, что пометки пора пересчитать; так же удобно проверить, что ключ работает.

Поля ответа

Поле	Тип	Описание
`public_key`	строка	Публичный ключ сайта для виджета.
`domains`	список строк	Домены сайта из кабинета.
`settings`	объект	Настройки пометок: `style`, `mark_every`, `numbering`, `inline_red`, `inline_italic`, `registries`, `allow_subdomains` — как в кабинете.
`addons`	список строк	Действующие доп. услуги: `narcotics` — предупреждение о вреде наркотиков.
`tariff`	строка или null	Код действующего тарифа сайта: `start`, `standard`, `media`. `null` — тарифа нет: виджет пометок не ставит, API работает только из пакетов проверок.
`dictionary_version`	число	Версия разметки для этого сайта. Сравнивайте только на равенство: меняется, когда обновились реестры, изменились настройки пометок, тариф, доп. услуга или исключения однофамильцев — тогда сохранённые пометки нужно пересчитать.
`dictionary_updated_at`	число	Unix-время последней пересборки словаря — чтобы показать людям.
`widget_url`	строка	Адрес скрипта виджета.

Запрос

curl https://agent-mark.ru/api/site \
  -H "Authorization: Bearer sk_ваш_ключ"

Ответ

{
  "public_key": "pk_6f2c…",
  "domains": ["example.ru"],
  "settings": {
    "style": "footnote", "mark_every": true, "numbering": "asterisk",
    "inline_red": true, "inline_italic": false,
    "registries": ["foreign_agents", "undesirable", "extremist",
                   "terrorist", "rfm_organizations", "rfm_persons"],
    "allow_subdomains": false
  },
  "addons": ["narcotics"],
  "tariff": "media",
  "dictionary_version": 2893746012,
  "dictionary_updated_at": 1761102000,
  "widget_url": "https://agent-mark.ru/widget.js"
}

Сводка по реестрам

GET/api/registries

без ключапроверкой не считается

Сколько действующих записей в каждом реестре и когда он в последний раз успешно синхронизировался. Подходит для мониторинга и для подписи «данные на …» на вашем сайте.

Поля ответа

Поле	Тип	Описание
`registry`	строка	Код реестра.
`active`	число	Действующих записей.
`last_sync`	дата и время или null	Последняя успешная синхронизация, ISO 8601 в UTC; `null` — ещё не было.

Запрос

curl https://agent-mark.ru/api/registries

Ответ

[
  {"registry": "foreign_agents", "active": 1282,
   "last_sync": "2026-10-22T00:01:12.483915+00:00"},
  {"registry": "extremist", "active": 150,
   "last_sync": "2026-10-22T00:01:20.117204+00:00"},
  …
]

Разметка для виджета

POST/api/widget/mark

публичный ключтолько из браузера с домена сайтаформат может меняться

Служебный метод JS-виджета: по видимому тексту страницы возвращает план — после каких позиций вставить пометки. Описан для понимания, как работает виджет; для своих интеграций используйте /api/mark. Запрос принимается только с заголовком Origin домена сайта; виджет отправляет JSON с типом text/plain, чтобы браузер не делал предварительный запрос OPTIONS.

Тело запроса

Поле	Тип	Описание
`key` обязательно	строка	Публичный ключ `pk_…`.
`text` обязательно	строка	Видимый текст страницы до 200 000 символов.
`url`	строка	Адрес страницы — для исключений однофамильцев.

Поля ответа

Поле	Тип	Описание
`style`	строка	Вид пометки из настроек сайта.
`inline_css`	строка	Стиль статуса в скобках: `color:#c4382b` и т. п.
`warning`	строка	Предупреждение перед текстом или пустая строка.
`footnotes`	список	`marker`, `label`, `text` — как у `/api/mark`.
`insertions`	список	Пометки: `end` — позиция в единицах UTF-16, после которой вставить; `kind` — `marker` (значок) или `inline` (статус в скобках); `footnote` — номер сноски в списке; `status` — короткий статус для `inline`.

Без действующего тарифа сайта метод отвечает 403 и пометок не ставит; реестры — по тарифу. Ошибки приходят как {"error": "…"}: 400, 403, 413, 429, 503 — подробнее.

Запрос

fetch("https://agent-mark.ru/api/widget/mark", {
  method: "POST",
  headers: {"Content-Type": "text/plain"},
  body: JSON.stringify({key: "pk_…", url: location.href,
                        text: "Интервью с Екатериной Шульман о выборах."})
})

Ответ

{
  "style": "footnote",
  "inline_css": "color:#c4382b",
  "warning": "",
  "footnotes": [
    {"marker": "*", "label": "Екатерина Шульман",
     "text": "Екатерина Шульман — иностранный агент"}
  ],
  "insertions": [
    {"end": 29, "kind": "marker", "footnote": 0, "status": ""}
  ]
}

Обновлено 22.10.2026 · вопросы — mail@brain-pro.ru