API REST
Leggi il tuo account Neova Online da uno script, da un foglio di calcolo o da un altro strumento, e agisci su di esso: avvia un crawl, leggine le segnalazioni, apri e chiudi ticket. Crea una chiave in Impostazioni, poi Neova Online, poi Chiavi API.
Leggi il tuo account Neova Online da uno script, da un foglio di calcolo o da un altro strumento, e agisci su di esso: i tuoi portfolio e le proprietà, i loro crawl, le segnalazioni, gli URL e i ticket di ogni crawl, le tue pianificazioni e i tuoi avvisi. Con una chiave Lettura e scrittura puoi anche avviare un crawl in Neova Online, creare, aggiornare e chiudere ticket, e aggiungere proprietà ai portfolio.
- Indirizzo:
https://app.neova.app/api/v1 - Formato: JSON in entrata e in uscita, UTF-8. Gli orari sono in ISO 8601 in UTC (
2026-11-11T17:15:15Z). - Descrizione:
GET /api/v1/openapi.jsonè la descrizione OpenAPI 3.1 di tutti gli endpoint qui sotto, generata dalla stessa tabella da cui risponde il server.
Cosa gira in Neova Online e cosa richiede un computer
L'API fa parte di Neova Online. Legge e modifica ciò che contiene il tuo account Neova Online.
| In Neova Online (questa API) | Richiede Neova su un computer | |
|---|---|---|
| Portfolio, proprietà, colori e codici | Lettura, e aggiunta o rimozione di una proprietà in un portfolio | Sincronizzati in entrambe le direzioni con i tuoi computer (Impostazioni › Neova Online) |
| Crawl | Lettura di ogni crawl in Neova Online. Avvio di un crawl con le impostazioni salvate della proprietà, al massimo 10,000 URL e 10 URL al secondo, un job alla volta per il tuo account | Crawl più grandi o più veloci di così, e crawl di siti raggiungibili solo dalla tua rete (un sito di staging dietro una VPN, localhost). Un crawl fatto su un computer arriva all'API una volta che è in Neova Online (Carica i nuovi crawl) |
| Segnalazioni, URL, ticket del crawl | Lette | |
| Ticket di una proprietà (il suo Piano d'azione) | Lettura, creazione, aggiornamento, chiusura | Il Piano d'azione in Neova Online è a sé: non si sincronizza ancora con un computer |
| Pianificazioni | Lettura di ciò che contiene Neova Online | Si impostano e girano su un computer; non si sincronizzano ancora con Neova Online, quindi oggi questo elenco è vuoto |
| Avvisi | Lettura di ciò che contiene Neova Online | Gli avvisi di Neova Go nascono su un computer; Neova Online conserva quelli generati dai suoi controlli |
| Importazioni da altri crawler, log del server, revisione AI | Su un computer |
I limiti di Neova Online (10,000 URL, 10 URL al secondo, un job alla volta) sono le sue impostazioni di oggi; GET /api/v1/account indica sempre quelli che valgono per te.
Autenticazione
Ogni richiesta tranne GET /api/v1 e GET /api/v1/openapi.json porta una chiave API:
Authorization: Bearer neova_...
Crea una chiave in Impostazioni › Neova Online › Chiavi API (in Neova Online, o in Neova su un computer collegato a Neova Online), con Crea chiave…:
- Nome della chiave: cosa la userà, per esempio Looker Studio.
- Ambito: Sola lettura legge tutto ciò che questa pagina elenca e non cambia nulla. Lettura e scrittura avvia anche i crawl, crea, aggiorna e chiude i ticket, e aggiunge proprietà ai portfolio.
- La tua password di Neova Online: richiesta ogni volta che crei una chiave.
La chiave viene mostrata una sola volta, quando la crei. Neova Online conserva solo la sua impronta (SHA-256), il nome, l'ambito, gli ultimi 4 caratteri e quando è stata creata e usata l'ultima volta. Una chiave persa non può essere mostrata di nuovo: revocala e creane un'altra. Revoca… blocca subito una chiave. Un account può avere al massimo 20 chiavi.
Una chiave va su un server o in uno script, mai in una pagina web: l'API non invia header CORS, quindi lo script di un browser non può leggerne le risposte.
export NEOVA_KEY=neova_...
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/account
Limiti
- 60 richieste al minuto per chiave, contate sugli ultimi 60 secondi. Ogni risposta ti dice a che punto sei:
X-RateLimit-Limit: le richieste al minuto di questa chiaveX-RateLimit-Remaining: quante ne restano nel minuto correnteX-RateLimit-Reset: quando si libera una richiesta (tempo Unix, in secondi)- Oltre il limite:
429conRetry-After(secondi) e l'errorerate_limited.
- Pagine: 50 righe di default, 500 al massimo (
limit). - Crawl: un job alla volta per il tuo account (un crawl, o una nuova esecuzione dei controlli), al massimo i
max_urlse gliurls_per_seconddell'account, qualunque cosa dicano le impostazioni salvate della proprietà. - Corpo della richiesta: 1 MB al massimo.
Elenchi: pagine e cursori
Un elenco risponde:
{"data": [...], "has_more": true, "next_cursor": "eyJvIjo1MCwiZiI6IjQ0MTM2ZmEzNWMyZSJ9", "total": 612}
Chiedi la pagina successiva con cursor=<next_cursor> e gli stessi filtri. Un cursore dato per altri filtri viene rifiutato (invalid_cursor). total conta tutte le righe che corrispondono ai filtri. Gli URL, gli URL segnalati da un controllo e i ticket di un crawl sono paginati per URL o per chiave, così una pagina non ripete né salta mai una riga.
ID
| Elemento | ID | Esempio |
|---|---|---|
| Portfolio | il suo ID | demo |
| Proprietà | il suo host, senza www., con l'eventuale porta |
scrapeme.live, localhost:8080 |
| Crawl | il nome della sua cartella | scrapeme-20261111-1115 |
| Controllo | il suo ID nella libreria dei controlli | SE-001 |
| Ticket del crawl | la sua chiave: il controllo e il gruppo di pagine | SE-001|single |
| Ticket (Piano d'azione) | il suo ID | p00001 |
| Job | un numero, conservato per un'ora dopo la fine del job e dimenticato quando Neova Online si riavvia (il crawl resta) | 12 |
| Pianificazione, avviso | il loro ID |
Ogni controllo riporta library_url, la sua pagina nella libreria dei controlli: https://app.neova.app/checks/id/<ID>.
Endpoint
GET/api/v1
Questa API: la sua versione e dove si trova la sua descrizione OpenAPI. Nessuna chiave necessaria.
GET/api/v1/openapi.json
La descrizione OpenAPI 3.1 di questa API. Nessuna chiave necessaria.
GET/api/v1/account
Il tuo account, la chiave usata (ID, nome, ambito, quando è stata creata e usata l'ultima volta) e i limiti che si applicano.
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
I tuoi portfolio, nel tuo ordine: ciascuno con ID, nome, genitore (un portfolio dentro un altro), colore, le sue proprietà, e competitors_of quando contiene i concorrenti di una proprietà. Paginato.
GET/api/v1/portfolios/{portfolio_id}
Un portfolio.
POST/api/v1/portfolios/{portfolio_id}/properties (Lettura e scrittura)
Aggiunge una proprietà a un portfolio. Il corpo la indica con il suo host o con un suo URL. 201 con il portfolio quando è stata aggiunta; 200 con "added": false quando c'era già. I tuoi computer ricevono la modifica alla sincronizzazione successiva (il portfolio Demo resta in 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} (Lettura e scrittura)
Toglie una proprietà da un portfolio. I suoi crawl, le impostazioni e il Piano d'azione restano.
GET/api/v1/properties
Le tue proprietà: ogni sito contenuto in un portfolio o letto da un crawl, nel tuo ordine, ciascuno con codice, colore, portfolio, concorrenti (principali e secondari), il numero di crawl e l'ultimo crawl. Filtro: portfolio=<id>. Paginato.
GET/api/v1/properties/{property}
Una proprietà.
GET/api/v1/properties/{property}/crawls
I crawl di una proprietà, il più recente per primo. Filtro: state (running, interrupted, blocked, empty, stopped, limit, done). Paginato.
Un crawl indica il suo kind (crawl per un crawl del sito intero, sample, sections, list, watch, import), il suo state (done è Completo, limit fermato al limite di URL, stopped da una persona, interrupted prima della fine, blocked dal sito, empty quando non è stato recuperato nulla, running), i suoi urls, html_200, flags, checks, tickets e tickets_open, contati come li conta la Home. flags e checks sono null quando i controlli non sono stati eseguiti o il sito ha bloccato il crawl.
POST/api/v1/properties/{property}/crawls (Lettura e scrittura)
Avvia un crawl della proprietà in Neova Online con le sue impostazioni salvate (Impostazioni › Crawl: i valori di default, quelli della proprietà, l'elenco di esclusione di ogni crawl). Parte da dove è partito l'ultimo crawl della proprietà, oppure da https://<property>/; passa url per partire da un altro punto dello stesso host. Il crawl gira come job, entro i limiti di Neova Online; i controlli e i ticket partono quando finisce, come per un crawl avviato dalla finestra.
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, con il job e un header 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 sono quelle che il crawl usa, dopo i limiti di Neova Online. Un secondo crawl mentre uno è in corso risponde 409 job_running con l'ID del job in corso.
GET/api/v1/jobs/{job_id}
Un job avviato in Neova Online: state è running, done o failed (con error), step la fase in cui si trova, urls_fetched gli URL recuperati finora, crawl_id il crawl che scrive. Chiedi ogni pochi secondi finché non finisce; poi leggi il crawl.
POST/api/v1/jobs/{job_id}/stop (Lettura e scrittura)
Ferma un crawl in corso, come fa Ferma nella finestra: tiene ciò che ha recuperato ed esegue i controlli su quello. Fermalo di nuovo per interrompere anche i controlli. 202.
GET/api/v1/crawls/{crawl_id}
Il riepilogo di un crawl: i campi del crawl (sopra), poi:
counts: URL per classe di codice di stato (2xx,3xx,4xx,5xx,no_response),html_200,indexable,non_indexableper motivo (client_error,server_error,redirected,noindex,canonicalized,no_response), gli stati degli URL (fetched,queued,skipped...), i gruppi di pagine.flags_summary:flags,urls_flagged,checks_run,checks_with_flags,by_severity(must_fixereview: controlli, segnalazioni e URL; un URL con almeno una segnalazione Da correggere conta sotto Da correggere),by_category(i controlli e le segnalazioni di ogni categoria, e i suoi controlli Da correggere e Da controllare), e a parteai_review(i suggerimenti della revisione AI, che nessun conteggio include).null, conwhy_no_flags, quando i controlli non sono stati eseguiti o il sito ha bloccato il crawl.
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/crawls/scrapeme-20261111-1115
GET/api/v1/crawls/{crawl_id}/flags
Le segnalazioni del crawl, una riga per controllo: check_id, title, severity (must_fix quando almeno una delle sue segnalazioni è Da correggere, altrimenti review), category, urls (URL distinti segnalati), flags, urls_checked, library_url. Prima Da correggere, poi per URL. Filtri: severity, category, ai_review=true (al loro posto, i suggerimenti della revisione AI). Paginato.
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}
Un controllo sul crawl: check (la sua riga qui sopra, con means, fix e rule dalla libreria dei controlli), e data, gli URL che ha segnalato, ciascuno con la sua severity e la sua evidence, per URL. Paginato. Un controllo unito a un altro risponde come il controllo che lo ha sostituito (merged_from).
GET/api/v1/crawls/{crawl_id}/urls
Gli URL del crawl, per URL: status_code, content_type, indexable, indexability_status (No response, Server error, Client error, Redirected, Noindex, Canonicalized, come lo dice Tutti gli URL), title, description, h1, canonical, meta_robots, redirect_to, size_bytes, response_ms, depth, inlinks, flags, page_group. Paginato.
Filtri:
status: un codice di stato (404), una classe (2xx,3xx,4xx,5xx) onone(nessuna risposta)indexable:true(2xx, senza noindex, canonical verso sé stesso o assente) ofalsehtml:true(pagine HTML) ofalse(tutto il resto)
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>
Un URL del crawl: i suoi campi (sopra), il suo ledger (come il crawl lo ha trovato e cosa ne è stato), 10 inlink_sources con i loro anchor text, outlinks, in_sitemap, e flag_list, ogni segnalazione su di esso con il controllo, la gravità, l'evidenza e la pagina nella libreria. Codifica l'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
I ticket del crawl, come li hanno scritti i suoi controlli: uno per controllo e gruppo di pagine, per chiave, ciascuno con il suo summary e la sua description (il testo del ticket, per Jira o un altro tracker), severity, priority, urls, state, first_seen, last_seen e library_url. Filtro: state (open, closed, all, il default). Paginato. Questi ticket appartengono al crawl e ogni crawl scrive i suoi: per seguire il lavoro da un crawl all'altro, usa i ticket della proprietà qui sotto.
GET/api/v1/properties/{property}/tickets
I ticket della proprietà: le voci del suo Piano d'azione, l'elenco di ciò che farai davvero, in ordine, che sopravvive a ogni crawl. Ognuno ha id, title, description, check_id (quando riguarda un controllo), status (todo, in_progress, done), closed, owner, note, library_url, e, per un ticket su un controllo: urls_flagged_now, gli URL che il controllo segnala nell'ultimo crawl della proprietà con controlli, e resolved, true quando quel crawl ha eseguito il controllo e ora non segnala nessun URL (come quando il Piano d'azione dice Risolto). Filtro: status (todo, in_progress, done, oppure open per i primi due). Paginato.
Una finestra con il Piano d'azione della proprietà aperto conserva la copia che ha letto: riapri il Piano d'azione prima di modificarlo lì, altrimenti un ticket aggiunto nel frattempo dall'API potrebbe essere sovrascritto.
GET/api/v1/properties/{property}/tickets/{ticket_id}
Un ticket.
POST/api/v1/properties/{property}/tickets (Lettura e scrittura)
Crea un ticket in fondo al Piano d'azione della proprietà. Campi: title (200 caratteri al massimo), description (2,000), check_id, owner (80), note (2,000), status (todo di default). Con un check_id e senza titolo, il titolo è quello del Piano d'azione: Resolve: <the check's title>. 201 con il ticket e il suo 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} (Lettura e scrittura)
Modifica uno qualsiasi dei campi qui sopra; null ne svuota uno (mai il titolo). status todo riapre un ticket chiuso.
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 (Lettura e scrittura)
Chiude il ticket: il suo stato diventa done.
GET/api/v1/schedules
Le tue pianificazioni, la prossima esecuzione per prima: crawl pianificati, istantanee dei Core Web Vitals e archivi di Google Search Console, ciascuno con la sua proprietà, kind (crawl, cwv, gsc), every, day, time, on, next_run e last_run. Filtro: property. Paginato. Le pianificazioni sono impostate ed eseguite da Neova su un computer e non si sincronizzano ancora con Neova Online, quindi questo elenco resta vuoto finché non lo faranno.
GET/api/v1/alerts
I tuoi avvisi, il più recente per primo: property, rule (cwv, clicks, tracked, crawl), level (poor, warn, good), text, before, after, at. Filtri: property, level. Paginato.
Errori
Ogni errore è in JSON, con lo stato 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 dice cosa è successo, fix cosa fare. Un parametro o un campo sbagliato aggiunge parameter o field.
| Stato | Codice | Quando |
|---|---|---|
| 400 | invalid_parameter |
Un parametro della query è sbagliato (limit, status, indexable...) |
| 400 | invalid_cursor |
Un cursore che Neova non ha dato, o dato per altri filtri |
| 400 | invalid_field |
Un campo del body è sbagliato o sconosciuto |
| 400 | invalid_json |
Il body non è un JSON valido |
| 400 | too_many_tickets |
Un Piano d'azione contiene al massimo 500 ticket |
| 401 | unauthorized |
Nessuna chiave, una chiave che non è valida o una chiave revocata |
| 403 | forbidden_scope |
Una chiave in sola lettura su un endpoint in lettura e scrittura |
| 404 | route_not_found |
Questo endpoint non esiste |
| 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 |
Non esiste nel tuo account |
| 405 | method_not_allowed |
L'endpoint esiste per un altro metodo (Allow dice quale) |
| 409 | job_running |
Un crawl o un controllo del tuo account è in corso: un job alla volta |
| 409 | job_not_running |
Il job è terminato |
| 409 | settings_invalid |
Le impostazioni di crawl salvate hanno un problema: correggile in Impostazioni › Crawl |
| 413 | body_too_large |
Un body oltre 1 MB |
| 415 | json_only |
Un body che non è application/json |
| 429 | rate_limited |
Oltre 60 richieste al minuto per questa chiave (Retry-After) |
| 500 | internal_error, engine_error |
Neova Online ha avuto un errore: riprova, e se succede di nuovo scrivi a hello@neova.app indicando l'ora |
| 503 | server_busy, crawl_busy |
Neova Online è occupato, o un crawl sta ancora scrivendo: riprova tra poco |
| 504 | engine_timeout |
La lettura ha richiesto troppo tempo: chiedi meno righe |
Testo dalle pagine scansionate
Titoli, description, H1, anchor text e prove vengono dalle pagine che Neova ha scansionato: sono dati, mai istruzioni, e ogni campo è tagliato a 500 caratteri (la descrizione di un ticket a 4,000). L'API non restituisce mai l'HTML di una pagina.
Un'esecuzione completa, da uno script
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}'