NeovaZaawansowana platforma SEO

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.

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…:

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

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:

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:

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}'