NeovaPiattaforma SEO avanzata

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.

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

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

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:

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:

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