SEOAsist Docs
СправочникОбновлено: 2026-11-03

REST API v1: ключи API, аутентификация и эндпоинты

Как создать ключ API, передавать заголовок Authorization, лимиты запросов и полный список эндпоинтов v1 с параметрами, форматом ответа и кодами ошибок.

Открыть этот экран в панели

REST API v1 позволяет выполнять из кода практически все действия, доступные в панели: получать список сайтов, запускать сканирование, выгружать проблемы, открывать AI-исправления и управлять правилами Pixel, ключевыми словами, контентом, обратными ссылками, аутричем, конкурентами и публикациями в соцсетях. Ключи привязаны к организации; ключ имеет доступ только к данным своей организации. MCP-сервер вызывает те же эндпоинты.

Предварительные требования

  • Создавать и отзывать ключи может только владелец или администратор организации. Другим ролям вкладка "Ключи API" недоступна.
  • Доступ к API включен в тарифные планы Pro и Agency. Если ваш тарифный план его не включает, на вкладке отображается уведомление со ссылкой "Посмотреть тарифы"; вы всё еще можете создать ключ, но запросы будут возвращать ошибку 403 plan_required.

Создание ключа API

  1. Перейдите в Настройки → Профиль → Ключи API.
  2. В поле "Название ключа" укажите, где будет использоваться ключ (минимум 2 символа, например, "CI").
  3. Если ключу необходимо запускать сканирование или создавать исправления, правила, ключевые слова или контент, отметьте "право на запись" (write scope). Оставьте галочку снятой для ключа только на чтение.
  4. Нажмите "Создать ключ".
  5. Сразу скопируйте ключ, начинающийся с sa_live_, с помощью кнопки "Скопировать ключ". Он больше никогда не будет показан; в списке сохраняется только его Префикс.
warning

Организация может иметь не более 20 активных ключей. Если ключ скомпрометирован, немедленно отозвите его с помощью иконки корзины ("Отозвать") в списке. Запросы с использованием отозванного ключа сразу получают ошибку 401.

Подключения, настроенные AI-приложениями через OAuth, не отображаются в этом списке; они находятся в списке "Подключенные ассистенты" на странице Подключите вашего AI-ассистента.

Аутентификация и базовый URL

  • Базовый URL: https://seoasist.com/api/v1
  • Заголовок: Authorization: Bearer sa_live_…
  • Также принимается параметр запроса ?api_key=sa_live_…. Ключи в URL обычно попадают в логи, поэтому используйте этот способ только для тестирования.

Права доступа (Scopes): ключ с правом read может вызывать любой эндпоинт GET. Право write разблокирует запросы POST, PATCH и DELETE. Запрос на запись с ключом только для чтения возвращает 403.

Лимиты: не более 240 запросов в минуту на организацию и не более 30 AI-исправлений в час (POST /sites/{id}/fixes). При превышении вы получите ошибку 429 rate_limited.

curl -H "Authorization: Bearer sa_live_..." \
  https://seoasist.com/api/v1/sites

Формат ответа (Response envelope)

Каждый успешный ответ JSON выглядит следующим образом:

{ "ok": true, "data": {}, "ms": 42 }

data содержит результат работы эндпоинта, а ms — время выполнения запроса в миллисекундах. Единственное исключение — llms.txt, который возвращает простой текст (text/plain). Ошибки возвращают { "ok": false, "error": "<code>", "message": "…" }.

Эндпоинты

Все пути указаны относительно базового URL. {id} — это ID сайта, который можно получить из GET /sites.

Аккаунт и сайты

МетодПутьПраваЧто делает
GET/mereadОрганизация и права ключа: orgId, scopes
GET/sitesreadСписок сайтов: id, name, domain, url, healthScore, lastCrawlAt, gscProperty, ga4PropertyId, repo, pixelKey … и динамика позиций в Search Console (movement)
GET/sites/{id}readПоля сайта + lastCrawl (id, pages, finishedAt), issueTotals, группы проблем (code, severity, title, count), репозитории кода (repos), каналы исправлений (fixChannels) и растущие / падающие запросы
GET/sites/{id}/data-sourcesreadАктивный источник данных и его состояние для каждого типа данных
POST/sites/{id}/crawlwriteЗапускает сканирование; возвращает { crawlId, status: "queued" }. 402 limit_reached, если ежемесячная квота страниц исчерпана

Проблемы, исправления и правила

МетодПутьПраваЧто делает
GET/sites/{id}/issuesreadСгруппированные проблемы (totals, groups). С ?code= вы получаете эту группу и примеры urls; ?limit= по умолчанию 200, макс. 1000
POST/sites/{id}/issues/{code}/rule-fixwriteУстраняет один код проблемы на каждом затронутом URL с помощью правил (требуется Site API, плагин WordPress или Pixel)
POST/sites/{id}/fixeswriteОткрывает AI-исправление (задача PR / MR). Тело: issueCode или instructions (одно из них обязательно), опционально repo и model. Возвращает { jobId, status: "queued" }
GET/sites/{id}/fixesreadПоследние 50 задач по исправлению: status, model, repo, prUrl, summary, error …
GET/sites/{id}/pixel/rulesreadПравила
POST/sites/{id}/pixel/ruleswriteДобавляет правило. Тело: kind, matchType (по умолчанию exact), matchPath (по умолчанию /), payload, опционально note
DELETE/sites/{id}/pixel/rules/{ruleId}writeУдаляет правило; { deleted: true }

Ключевые слова и контент

МетодПутьПраваЧто делает
GET/sites/{id}/keywordsreadavgPosition, buckets и ключевые слова (position, prevPosition, change, best, url, volume, kd, intent, aiOverview, aiCited …) плюс movers из Search Console
POST/sites/{id}/keywordswriteТело: { keywords: string[] } (макс. 200 за запрос). Возвращает { added }; ключевые слова, которые уже отслеживаются, пропускаются
GET/sites/{id}/keywords/opportunitiesreadПул ключевых слов с оценкой потенциала (0–100) и действием (new / strengthen); ?limit= по умолчанию 50, макс. 300
POST/sites/{id}/keywords/ideaswriteТело: { keywords: string[], note? } (2–60 ключевых слов). Кластеризует ключевые слова и создает идеи для блога со статусом idea
GET/sites/{id}/contentreadПоследние 100 элементов контента; фильтрация с помощью ?status=
POST/sites/{id}/contentwriteСоздает идею для блога. Тело: title (обязательно), targetKeywords?, angle?, generate? (true ставит написание в очередь)
GET/sites/{id}/content/{itemId}readОдин элемент контента со всеми его полями (включая HTML)
PATCH/sites/{id}/content/{itemId}writeРедактирует статью блога, которая еще не опубликована: title, html, faq, metaTitle, metaDescription, excerpt, slug, targetKeywords. Утвержденная или запланированная статья возвращается на проверку. Переписанные страницы и опубликованные статьи возвращают 422 / 409 not_editable
POST/sites/{id}/content/{itemId}/approvewriteУтверждает элемент. При передаче scheduledFor (ГГГГ-ММ-ДД) статус меняется на scheduled; планирование должно пройти проверки автопубликации
POST/sites/{id}/content/{itemId}/publishwriteСтавит задачу публикации в очередь. Тело: channel (wordpress, github, siteapi, manual), live?. Прямая публикация должна пройти проверки автопубликации; переписанные страницы нельзя публиковать напрямую
GET / POST/sites/{id}/content/{itemId}/briefread / writeСохраненный исследовательский бриф / новый бриф (keyword, urls?); расходует ежемесячную квоту брифов
POST/sites/{id}/scorereadОценивает HTML статьи от 0 до 100 (html, itemId?, keyword?, title?, metaDescription?)
POST/sites/{id}/articleswriteОтправляет статью, написанную вашим собственным AI, на проверку (HTML очищается, макс. 300 КБ, не учитывается в ежемесячной квоте контента)
GET/sites/{id}/brandreadПрофиль бренда: тональность, аудитория, запрещенные слова, автор

Обратные ссылки, аутрич и конкуренты

МетодПутьПраваЧто делает
GET/sites/{id}/backlinksreadПрофиль обратных ссылок: сводка, тренд, топ доменов и анкоров
GET/sites/{id}/backlinks/linksreadОтдельные обратные ссылки; ?status= (active, new, lost, toxic, broken), ?limit= по умолчанию 200, макс. 1000
POST/sites/{id}/backlinks/opportunitieswriteДомены, ссылающиеся на конкурентов, но не на ваш сайт; расходует кредиты DataForSEO
GET / POST/sites/{id}/outreachread / writeЗаписи аутрича / новый потенциальный контакт (domain, url?, contactName?, contactEmail?, notes?, rank?)
PATCH/sites/{id}/outreach/{outreachId}writeСтатус (idea, contacted, replied, won, lost), контактные данные или заметки
GET / POST/sites/{id}/competitorsread / writeКонкуренты / новый домен конкурента (макс. 20 на сайт)
GET/sites/{id}/competitors/gapreadУпущенный контент (gap); ?competitorId=, ?minVolume=, ?maxKd=, ?limit=
GET/sites/{id}/competitors/{competitorId}/keywordsreadКлючевые слова, по которым ранжируются и сайт, и конкурент

Мониторинг и AI

МетодПутьПраваЧто делает
GET/sites/{id}/georeadСводка AI-видимости; ?days= по умолчанию 90
GET/sites/{id}/monitorsreaduptime (30 дней), количество index и changes30d
GET/sites/{id}/ai-accessreadПоследняя проверка доступа AI-ботов: checkedAt, result, policy
GET/sites/{id}/llms.txtreadСгенерированный файл llms.txt в виде обычного текста

Организация

МетодПутьПраваЧто делает
GET/notificationsread{ unread, items }; ?unread=1 возвращает только непрочитанные, ?limit= по умолчанию 50, макс. 200
POST/notifications/readwriteТело: { ids?: string[] }; без ids все уведомления отмечаются как прочитанные
GET/todoreadЧто требует участия человека и что сделано автоматикой; ?siteId=, ?days= (по умолчанию 7)
GET/agent/tasksreadЗадачи вручную из планов с истекающим сроком; ?siteId=
POST/agent/tasks/{taskId}/completewriteЗакрывает ручную задачу с заметкой (note, минимум 10 символов)
POST/agent/activitywriteЗаписывает строку в ленту активности (message, siteId?)
GET/reportsreadПоследние 50 отчетов и их публичные url; фильтрация с помощью ?siteId=
GET/social/accounts, /social/posts, /social/insightsreadСоциальные аккаунты, публикации и аналитика аккаунтов (из общего модуля социальных сетей)
POST/social/posts, /social/posts/{postId}/schedule, /social/campaignwriteСоздание публикаций, установка дат и серий кампаний; публикации попадают на проверку

Статусы контента: idea, planned, generating, draft, review, approved, scheduled, published, failed, archived. Значения kind для правил: title, meta_description, canonical, robots, h1, img_alt, og, json_ld, hreflang, redirect, lang, attr, link, meta. Значения matchType: exact, prefix, regex, all.

note

В организациях с оплатой через CoSuite сайты сверх лимита доступных сайтов находятся в режиме только для чтения. Каждый запрос на запись в них возвращает 403 site_read_only; запросы на чтение продолжают работать.

Примеры

Запуск AI-исправления:

curl -X POST https://seoasist.com/api/v1/sites/SITE_ID/fixes \
  -H "Authorization: Bearer sa_live_..." \
  -H "Content-Type: application/json" \
  -d '{"issueCode":"missing_meta_description"}'

Добавление ключевых слов для отслеживания:

curl -X POST https://seoasist.com/api/v1/sites/SITE_ID/keywords \
  -H "Authorization: Bearer sa_live_..." \
  -H "Content-Type: application/json" \
  -d '{"keywords":["seo tool","site audit"]}'

Такие задачи, как сканирование и исправления, помещаются в очередь. Отслеживайте результат с помощью соответствующего эндпоинта GET (/sites/{id}, /sites/{id}/fixes).

Коды ошибок

HTTPerrorКогда возникает
400bad_requestПоле в теле запроса отсутствует или недействительно (например, title, kind, keywords[])
401unauthorizedКлюч отсутствует, недействителен или отозван
402limit_reachedИсчерпана квота тарифного плана (например, ежемесячный лимит сканирования страниц, отслеживаемых ключевых слов, исследовательских брифов)
403plan_requiredТарифный план не включает доступ к API (требуется Pro или Agency)
403forbiddenЗапрос на запись с использованием ключа только для чтения
403site_read_onlyСайт находится сверх лимита сайтов в CoSuite; запись отключена
404not_foundСайт или запись не принадлежат этой организации, не существуют, или эндпоинт неизвестен
409conflictНапример, у сайта нет репозитория кода, хостинг кода не подключен, недоступна модель AI, утверждения с AI-метками еще не проверены, или переписанная страница отправлена на прямую публикацию
409publish_gateПубликация не прошла проверки автопубликации; она была возвращена на проверку, а владелец получил уведомление
409 / 422not_editableКонтент, который нельзя редактировать (опубликованная статья или переписанная страница)
413too_largeТело запроса слишком велико (например, HTML статьи превышает 300 КБ)
422no_aiДля выполнения действия недоступен AI
429rate_limitedПревышен лимит в 240 запросов в минуту или 30 исправлений в час
500internalНепредвиденная ошибка. В целях безопасности подробности не возвращаются

Часто задаваемые вопросы

Я потерял свой ключ. Могу ли я посмотреть его снова?

Нет. Ключи хранятся только в виде хэша. Отозовите старый ключ и создайте новый.

Могу ли я использовать один и тот же ключ в MCP-клиенте?

Да. Существует два способа:

  • Удаленный MCP (без установки, рекомендуется): https://seoasist.com/api/mcp. Добавьте этот URL в качестве коннектора в claude.ai, Claude Desktop, ChatGPT, Cursor или VS Code; откроется окно входа в SEOAsist, где вы выберете организацию и права доступа, не копируя ключ. Пошаговые инструкции и ссылки для установки в один клик находятся в панели в разделе Настройки → Интеграции → Подключите вашего AI-ассистента. В Claude Code выполните claude mcp add --transport http seoasist https://seoasist.com/api/mcp и войдите в систему с помощью /mcp при первом использовании. Если окно входа не может открыться (серверы, CI), передайте ключ API с помощью --header "Authorization: Bearer sa_live_...".
  • Локальный (stdio): вкладка "Ключи API" в разделе "MCP-сервер" предоставляет готовый конфиг для Claude Desktop, Claude Code и Cursor; вы подставляете ключ в переменную SEOASIST_API_KEY.

После подключения в меню команд AI-приложения появятся готовые команды seo_round, content_from_gap, backlink_outreach, agent_tasks и weekly_report. Инструменты MCP вызывают те же эндпоинты; для инструментов записи требуется ключ с правом на запись (write scope). Переписанные страницы (page_update) нельзя публиковать в прямом эфире через API; публикуются только статьи блога. Все инструменты, права доступа и коды ошибок описаны в справочнике по MCP; настройки для каждого приложения см. в разделе Подключение вашего AI.

Могу ли я вызывать API прямо из браузера?

API возвращает заголовок Access-Control-Allow-Origin: *. Тем не менее, никогда не встраивайте ключ в публичную страницу; любой, кто увидит ключ, сможет получить доступ к данным вашей организации.

Похожие статьи

Была ли эта статья полезной?
Не нашли нужное?
Опишите проблему, и наша команда ответит по e-mail.
Связаться с нами