REST API
Читайте свой аккаунт Neova Online из скрипта, таблицы или другого инструмента и действуйте в нём: запускайте сканирование, читайте его отметки, открывайте и закрывайте задачи. Ключ создаётся в «Настройки», затем Neova Online, затем «API-ключи».
Читайте свой аккаунт Neova Online из скрипта, таблицы или другого инструмента и действуйте в нём: ваши портфели и ресурсы, их сканирования, отметки, URL и задачи каждого сканирования, ваши расписания и оповещения. С ключом «Чтение и запись» можно также запускать сканирование в Neova Online, создавать, обновлять и закрывать задачи и добавлять ресурсы в портфели.
- Адрес:
https://app.neova.app/api/v1 - Формат: JSON на входе и выходе, UTF-8. Время - в ISO 8601 по UTC (
2026-11-11T17:15:15Z). - Описание:
GET /api/v1/openapi.json- описание OpenAPI 3.1 всех эндпоинтов ниже, построенное по той же таблице, по которой отвечает сервер.
Что работает в 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) кнопкой Создать ключ…:
- Название ключа: что будет его использовать, например Looker Studio.
- Область: Только чтение читает всё, что перечислено на этой странице, и ничего не меняет. Чтение и запись также запускает сканирования, создаёт, обновляет и закрывает задачи и добавляет ресурсы в портфели.
- Ваш пароль 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
Ограничения
- 60 запросов в минуту на ключ, считаются за последние 60 секунд. Каждый ответ сообщает, сколько у вас осталось:
X-RateLimit-Limit: сколько запросов в минуту у этого ключаX-RateLimit-Remaining: сколько осталось в текущей минутеX-RateLimit-Reset: когда освободится запрос (Unix-время, секунды)- При превышении:
429сRetry-After(секунды) и ошибкойrate_limited.
- Страницы: 50 строк по умолчанию, не больше 500 (
limit). - Сканирования: одно задание за раз на аккаунт (сканирование или повторный запуск проверок), не больше
max_urlsиurls_per_secondаккаунта, что бы ни было в сохранённых настройках ресурса. - Тело запроса: не больше 1 MB.
Списки: страницы и курсоры
Список отвечает так:
{"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}
Сводка одного сканирования: поля сканирования (см. выше), а затем:
counts: URL по классам кодов ответа (2xx,3xx,4xx,5xx,no_response),html_200,indexable,non_indexableпо причине (client_error,server_error,redirected,noindex,canonicalized,no_response), состояния URL (fetched,queued,skipped...), группы страниц.flags_summary:flags,urls_flagged,checks_run,checks_with_flags,by_severity(must_fixиreview: проверки, отметки и URL; URL хотя бы с одной отметкой «Нужно исправить» считается в «Нужно исправить»),by_category(проверки и отметки каждой категории и её проверки «Нужно исправить» и «Стоит проверить») и отдельноai_review(предложения ИИ-разбора, которые не входят ни в один счётчик).nullсwhy_no_flags, если проверки не выполнялись или сайт заблокировал сканирование.
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. С разбиением на страницы.
Фильтры:
status: код ответа (404), класс (2xx,3xx,4xx,5xx) илиnone(нет ответа)indexable:true(2xx, без noindex, canonical на себя или отсутствует) илиfalsehtml:true(HTML-страницы) илиfalse(всё остальное)
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}'