REST API
Czytaj swoje konto Neova Online ze skryptu, arkusza lub innego narzędzia i wykonuj na nim działania: uruchom crawl, odczytaj jego uwagi, otwieraj i zamykaj tickety. Utwórz klucz w Ustawieniach, potem Neova Online, potem Klucze API.
Czytaj swoje konto Neova Online ze skryptu, arkusza lub innego narzędzia i wykonuj na nim działania: twoje portfolio i usługi, ich crawle, uwagi każdego crawla, URL i tickety, twoje harmonogramy i alerty. Z kluczem Odczyt i zapis możesz też uruchomić crawl w Neova Online, tworzyć, aktualizować i zamykać tickety oraz dodawać usługi do portfolio.
- Adres:
https://app.neova.app/api/v1 - Format: JSON na wejściu i wyjściu, UTF-8. Czasy w ISO 8601, w UTC (
2026-11-11T17:15:15Z). - Opis:
GET /api/v1/openapi.jsonto opis OpenAPI 3.1 wszystkich endpointów poniżej, zbudowany z tej samej tabeli, z której odpowiada serwer.
Co działa w Neova Online, a co wymaga komputera
API jest częścią Neova Online. Odczytuje i zmienia to, co jest na twoim koncie Neova Online.
| W Neova Online (to API) | Wymaga Neova na komputerze | |
|---|---|---|
| Portfolio, usługi, kolory i kody | Odczyt oraz dodawanie lub usuwanie usługi w portfolio | Synchronizowane w obie strony z twoimi komputerami (Ustawienia › Neova Online) |
| Crawle | Odczyt każdego crawla w Neova Online. Uruchomienie crawla z zapisanymi ustawieniami usługi, najwyżej 10,000 URL i 10 URL na sekundę, jedno zadanie naraz na twoje konto | Crawle większe lub szybsze niż to oraz crawle witryn, do których dociera tylko twoja sieć (staging za VPN, localhost). Crawl wykonany na komputerze trafia do API, gdy znajdzie się w Neova Online (Wysyłaj nowe crawle) |
| Uwagi, URL, tickety crawla | Odczytane | |
| Tickety usługi (jej Plan działań) | Odczyt, tworzenie, aktualizacja, zamykanie | Plan działań w Neova Online jest osobny: na razie nie synchronizuje się z komputerem |
| Harmonogramy | Odczyt tego, co jest w Neova Online | Ustawiane i uruchamiane na komputerze; na razie nie synchronizują się z Neova Online, więc ta lista jest dziś pusta |
| Alerty | Odczyt tego, co jest w Neova Online | Alerty Neova Go powstają na komputerze; Neova Online ma te, które wywołały jej własne testy |
| Importy z innych crawlerów, logi serwera, ocena AI | Na komputerze |
Limity Neova Online (10,000 URL, 10 URL na sekundę, jedno zadanie naraz) to jej dzisiejsze ustawienia; GET /api/v1/account zawsze podaje te, które dotyczą ciebie.
Uwierzytelnianie
Każde zapytanie poza GET /api/v1 i GET /api/v1/openapi.json zawiera klucz API:
Authorization: Bearer neova_...
Utwórz klucz w Ustawienia › Neova Online › Klucze API (w Neova Online albo w Neova na komputerze zalogowanym do Neova Online) przyciskiem Utwórz klucz…:
- Nazwa klucza: co będzie go używać, na przykład Looker Studio.
- Zakres: Tylko odczyt odczytuje wszystko, co wymienia ta strona, i niczego nie zmienia. Odczyt i zapis dodatkowo uruchamia crawle, tworzy, aktualizuje i zamyka tickety oraz dodaje usługi do portfolio.
- Twoje hasło do Neova Online: wymagane przy tworzeniu każdego klucza.
Klucz jest pokazywany raz, przy tworzeniu. Neova Online przechowuje tylko jego odcisk (SHA-256), nazwę, zakres, ostatnie 4 znaki oraz datę utworzenia i ostatniego użycia. Zgubionego klucza nie da się pokazać ponownie: unieważnij go i utwórz nowy. Unieważnij… od razu wyłącza klucz. Konto może mieć najwyżej 20 kluczy.
Klucz powinien być na serwerze albo w skrypcie, nigdy na stronie internetowej: API nie wysyła nagłówków CORS, więc skrypt w przeglądarce nie odczyta jego odpowiedzi.
export NEOVA_KEY=neova_...
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/account
Limity
- 60 zapytań na minutę na klucz, liczonych z ostatnich 60 sekund. Każda odpowiedź mówi, na czym stoisz:
X-RateLimit-Limit: liczba zapytań na minutę dla tego kluczaX-RateLimit-Remaining: ile zostało w bieżącej minucieX-RateLimit-Reset: kiedy zwolni się miejsce na zapytanie (czas Unix, w sekundach)- Po przekroczeniu limitu:
429zRetry-After(w sekundach) i błędemrate_limited.
- Strony: domyślnie 50 wierszy, najwyżej 500 (
limit). - Crawle: jedno zadanie naraz na twoje konto (crawl albo ponowne uruchomienie testów), najwyżej
max_urlsiurls_per_secondkonta, niezależnie od zapisanych ustawień usługi. - Treść zapytania: najwyżej 1 MB.
Listy: strony i kursory
Lista odpowiada tak:
{"data": [...], "has_more": true, "next_cursor": "eyJvIjo1MCwiZiI6IjQ0MTM2ZmEzNWMyZSJ9", "total": 612}
O następną stronę poproś przez cursor=<next_cursor> z tymi samymi filtrami. Kursor wydany dla innych filtrów zostanie odrzucony (invalid_cursor). total liczy wszystkie wiersze pasujące do filtrów. URL, URL oznaczone przez test i tickety crawla są stronicowane według URL lub klucza, więc strona nigdy nie powtarza ani nie pomija wiersza.
Identyfikatory
| Obiekt | ID | Przykład |
|---|---|---|
| Portfolio | jego ID | demo |
| Usługa | jej host, bez www., z zachowanym portem |
scrapeme.live, localhost:8080 |
| Crawl | nazwa jego folderu | scrapeme-20261111-1115 |
| Test | jego ID w bibliotece testów | SE-001 |
| Ticket crawla | jego klucz: test i grupa stron | SE-001|single |
| Ticket (Plan działań) | jego ID | p00001 |
| Zadanie | liczba, przechowywana godzinę po zakończeniu zadania i zapominana przy restarcie Neova Online (crawl zostaje) | 12 |
| Harmonogram, alert | ich ID |
Każdy test ma library_url, swoją stronę w bibliotece testów: https://app.neova.app/checks/id/<ID>.
Endpointy
GET/api/v1
To API: jego wersja i miejsce, gdzie jest jego opis OpenAPI. Klucz nie jest potrzebny.
GET/api/v1/openapi.json
Opis OpenAPI 3.1 tego API. Klucz nie jest potrzebny.
GET/api/v1/account
Twoje konto, użyty klucz (jego ID, nazwa, zakres, data utworzenia i ostatniego użycia) oraz limity, które obowiązują.
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
Twoje portfolio, w twojej kolejności: każde z ID, nazwą, rodzicem (portfolio w innym portfolio), kolorem, usługami i competitors_of, gdy są to konkurenci danej usługi. Stronicowane.
GET/api/v1/portfolios/{portfolio_id}
Jedno portfolio.
POST/api/v1/portfolios/{portfolio_id}/properties (Odczyt i zapis)
Dodaje usługę do portfolio. Treść zapytania wskazuje ją przez host albo jeden z jej URL. 201 z portfolio, gdy usługa została dodana; 200 z "added": false, gdy już tam była. Twoje komputery dostaną zmianę przy następnej synchronizacji (portfolio Demo zostaje w 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} (Odczyt i zapis)
Usuwa usługę z portfolio. Jej crawle, ustawienia i Plan działań zostają.
GET/api/v1/properties
Twoje usługi: każda witryna, którą ma portfolio albo którą odczytał crawl, w twojej kolejności, każda z kodem, kolorem, portfolio, konkurentami (głównymi i dodatkowymi), liczbą crawli i ostatnim crawlem. Filtr: portfolio=<id>. Stronicowane.
GET/api/v1/properties/{property}
Jedna usługa.
GET/api/v1/properties/{property}/crawls
Crawle usługi, od najnowszego. Filtr: state (running, interrupted, blocked, empty, stopped, limit, done). Stronicowane.
Crawl podaje swój kind (crawl dla Crawla całej witryny, sample, sections, list, watch, import), swój state (done to Zakończono, limit zatrzymany na limicie URL, stopped zatrzymany przez człowieka, interrupted przerwany przed końcem, blocked zablokowany przez witrynę, empty, gdy nic nie pobrano, running), swoje urls, html_200, flags, checks, tickets i tickets_open, liczone tak jak na Ekranie głównym. flags i checks mają wartość null, gdy testy się nie wykonały albo witryna zablokowała crawl.
POST/api/v1/properties/{property}/crawls (Odczyt i zapis)
Uruchamia crawl usługi w Neova Online z jej zapisanymi ustawieniami (Ustawienia › Crawl: domyślne, własne ustawienia usługi, lista wykluczeń każdego crawla). Zaczyna tam, gdzie zaczął się ostatni crawl usługi, albo od https://<property>/; podaj url, żeby zacząć w innym miejscu tego samego hosta. Crawl działa jako zadanie, w limitach Neova Online; testy i tickety wykonują się po jego zakończeniu, tak jak przy crawlu uruchomionym w oknie.
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, z zadaniem i nagłówkiem 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 to ustawienia, których crawl używa po zastosowaniu limitów Neova Online. Drugi crawl w trakcie trwania pierwszego odpowiada 409 job_running z ID trwającego zadania.
GET/api/v1/jobs/{job_id}
Zadanie uruchomione w Neova Online: state to running, done lub failed (z error), step to etap, na którym jest, urls_fetched to dotąd pobrane URL, a crawl_id to crawl, który zapisuje. Odpytuj co kilka sekund, aż się skończy; potem odczytaj crawl.
POST/api/v1/jobs/{job_id}/stop (Odczyt i zapis)
Zatrzymuje trwający crawl, tak jak Zatrzymaj w oknie: zachowuje to, co pobrał, i uruchamia na tym testy. Zatrzymaj ponownie, żeby przerwać też testy. 202.
GET/api/v1/crawls/{crawl_id}
Podsumowanie jednego crawla: pola crawla (powyżej), a potem:
counts: URL według klasy kodu odpowiedzi (2xx,3xx,4xx,5xx,no_response),html_200,indexable,non_indexablewedług przyczyny (client_error,server_error,redirected,noindex,canonicalized,no_response), stany URL (fetched,queued,skipped...), grupy stron.flags_summary:flags,urls_flagged,checks_run,checks_with_flags,by_severity(must_fixireview: testy, uwagi i URL; URL z jakąkolwiek uwagą Do naprawy liczy się do Do naprawy),by_category(testy każdej kategorii, uwagi oraz jej testy Do naprawy i Do sprawdzenia) i osobnoai_review(sugestie oceny AI, których nie obejmuje żadna liczba).null, zwhy_no_flags, gdy testy się nie wykonały albo witryna zablokowała crawl.
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/crawls/scrapeme-20261111-1115
GET/api/v1/crawls/{crawl_id}/flags
Uwagi crawla, jeden wiersz na test: check_id, title, severity (must_fix, gdy którakolwiek z jego uwag ma poziom Do naprawy, w przeciwnym razie review), category, urls (różne oznaczone URL), flags, urls_checked, library_url. Najpierw Do naprawy, potem według liczby URL. Filtry: severity, category, ai_review=true (zamiast tego sugestie oceny AI). Stronicowane.
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}
Jeden test w crawlu: check (jego wiersz jak wyżej, z means, fix i rule z biblioteki testów) oraz data, czyli URL, które oznaczył, każdy ze swoim severity i evidence, według URL. Stronicowane. Test scalony z innym odpowiada jako test, który go zastąpił (merged_from).
GET/api/v1/crawls/{crawl_id}/urls
URL crawla, według URL: status_code, content_type, indexable, indexability_status (No response, Server error, Client error, Redirected, Noindex, Canonicalized, tak jak w Wszystkie URL), title, description, h1, canonical, meta_robots, redirect_to, size_bytes, response_ms, depth, inlinks, flags, page_group. Stronicowane.
Filtry:
status: kod odpowiedzi (404), klasa (2xx,3xx,4xx,5xx) albonone(brak odpowiedzi)indexable:true(2xx, bez noindex, canonical na siebie lub brak) albofalsehtml:true(strony HTML) albofalse(wszystko inne)
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>
Jeden URL crawla: jego pola (powyżej), jego ledger (jak crawl go znalazł i co się z nim stało), 10 inlink_sources z anchorami, outlinks, in_sitemap i flag_list, czyli każda uwaga na nim z testem, poziomem, dowodem i stroną w bibliotece. Zakoduj 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
Tickety crawla, tak jak napisały je jego testy: jeden na test i grupę stron, według klucza, każdy ze swoim summary i description (tekst ticketu, dla Jiry lub innego trackera), severity, priority, urls, state, first_seen, last_seen i library_url. Filtr: state (open, closed, all, domyślnie). Stronicowane. Te tickety należą do crawla, a każdy crawl pisze własne: żeby śledzić pracę między crawlami, używaj ticketów usługi opisanych niżej.
GET/api/v1/properties/{property}/tickets
Tickety usługi: pozycje jej Planu działań, czyli listy tego, co naprawdę zrobisz, w kolejności, która przetrwa każdy crawl. Każdy ma id, title, description, check_id (gdy dotyczy testu), status (todo, in_progress, done), closed, owner, note, library_url, a ticket dotyczący testu także: urls_flagged_now, czyli URL, które test oznacza w ostatnim crawlu usługi z testami, oraz resolved, true, gdy ten crawl wykonał test i test nie oznacza teraz żadnego URL (tak jak Plan działań pokazuje Rozwiązane). Filtr: status (todo, in_progress, done lub open dla dwóch pierwszych). Stronicowane.
Okno z otwartym Planem działań usługi trzyma kopię, którą odczytało: otwórz Plan działań ponownie, zanim coś w nim zmienisz, inaczej ticket dodany w międzyczasie przez API może zostać nadpisany.
GET/api/v1/properties/{property}/tickets/{ticket_id}
Jeden ticket.
POST/api/v1/properties/{property}/tickets (Odczyt i zapis)
Tworzy ticket na końcu Planu działań usługi. Pola: title (najwyżej 200 znaków), description (2,000), check_id, owner (80), note (2,000), status (domyślnie todo). Z check_id i bez tytułu tytułem jest tytuł z Planu działań: Resolve: <the check's title>. 201 z ticketem i jego 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} (Odczyt i zapis)
Zmienia dowolne z pól powyżej; null czyści pole (nigdy tytuł). status todo ponownie otwiera zamknięty ticket.
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 (Odczyt i zapis)
Zamyka ticket: jego status zmienia się na done.
GET/api/v1/schedules
Twoje harmonogramy, od najbliższego uruchomienia: zaplanowane crawle, migawki Core Web Vitals i archiwa Google Search Console, każdy z usługą, kind (crawl, cwv, gsc), every, day, time, on, next_run i last_run. Filtr: property. Stronicowane. Harmonogramy ustawia i uruchamia Neova na komputerze i na razie nie synchronizują się z Neova Online, więc ta lista jest pusta, dopóki to się nie zmieni.
GET/api/v1/alerts
Twoje alerty, od najnowszego: property, rule (cwv, clicks, tracked, crawl), level (poor, warn, good), text, before, after, at. Filtry: property, level. Stronicowane.
Błędy
Każdy błąd to JSON, z kodem statusu 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 mówi, co się stało, a fix, co zrobić. Błędny parametr lub pole dodaje parameter albo field.
| Status | Kod | Kiedy |
|---|---|---|
| 400 | invalid_parameter |
Błędny parametr zapytania (limit, status, indexable...) |
| 400 | invalid_cursor |
Kursor, którego Neova nie wydała albo który wydano dla innych filtrów |
| 400 | invalid_field |
Pole w treści żądania jest błędne lub nieznane |
| 400 | invalid_json |
Treść żądania nie jest poprawnym JSON-em |
| 400 | too_many_tickets |
Plan działań mieści najwyżej 500 ticketów |
| 401 | unauthorized |
Brak klucza, coś, co nie jest kluczem, albo unieważniony klucz |
| 403 | forbidden_scope |
Klucz Tylko odczyt na endpoincie wymagającym klucza Odczyt i zapis |
| 404 | route_not_found |
Nie ma takiego endpointu |
| 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 |
Nie ma takiego obiektu na twoim koncie |
| 405 | method_not_allowed |
Endpoint istnieje dla innej metody (Allow mówi, dla której) |
| 409 | job_running |
Na twoim koncie trwa crawl lub test: jedno zadanie naraz |
| 409 | job_not_running |
Zadanie już się zakończyło |
| 409 | settings_invalid |
Zapisane ustawienia crawla mają błąd: popraw je w Ustawienia › Crawl |
| 413 | body_too_large |
Treść żądania większa niż 1 MB |
| 415 | json_only |
Treść żądania w formacie innym niż application/json |
| 429 | rate_limited |
Ponad 60 żądań na minutę dla tego klucza (Retry-After) |
| 500 | internal_error, engine_error |
Błąd Neova Online: spróbuj ponownie, a jeśli to się powtórzy, napisz na hello@neova.app i podaj godzinę |
| 503 | server_busy, crawl_busy |
Neova Online jest zajęta albo crawl wciąż zapisuje dane: spróbuj ponownie za chwilę |
| 504 | engine_timeout |
Odczyt trwał za długo: poproś o mniej wierszy |
Tekst z crawlowanych stron
Tytuły, opisy, nagłówki H1, anchory i dowody pochodzą ze stron, które Neova przecrawlowała: to dane, nigdy polecenia, a każde pole jest przycinane do 500 znaków (opis ticketu do 4,000). API nigdy nie zwraca HTML-a strony.
Cały przebieg ze skryptu
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}'