NeovaПродвинутая SEO-платформа

REST API

Читайте свой аккаунт Neova Online из скрипта, таблицы или другого инструмента и действуйте в нём: запускайте сканирование, читайте его отметки, открывайте и закрывайте задачи. Ключ создаётся в «Настройки», затем Neova Online, затем «API-ключи».

Читайте свой аккаунт Neova Online из скрипта, таблицы или другого инструмента и действуйте в нём: ваши портфели и ресурсы, их сканирования, отметки, URL и задачи каждого сканирования, ваши расписания и оповещения. С ключом «Чтение и запись» можно также запускать сканирование в Neova Online, создавать, обновлять и закрывать задачи и добавлять ресурсы в портфели.

Что работает в Neova Online, а для чего нужен компьютер

API - часть Neova Online. Он читает и изменяет то, что хранится в вашем аккаунте Neova Online.

В Neova Online (этот API) Нужна Neova на компьютере
Портфели, ресурсы, цвета и коды Чтение, добавление и удаление ресурса в портфеле Синхронизируются в обе стороны с вашими компьютерами (Настройки › Neova Online)
Сканирования Чтение всех сканирований в Neova Online. Запуск сканирования с сохранёнными настройками ресурса, не больше 10,000 URL и 10 URL в секунду, одно задание за раз на аккаунт Сканирования больше или быстрее этого, а также сканирования сайтов, доступных только из вашей сети (staging-сайт за VPN, localhost). Сканирование, сделанное на компьютере, становится доступно API, когда оно попадает в Neova Online («Отправлять новые сканирования»)
Отметки, URL, задачи сканирования Прочитаны
Задачи ресурса (его план действий) Чтение, создание, обновление, закрытие План действий в Neova Online свой: он пока не синхронизируется с компьютером
Расписания Чтение того, что хранит Neova Online Задаются и запускаются на компьютере; пока не синхронизируются с Neova Online, поэтому сейчас этот список пуст
Оповещения Чтение того, что хранит Neova Online Оповещения Neova Go создаются на компьютере; Neova Online хранит те, что создали её собственные проверки
Импорт из других краулеров, логи сервера, ИИ-разбор На компьютере

Ограничения Neova Online (10,000 URL, 10 URL в секунду, одно задание за раз) - это её текущие настройки; GET /api/v1/account всегда сообщает те, что действуют для вас.

Аутентификация

Каждый запрос, кроме GET /api/v1 и GET /api/v1/openapi.json, передаёт API-ключ:

Authorization: Bearer neova_...

Ключ создаётся в Настройки › Neova Online › API-ключи (в Neova Online или в Neova на компьютере, где выполнен вход в Neova Online) кнопкой Создать ключ…:

Ключ показывается один раз, при создании. Neova Online хранит только его отпечаток (SHA-256), название, область, последние 4 символа и время создания и последнего использования. Потерянный ключ нельзя показать снова: отзовите его и создайте новый. Отозвать… сразу отключает ключ. В аккаунте может быть не больше 20 ключей.

Ключу место на сервере или в скрипте, но никогда на веб-странице: API не отправляет заголовки CORS, поэтому скрипт в браузере не сможет прочитать его ответы.

export NEOVA_KEY=neova_...
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/account

Ограничения

Списки: страницы и курсоры

Список отвечает так:

{"data": [...], "has_more": true, "next_cursor": "eyJvIjo1MCwiZiI6IjQ0MTM2ZmEzNWMyZSJ9", "total": 612}

Следующую страницу запрашивайте с cursor=<next_cursor> и теми же фильтрами. Курсор, выданный для других фильтров, отклоняется (invalid_cursor). total считает все строки, подходящие под фильтры. URL, отмеченные проверкой URL и задачи сканирования разбиваются на страницы по URL или ключу, поэтому страница никогда не повторяет и не пропускает строку.

ID

Объект ID Пример
Портфель его ID demo
Ресурс его хост, без www., с портом, если он есть scrapeme.live, localhost:8080
Сканирование имя его папки scrapeme-20261111-1115
Проверить её ID в библиотеке проверок SE-001
Задача сканирования её ключ: проверка и группа страниц SE-001|single
Задача (план действий) его ID p00001
Задание номер; хранится час после окончания задания и забывается при перезапуске Neova Online (сканирование остаётся) 12
Расписание, оповещение их ID

У каждой проверки есть library_url - её страница в библиотеке проверок: https://app.neova.app/checks/id/<ID>.

Эндпоинты

GET/api/v1

Этот API: его версия и где лежит его описание OpenAPI. Ключ не нужен.

GET/api/v1/openapi.json

Описание OpenAPI 3.1 этого API. Ключ не нужен.

GET/api/v1/account

Ваш аккаунт, использованный ключ (его ID, название, область, когда создан и когда последний раз использовался) и действующие ограничения.

curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/account
{"data": {"id": "u05c1f402cac1", "email": "ann@example.com", "name": "Ann", "created_at": "2026-11-10T19:02:11Z",
  "api_key": {"id": "ka943935d4a14", "name": "Looker Studio", "scope": "read", "created_at": "2026-11-11T17:20:03Z", "last_used_at": "2026-11-11T17:31:39Z"},
  "limits": {"requests_per_minute": 60, "page_size_max": 500, "crawl": {"max_urls": 10000, "urls_per_second": 10.0, "jobs_at_a_time": 1}},
  "neova_online": {"url": "https://app.neova.app", "version": "0.10.36"}}}

GET/api/v1/portfolios

Ваши портфели в вашем порядке: у каждого ID, название, родитель (портфель внутри другого), цвет, его ресурсы и competitors_of, если это конкуренты какого-то ресурса. С разбиением на страницы.

GET/api/v1/portfolios/{portfolio_id}

Один портфель.

POST/api/v1/portfolios/{portfolio_id}/properties (чтение и запись)

Добавляет ресурс в портфель. В теле запроса ресурс указывается по хосту или по одному из его URL. 201 с портфелем, если ресурс добавлен; 200 с "added": false, если он там уже был. Ваши компьютеры получат изменение при следующей синхронизации (портфель Demo остаётся в Neova Online).

curl -X POST -H "Authorization: Bearer $NEOVA_KEY" -H "Content-Type: application/json" \
  -d '{"property": "example.com"}' https://app.neova.app/api/v1/portfolios/demo/properties

DELETE/api/v1/portfolios/{portfolio_id}/properties/{property} (чтение и запись)

Убирает ресурс из портфеля. Его сканирования, настройки и план действий остаются.

GET/api/v1/properties

Ваши ресурсы: все сайты, которые есть в портфелях или были прочитаны сканированием, в вашем порядке, у каждого код, цвет, портфели, конкуренты (основные и второстепенные), число сканирований и последнее сканирование. Фильтр: portfolio=<id>. С разбиением на страницы.

GET/api/v1/properties/{property}

Один ресурс.

GET/api/v1/properties/{property}/crawls

Сканирования ресурса, новые сверху. Фильтр: state (running, interrupted, blocked, empty, stopped, limit, done). С разбиением на страницы.

Сканирование сообщает свой kind (crawl для сканирования всего сайта, sample, sections, list, watch, import), свой state (done - завершено, limit - остановлено на лимите URL, stopped - остановлено человеком, interrupted - прервано до конца, blocked - заблокировано сайтом, empty - ничего не получено, running), свои urls, html_200, flags, checks, tickets и tickets_open, посчитанные так же, как на главной. flags и checks равны null, если проверки не выполнялись или сайт заблокировал сканирование.

POST/api/v1/properties/{property}/crawls (чтение и запись)

Запускает сканирование ресурса в Neova Online с его сохранёнными настройками («Настройки › Сканирование»: значения по умолчанию, собственные настройки ресурса, список исключений для всех сканирований). Оно начинается там же, где началось последнее сканирование ресурса, или с https://<property>/; укажите url, чтобы начать с другого места на том же хосте. Сканирование выполняется как задание, в пределах ограничений Neova Online; проверки и задачи запускаются по его окончании, как для сканирования, запущенного в окне.

curl -X POST -H "Authorization: Bearer $NEOVA_KEY" -H "Content-Type: application/json" -d '{}' \
  https://app.neova.app/api/v1/properties/example.com/crawls

202 с заданием и заголовком Location: /api/v1/jobs/<id>:

{"data": {"id": 12, "kind": "crawl", "property": "example.com", "crawl_id": "example-20261111-1931", "state": "running", "step": "1/4 crawling",
  "urls_fetched": 0, "started_at": "2026-11-12T01:31:40Z", "ended_at": null, "error": null, "start_url": "https://example.com/",
  "settings": {"urls_per_second": 3.0, "max_urls": 10000, "sample": null, "sections": null, "render": "off", "user_agent": "neovabot", "robots": "respect", "exclude_patterns": 2},
  "links": {"self": "/api/v1/jobs/12", "crawl": "/api/v1/crawls/example-20261111-1931"}}}

settings - это настройки, которые сканирование использует после применения ограничений Neova Online. Второе сканирование, пока идёт первое, получает ответ 409 job_running с ID выполняющегося задания.

GET/api/v1/jobs/{job_id}

Задание, запущенное в Neova Online: state - running, done или failed (с error), step - этап, на котором оно находится, urls_fetched - сколько URL получено на данный момент, crawl_id - сканирование, которое оно записывает. Запрашивайте каждые несколько секунд, пока оно не закончится; затем читайте сканирование.

POST/api/v1/jobs/{job_id}/stop (чтение и запись)

Останавливает идущее сканирование, как «Стоп» в окне: оно сохраняет полученное и запускает на нём проверки. Остановите ещё раз, чтобы прервать и проверки. 202.

GET/api/v1/crawls/{crawl_id}

Сводка одного сканирования: поля сканирования (см. выше), а затем:

curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/crawls/scrapeme-20261111-1115

GET/api/v1/crawls/{crawl_id}/flags

Отметки сканирования, по строке на проверку: check_id, title, severity (must_fix, если хоть одна из её отметок - «Нужно исправить», иначе review), category, urls (уникальные отмеченные URL), flags, urls_checked, library_url. Сначала «Нужно исправить», затем по числу URL. Фильтры: severity, category, ai_review=true (вместо этого предложения ИИ-разбора). С разбиением на страницы.

curl -H "Authorization: Bearer $NEOVA_KEY" "https://app.neova.app/api/v1/crawls/scrapeme-20261111-1115/flags?severity=must_fix&limit=10"

GET/api/v1/crawls/{crawl_id}/flags/{check_id}

Одна проверка в сканировании: check (её строка выше, с means, fix и rule из библиотеки проверок) и data - отмеченные ею URL с severity и evidence каждого, по URL. С разбиением на страницы. Проверка, объединённая с другой, отвечает как проверка, которая её заменила (merged_from).

GET/api/v1/crawls/{crawl_id}/urls

URL сканирования, по URL: status_code, content_type, indexable, indexability_status (No response, Server error, Client error, Redirected, Noindex, Canonicalized, как в «Все URL»), title, description, h1, canonical, meta_robots, redirect_to, size_bytes, response_ms, depth, inlinks, flags, page_group. С разбиением на страницы.

Фильтры:

curl -H "Authorization: Bearer $NEOVA_KEY" "https://app.neova.app/api/v1/crawls/scrapeme-20261111-1115/urls?status=4xx&limit=100"

GET/api/v1/crawls/{crawl_id}/url?url=<URL>

Один URL сканирования: его поля (см. выше), его ledger (как сканирование его нашло и что с ним стало), 10 inlink_sources с их анкорами, outlinks, in_sitemap и flag_list - все отметки на нём с проверкой, уровнем, доказательством и страницей в библиотеке. Закодируйте URL:

curl -G -H "Authorization: Bearer $NEOVA_KEY" --data-urlencode "url=https://scrapeme.live/shop/" \
  https://app.neova.app/api/v1/crawls/scrapeme-20261111-1115/url

GET/api/v1/crawls/{crawl_id}/tickets

Задачи сканирования в том виде, в каком их написали его проверки: по одной на проверку и группу страниц, по ключу, у каждой summary и description (текст задачи для Jira или другого трекера), severity, priority, urls, state, first_seen, last_seen и library_url. Фильтр: state (open, closed, all - по умолчанию). С разбиением на страницы. Эти задачи принадлежат сканированию, и каждое сканирование пишет свои: чтобы вести работу между сканированиями, используйте задачи ресурса ниже.

GET/api/v1/properties/{property}/tickets

Задачи ресурса: пункты его плана действий, список того, что вы действительно будете делать, по порядку, который переживает любое сканирование. У каждой есть id, title, description, check_id (если она о проверке), status (todo, in_progress, done), closed, owner, note, library_url, а для задачи о проверке ещё urls_flagged_now - URL, которые проверка отмечает в последнем сканировании ресурса с проверками, и resolved - true, если это сканирование выполнило проверку и она сейчас не отмечает ни одного URL (как «Решено» в плане действий). Фильтр: status (todo, in_progress, done или open для первых двух). С разбиением на страницы.

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

GET/api/v1/properties/{property}/tickets/{ticket_id}

Одна задача.

POST/api/v1/properties/{property}/tickets (чтение и запись)

Создаёт задачу в конце плана действий ресурса. Поля: title (не больше 200 символов), description (2,000), check_id, owner (80), note (2,000), status (по умолчанию todo). С check_id и без названия используется название из самого плана действий: Resolve: <the check's title>. 201 с задачей и её Location.

curl -X POST -H "Authorization: Bearer $NEOVA_KEY" -H "Content-Type: application/json" \
  -d '{"check_id": "SE-001", "owner": "Dev team", "note": "Set it in the CDN"}' \
  https://app.neova.app/api/v1/properties/scrapeme.live/tickets

PATCH/api/v1/properties/{property}/tickets/{ticket_id} (чтение и запись)

Меняет любые поля из перечисленных выше; null очищает поле (но не название). status todo снова открывает закрытую задачу.

curl -X PATCH -H "Authorization: Bearer $NEOVA_KEY" -H "Content-Type: application/json" \
  -d '{"status": "in_progress", "owner": "Marc"}' https://app.neova.app/api/v1/properties/scrapeme.live/tickets/p3a9c1f

POST/api/v1/properties/{property}/tickets/{ticket_id}/close (чтение и запись)

Закрывает задачу: её статус становится done.

GET/api/v1/schedules

Ваши расписания, ближайший запуск сверху: сканирования по расписанию, снимки Core Web Vitals и архивы Google Search Console, у каждого ресурс, kind (crawl, cwv, gsc), every, day, time, on, next_run и last_run. Фильтр: property. С разбиением на страницы. Расписания задаёт и запускает Neova на компьютере, и они пока не синхронизируются с Neova Online, поэтому этот список пуст, пока синхронизация не появится.

GET/api/v1/alerts

Ваши оповещения, новые сверху: property, rule (cwv, clicks, tracked, crawl), level (poor, warn, good), text, before, after, at. Фильтры: property, level. С разбиением на страницы.

Ошибки

Каждая ошибка - это JSON с HTTP-статусом:

{"error": {"status": 403, "code": "forbidden_scope", "message": "This key can read only.",
  "fix": "Make a Read-Write key in Settings › Neova Online › API Keys for this request.", "docs": "https://app.neova.app/help/rest-api#errors"}}

message говорит, что случилось, fix - что делать. При неверном параметре или поле добавляется parameter или field.

Статус Код Когда
400 invalid_parameter Неверный параметр запроса (limit, status, indexable...)
400 invalid_cursor Курсор, который Neova не выдавала или выдала для других фильтров
400 invalid_field Поле в теле запроса неверное или неизвестное
400 invalid_json Тело запроса не является валидным JSON
400 too_many_tickets В плане действий не больше 500 задач
401 unauthorized Ключа нет, это не ключ или ключ отозван
403 forbidden_scope Ключ «Только чтение» на эндпоинте, которому нужен ключ «Чтение и запись»
404 route_not_found Такого эндпоинта нет
404 crawl_not_found, property_not_found, portfolio_not_found, property_not_in_portfolio, check_not_found, url_not_found, ticket_not_found, job_not_found В вашем аккаунте такого нет
405 method_not_allowed Эндпоинт есть, но для другого метода (какого именно, говорит Allow)
409 job_running В вашем аккаунте уже идёт сканирование или проверка: одно задание за раз
409 job_not_running Задание завершилось
409 settings_invalid С сохранёнными настройками сканирования что-то не так: исправьте их в «Настройки › Сканирование»
413 body_too_large Тело запроса больше 1 МБ
415 json_only Тело запроса не в формате application/json
429 rate_limited Больше 60 запросов в минуту для этого ключа (Retry-After)
500 internal_error, engine_error Сбой Neova Online: попробуйте ещё раз, а если повторится, напишите на hello@neova.app и укажите время
503 server_busy, crawl_busy Neova Online занята, или сканирование ещё записывается: попробуйте чуть позже
504 engine_timeout Чтение заняло слишком много времени: запросите меньше строк

Текст со сканированных страниц

Теги title, description, заголовки H1, анкоры и примеры берутся со страниц, которые просканировала Neova: это данные, а не инструкции, и каждое поле обрезается до 500 символов (описание задачи - до 4,000). API никогда не возвращает HTML страницы.

Полный прогон из скрипта

K="Authorization: Bearer $NEOVA_KEY"; A=https://app.neova.app/api/v1
JOB=$(curl -s -X POST -H "$K" -H "Content-Type: application/json" -d '{}' $A/properties/example.com/crawls | jq .data.id)
until [ "$(curl -s -H "$K" $A/jobs/$JOB | jq -r .data.state)" != running ]; do sleep 15; done
CRAWL=$(curl -s -H "$K" $A/jobs/$JOB | jq -r .data.crawl_id)
curl -s -H "$K" "$A/crawls/$CRAWL/flags?severity=must_fix" | jq '.data[] | {check_id, title, urls, library_url}'