Справочник методов API

Все методы и OpenAPI

Вы можете скачать спецификацию OpenAPI в YAML для импорта в Postman или другой API-клиент. В файле описаны методы, параметры и форматы запросов и ответов, поэтому их не придётся добавлять вручную.

В cURL-примерах замените {apiKey} своим ключом и подставьте идентификаторы из ответов API. Пошаговый сценарий — в статье «Первый запрос к API». В примерах ответов используются демонстрационные данные. Реальные значения зависят от проекта.

Аккаунт и права ключа

Метод для проверки настройки авторизации. Он не требует отдельного права доступа (scope) и доступен даже без действующего тарифа.

curl --fail-with-body -sS "https://seo-reports.ru/api/me" \
  -H "Authorization: Bearer {apiKey}"

{
  "user_id": "123",
  "token": {
    "token_id": "456",
    "name": "CRM",
    "type": "personal",
    "scopes": [
      "projects:read",
      "reports:read"
    ],
    "expires_at": null
  }
}

Ответ содержит владельца user_id и объект token: идентификатор, название, тип, права и срок. Тип personal — персональный ключ, oauth — подключение ассистента. Если expires_at равен null, ключ бессрочный. В остальных случаях поле содержит дату со временем и часовым поясом.

Поиск и список проектов

Метод для поиска проектов по названию или адресу и получения их списка. Используйте его, чтобы получить project_id нужного проекта для использования в других методах.

curl --fail-with-body -sS "https://seo-reports.ru/api/projects?search=example.ru&page=1&page_size=20" \
  -H "Authorization: Bearer {apiKey}"

{
  "items": [
    {
      "project_id": "35328",
      "name": "example.ru",
      "url": "https://example.ru",
      "source": "yandex_metrika",
      "default_template_id": "412"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}

items содержит проекты текущего владельца ключа. Поле source показывает тип базового источника данных проекта. В кабинете эти же состояния отображаются в колонке «Источник» в списке проектов.

default_template_id — ID шаблона, выбранного для автогенерации отчётов проекта. При создании отчёта его можно передать в поле template_id. Если шаблон автогенерации не выбран, API возвращает null.

Для следующей страницы увеличьте page, пока page × page_size меньше total. Пустой items — не ошибка. Это значит, что по указанному запросу проектов не найдено.

Шаблоны и настройки генерации

Метод возвращает доступные шаблоны, шаблон по умолчанию, сведения о предыдущем отчёте и источник наследуемых настроек.

curl --fail-with-body -sS "https://seo-reports.ru/api/projects/{projectId}/report-options" \
  -H "Authorization: Bearer {apiKey}"

{
  "project_id": "35328",
  "templates": [
    {
      "template_id": "412",
      "name": "SEO-отчёт"
    }
  ],
  "default_template_id": "412",
  "previous_report": {
    "report_id": "35328.a3f1c9e84b2d7061fe5c8a94d20b3e77",
    "settings_inherited": true
  },
  "settings_source": "last_report"
}

История отчётов проекта

Метод возвращает отчёты, уже собранные по проекту, — тот же список, что история отчётов в кабинете. Используйте его, чтобы найти готовый отчёт за нужный период без новой генерации.

curl --fail-with-body -sS "https://seo-reports.ru/api/projects/{projectId}/reports?page=1&page_size=20" \
  -H "Authorization: Bearer {apiKey}"

{
  "project_id": "35328",
  "items": [
    {
      "report_id": "35328.a3f1c9e84b2d7061fe5c8a94d20b3e77",
      "status": "ready",
      "created_at": "2026-09-01T10:15:00+03:00",
      "auto": false,
      "period": {
        "from": "2026-08-01",
        "to": "2026-08-31"
      },
      "comparison": {
        "from": "2026-07-01",
        "to": "2026-07-31"
      },
      "preview_url": "https://seo-reports.ru/p/35328/a3f1c9e84b2d7061fe5c8a94d20b3e77",
      "preview_public": false
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}

Отчёты отсортированы от новых к старым по дате генерации. Как и в кабинете, за каждый день в истории остаётся последний ручной и последний автоматический отчёт. Удалённые отчёты в список не попадают. Чтобы найти отчёт за август, выберите строку с нужным period и прочитайте карточку по её report_id. Для следующей страницы увеличьте page, пока page × page_size меньше total.

Генерация и пересчёт отчёта

Метод для создания отчёта за выбранный период или повторной сборки готового отчёта. Чтобы собрать отчёт заново, передайте refresh: true. Генерация выполняется в фоне, её статус проверяется по карточке отчёта.

curl --fail-with-body -sS -X POST "https://seo-reports.ru/api/reports/generate" \
  -H "Authorization: Bearer {apiKey}" \
  -H "Content-Type: application/json" \
  --data '{
  "project_id": "{projectId}",
  "template_id": "{templateId}",
  "period": {
    "from": "2026-08-01",
    "to": "2026-08-31"
  },
  "comparison": {
    "from": "2026-07-01",
    "to": "2026-07-31"
  },
  "refresh": false,
  "make_public": false
}'

{
  "report_id": "35328.a3f1c9e84b2d7061fe5c8a94d20b3e77",
  "status": "generating",
  "preview_url": "https://seo-reports.ru/p/35328/a3f1c9e84b2d7061fe5c8a94d20b3e77",
  "preview_public": false,
  "warnings": [],
  "poll_after_ms": 2000
}

Ответ приходит сразу: HTTP 202 при сборке, HTTP 200 при готовом результате. Полученный report_id используйте для чтения карточки (см. ниже). Дождитесь, когда поле status примет значение ready, затем проверьте поле warnings. Ссылка на отчёт возвращается сразу в ответе, но открыть по ней отчёт можно только после завершения его формирования.

Пока структуру не правили, пересчёт может обновить тот же отчёт и сохранить ссылку. После правки структура входит в наследуемые параметры: запрос с теми же шаблоном и периодом может создать новый report_id, сохранив прежний отчёт по старой ссылке. Отдельного метода пересчёта правленого отчёта по report_id нет.

Карточка отчёта и готовность

Метод нужен и для опроса готовности, и для чтения текущей структуры и версии.

curl --fail-with-body -sS "https://seo-reports.ru/api/reports/{reportId}" \
  -H "Authorization: Bearer {apiKey}"

{
  "report_id": "35328.a3f1c9e84b2d7061fe5c8a94d20b3e77",
  "project_id": "35328",
  "template_id": "412",
  "status": "ready",
  "revision": 3,
  "preview_url": "https://seo-reports.ru/p/35328/a3f1c9e84b2d7061fe5c8a94d20b3e77",
  "preview_public": false,
  "period": {
    "from": "2026-08-01",
    "to": "2026-08-31"
  },
  "warnings": [],
  "blocks": [
    {
      "block_ref": "publicTraffic",
      "title": "Трафик",
      "disabled": false,
      "comment_top_html": "",
      "comment_bottom_html": "",
      "settings": {
        "metric": "users"
      }
    },
    {
      "block_ref": "publicDevices",
      "title": "Устройства",
      "disabled": true,
      "comment_top_html": "",
      "comment_bottom_html": "",
      "settings": {}
    }
  ]
}

Это сокращённый пример с двумя блоками. В реальном отчёте блоков может быть больше. После сохранения структуры и повторной сборки значение revision растёт.

При failed не считайте HTTP 200 успешной сборкой. При ready проверяйте предупреждения: их значения описаны в диагностике. Поле blocks описывает структуру отчёта. Чтобы получить цифры, используйте отдельный метод блока.

Данные и схема настроек блока

Метод для получения данных отдельного блока отчёта и описания его настроек. Возвращает показатели блока для анализа, а также доступные параметры и допустимые значения для изменения настроек.

Для запроса используйте blockRef из blocks[].block_ref в карточке отчёта. Отчёт должен быть готов (status: ready).

curl --fail-with-body -sS "https://seo-reports.ru/api/reports/{reportId}/blocks/{blockRef}" \
  -H "Authorization: Bearer {apiKey}"

Формат ответа ниже условный: имена провайдеров, содержимое data и список settings_schema зависят от конкретного блока. Настоящие имена настроек берите только из ответа своего отчёта.

{
  "block_ref": "publicTraffic",
  "title": "Трафик",
  "disabled": false,
  "data": {
    "provider": {
      "total": 1540,
      "rows": [
        {
          "date": "2026-08-01",
          "value": 50
        }
      ]
    }
  },
  "settings_schema": [
    {
      "name": "metric",
      "type": "enum",
      "label": "Показатель",
      "value": "users",
      "options": [
        {
          "value": "users",
          "label": "Пользователи"
        }
      ]
    }
  ]
}

В data находятся данные провайдеров без служебных объектов. В settings_schema для каждого поля есть name, type и label, текущее value, а при необходимости options или min/max/step. Типы: enum, boolean, number, string. Проверяйте допустимые значения перед изменением settings.

Комментарии и структура отчёта

Метод для изменения структуры и оформления отчёта: порядка блоков, их видимости, заголовков, комментариев и настроек. Также позволяет добавлять и удалять текстовые блоки.

Неуказанные заголовки, комментарии и настройки сохраняются, но для disabled действует правило выше. Чтобы удалить текстовый блок, исключите его из списка.

Сначала получите актуальную карточку отчёта. В тело запроса скопируйте её revision как expected_revision и полный массив blocks. Затем измените нужные поля, сохранив остальные блоки и их видимость (disabled).

curl --fail-with-body -sS "https://seo-reports.ru/api/reports/{reportId}" \
  -H "Authorization: Bearer {apiKey}"

Пример ниже соответствует демонстрационной карточке с двумя блоками выше и добавляет комментарий к publicTraffic. Для своего отчёта используйте его актуальную версию и полный список блоков. Не заменяйте свою структуру сокращённым списком из примера.

curl --fail-with-body -sS -X PUT "https://seo-reports.ru/api/reports/{reportId}/structure" \
  -H "Authorization: Bearer {apiKey}" \
  -H "Content-Type: application/json" \
  --data '{
  "expected_revision": 3,
  "blocks": [
    {
      "block_ref": "publicTraffic",
      "title": "Трафик",
      "disabled": false,
      "comment_top_html": "",
      "comment_bottom_html": "<p>Вывод по проверенным данным отчёта.</p>",
      "settings": {
        "metric": "users"
      }
    },
    {
      "block_ref": "publicDevices",
      "title": "Устройства",
      "disabled": true,
      "comment_top_html": "",
      "comment_bottom_html": "",
      "settings": {}
    }
  ]
}'

Запрос возвращает обновлённую карточку с новым revision. Ссылка просмотра сохраняется. Запрос применяется целиком. При конфликте версии приходит 409 revision_conflict. Перечитайте отчёт и согласуйте изменения, не подставляйте новую версию вслепую.

Как применяются изменения:

• Порядок объектов в blocks задаёт порядок в отчёте.
• Сервер очищает HTML и не сохраняет скрипты. Используйте простые абзацы, списки, выделения и ссылки.
• Чтобы добавить текстовый блок, включите в полный массив объект с type: textblock, title и comment_top_html.
• Правки сохраняются в параметрах отчёта и могут наследоваться при следующей генерации.

Word, PDF и доступ по ссылке

Метод для выгрузки отчёта в Word или PDF. Отчёт должен быть готов (status: ready). Формат — word или pdf. При успешном запросе приходит файл с заголовком Content-Disposition: attachment. Возьмите имя файла из этого заголовка или задайте его в своём клиенте.

curl --fail-with-body -sS "https://seo-reports.ru/api/reports/{reportId}/export/word" \
  -H "Authorization: Bearer {apiKey}" \
  --output report.docx

curl --fail-with-body -sS "https://seo-reports.ru/api/reports/{reportId}/export/pdf" \
  -H "Authorization: Bearer {apiKey}" \
  --output report.pdf

Word имеет MIME-тип application/vnd.openxmlformats-officedocument.wordprocessingml.document, PDF — application/pdf. Учитывайте таймаут своего клиента: экспорт может занять десятки секунд. Обе выгрузки входят в тяжёлый лимит запросов.