SEO Tools API

Программный доступ к платформе seotoolse.ru: запуск SEO/GEO-инструментов и контент-фабрики, получение результатов, расписания и экспорт. Тот же бэкенд, что и кабинет — данные из официальных API Яндекса и Google + AI-движок.

• Base URL: https://seotoolse.ru/api
• Формат: JSON (Content-Type: application/json), UTF-8
• Авторизация: Bearer-токен sk_live_… (см. ниже)
• MCP: для AI-ассистентов есть готовый MCP-сервер — см. ../mcp-server.js и раздел MCP.

1. Авторизация

API использует персональный токен формата sk_live_<64 hex>. Доступно с тарифа STARTER и выше.

Получить токен

В кабинете: Настройки → API → Сгенерировать токен. Plaintext показывается один раз — сохраните его. Повторная генерация отзывает старый токен.

Программно (нужен JWT из логина):

curl -X POST https://seotoolse.ru/api/auth/api-token \
  -H "Authorization: Bearer <JWT>"
# → { "apiToken": "sk_live_…", "preview": "sk_live_…XXXX" }

Использовать токен

Передавайте в каждом запросе:

Authorization: Bearer sk_live_xxxxxxxx...

> Токен = полный доступ к аккаунту и списанию токенов. Храните как пароль, не коммитьте в репозиторий. При утечке — перегенерируйте (старый сразу инвалидируется).

2. Модель работы

1. Создаёте задачу (POST /tasks) с типом и входными данными → получаете taskId, токены списываются сразу.

2. Задача проходит статусы: QUEUED → PROCESSING → COMPLETED (или FAILED — токены возвращаются).

3. Опрашиваете (GET /tasks/{id}) до терминального статуса → читаете result.

4. При желании — экспорт (GET /export/{id}) в CSV/XLSX или расписание (POST /scheduled).

Стоимость — в токенах (списываются с баланса тарифа). Цена за задачу = цена за единицу × кол-во единиц (ключей/URL), для AI-тулзов — по выбранному тиру модели.

3. Эндпоинты

POST /tasks — создать задачу

Тело:

{ "type": "SERP_TOP", "input": { "keywords": ["купить бетон"], "engine": "yandex", "region": "213" }, "projectId": "опц." }

Ответ 201:

{ "taskId": "cmq…", "type": "SERP_TOP", "status": "QUEUED", "creditsCost": 1 }

Ошибки: 400 (невалидный вход), 402 (не хватает токенов — {required, available}), 403 (тариф/модель не позволяет), 429 (лимит частоты).

GET /tasks/{id} — статус и результат

{ "id": "cmq…", "type": "SERP_TOP", "status": "COMPLETED",
  "progress": 100, "creditsCost": 1, "resultCount": 10,
  "result": { "items": [ … ] } }

GET /tasks?limit=10&type=SERP_TOP — история задач

Список метаданных (без тяжёлого result).

GET /auth/me — баланс, тариф, лимиты

{ "user": { "id": "…", "email": "…", "plan": "STARTER", "credits": 5000, "apiEnabled": true } }

GET /tools — каталог инструментов

Полный справочник. На каждый инструмент:

{ "slug": "article-write", "type": "ARTICLE_WRITE", "name": "Генератор статьи",
  "category": "content", "unit": "статья", "description": "…",
  "costPer": 20, "paid": true, "comingSoon": false, "tierPriced": true,
  "models": [ { "id": "seo-lite", "label": "SEO Lite", "credits": 20 }, … ] }

• type — передавайте в POST /tasks. costPer — цена за unit (для tierPriced — «от», цена тира Lite; полная сетка в models).
• paid: true — нужен STARTER+. comingSoon: true — инструмент в разработке (POST вернёт 400).
• Цены берутся из тарифной сетки в реальном времени — всегда актуальны.

POST /scheduled — расписание (cron)

{ "name": "Позиции каждый день", "type": "POSITION_CHECK",
  "input": { "domain": "site.ru", "keywords": ["…"] },
  "cronPattern": "0 9 * * *", "timezone": "Europe/Moscow" }

GET /scheduled — список расписаний

GET /export/{id}?format=csv — экспорт результата

format: csv | xlsx | json.

4. Справочник типов задач

Типы передаются в type (UPPER_SNAKE_CASE). Цены — в токенах за единицу (актуальные на момент написания; источник правды — GET /tools и тарифная сетка).

SERP / выдача

Ключевые слова

Анализ

GEO / готовность к AI-поиску

AI-инструменты (выбор тира модели)

Поле input.model: seo-lite (20) · seo-midl (40) · seo-pro (80) · seo-pro-plus (150). Цена = тиру. Доступны со STARTER.

Контент-фабрика

template (для CONTENT_BRIEF/ARTICLE_WRITE): guide · howto · comparison · review · listicle · problem · explainer · product.

Бренд-факты/голос подмешиваются автоматически, если задача привязана к проекту (projectId, поля проекта brandKnowledge/brandVoice).

5. Пример: от ключа до статьи

API=https://seotoolse.ru/api
TOK="Authorization: Bearer sk_live_…"

# 1. План статьи
BRIEF=$(curl -s -X POST $API/tasks -H "$TOK" -H 'Content-Type: application/json' \
  -d '{"type":"CONTENT_BRIEF","input":{"query":"как выбрать бетонный завод","aiOutline":true}}')
ID=$(echo "$BRIEF" | jq -r .taskId)

# 2. Дождаться результата
until [ "$(curl -s $API/tasks/$ID -H "$TOK" | jq -r .status)" = "COMPLETED" ]; do sleep 3; done

# 3. Сгенерировать статью
curl -s -X POST $API/tasks -H "$TOK" -H 'Content-Type: application/json' \
  -d '{"type":"ARTICLE_WRITE","input":{"topic":"как выбрать бетонный завод","model":"seo-pro","wordCount":1800}}'

6. Ошибки

MCP

Готовый MCP-сервер для Claude Code / Claude Desktop / Cursor — mcp-server.js. Даёт инструменты seo_create_task, seo_get_task, seo_list_tasks, seo_check_credits, seo_list_tools, seo_create_schedule, seo_list_schedules, seo_export_task. Конфиг — mcp-config-example.json:

{
  "mcpServers": {
    "seo-tools": {
      "command": "node",
      "args": ["/абсолютный/путь/mcp-server.js"],
      "env": { "SEO_API_URL": "https://seotoolse.ru/api", "SEO_API_TOKEN": "sk_live_…" }
    }
  }
}