Public API v1

Семантика

Работайте с папками и ключами через cursor-pagination; большие изменения отправляйте пакетными командами.

Получить ключевые слова

GET/projects/{projectId}/keywordssemantics:read

Запросbash

curl "https://api.seonorita.ru/api/v1/projects/<projectId>/keywords?limit=100&search=холодильник" \
  -H "Authorization: Bearer $SEO_API_TOKEN"

200 · Сокращённый ответjson

{
  "data": [
    {
      "id": "019...",
      "textOriginal": "купить холодильник",
      "textNormalized": "купить холодильник",
      "language": "ru",
      "priority": 0,
      "isFavorite": false,
      "isTracked": true,
      "tags": [],
      "tagsTruncated": false,
      "sourceMode": "MANUAL",
      "version": 7,
      "createdAt": "2026-09-01T10:00:00.000Z",
      "updatedAt": "2026-09-01T10:00:00.000Z"
    }
  ],
  "page": {
    "hasNext": true,
    "nextCursor": "opaque-cursor"
  },
  "meta": { "requestId": "01J..." }
}

Пакетное создание

POST/projects/{projectId}/keywords/bulksemantics:write

JSON · Тело запросаjson

{
  "items": [
    {
      "text": "купить холодильник",
      "language": "ru",
      "priority": 0,
      "isFavorite": false,
      "isTracked": true,
      "tagNames": [],
      "groupId": "019...",
      "duplicatePolicy": "ADD_TO_GROUP",
      "duplicateGroupId": "019..."
    }
  ],
  "duplicatePolicy": "SKIP_EXISTING"
}

201 · Ответjson

{
  "data": {
    "selected": 1,
    "created": 1,
    "restored": 0,
    "linked": 0,
    "skipped": 0,
    "rejected": 0,
    "failed": 0,
    "rows": [
      { "index": 0, "outcome": "CREATED", "keywordId": "019...", "version": 1 }
    ]
  },
  "meta": { "requestId": "01J..." }
}

Удалить запрос

DELETE/projects/{projectId}/keywords/{keywordId}semantics:write

Передайте актуальную версию запроса в If-Match. Без тела запроса ключ перемещается в системную папку «Корзина», а API возвращает 204 No Content без JSON.

Запрос · Переместить в корзинуbash

curl -X DELETE "https://api.seonorita.ru/api/v1/projects/<projectId>/keywords/<keywordId>" \
  -H "Authorization: Bearer $SEO_API_TOKEN" \
  -H 'If-Match: "v7"'

Окончательная очистка допускается только для запроса, который уже находится в корзине. Получите его актуальную версию после первого удаления и явно передайте permanent: true. Исторические замеры остаются неизменяемыми, а пользовательские значения запроса очищаются.

Запрос · Окончательная очисткаbash

curl -X DELETE "https://api.seonorita.ru/api/v1/projects/<projectId>/keywords/<keywordId>" \
  -H "Authorization: Bearer $SEO_API_TOKEN" \
  -H 'If-Match: "v8"' \
  -H "Content-Type: application/json" \
  -d '{"permanent":true}'

Удалить папку

DELETE/projects/{projectId}/keyword-groups/{groupId}semantics:write

Команда требует актуальный If-Match и возвращает204 No Content. Системные папки «Без группы» и «Корзина» удалить нельзя. Если тело отсутствует, удаляется всё поддерево, запросы сохраняются, а оставшиеся без папки запросы переходят в «Без группы».

Запрос · Удалить папку и поднять дочерниеbash

curl -X DELETE "https://api.seonorita.ru/api/v1/projects/<projectId>/keyword-groups/<groupId>" \
  -H "Authorization: Bearer $SEO_API_TOKEN" \
  -H 'If-Match: "v4"' \
  -H "Content-Type: application/json" \
  -d '{
    "deleteKeywords": false,
    "promoteChildren": true
  }'

Поле	По умолчанию	Поведение при true
`promoteChildren`	Удалить папку вместе с поддеревом	Удалить только выбранную папку и поднять её прямых потомков на уровень выше
`deleteKeywords`	Сохранить запросы и перенести оставшиеся без папки в «Без группы»	Переместить затронутые удалением запросы в «Корзину»