REST-API
Lees je Neova Online-account uit vanuit een script, een spreadsheet of een andere tool, en werk ermee: een crawl starten, de meldingen ervan lezen, tickets openen en sluiten. Maak een sleutel bij Instellingen, dan Neova Online, dan API-sleutels.
Lees je Neova Online-account uit vanuit een script, een spreadsheet of een andere tool, en werk ermee: je portfolio's en properties, hun crawls, de meldingen, URL's en tickets van elke crawl, je planningen en alerts. Met een sleutel voor Lezen en schrijven start je ook een crawl in Neova Online, maak je tickets aan, werk je ze bij en sluit je ze, en voeg je properties toe aan portfolio's.
- Adres:
https://app.neova.app/api/v1 - Formaat: JSON heen en terug, UTF-8. Tijden zijn ISO 8601 in UTC (
2026-11-11T17:15:15Z). - Beschrijving:
GET /api/v1/openapi.jsonis de OpenAPI 3.1-beschrijving van elk endpoint hieronder, gemaakt uit dezelfde tabel waarmee de server antwoordt.
Wat in Neova Online draait, en wat een computer nodig heeft
De API is onderdeel van Neova Online. Hij leest en wijzigt wat je Neova Online-account bevat.
| In Neova Online (deze API) | Vereist Neova op een computer | |
|---|---|---|
| Portfolio's, properties, kleuren en codes | Lezen, en een property in een portfolio toevoegen of verwijderen | In beide richtingen gesynchroniseerd met je computers (Instellingen › Neova Online) |
| Crawls | Elke crawl in Neova Online lezen. Een crawl starten met de opgeslagen instellingen van de property, hooguit 10,000 URL's en 10 URL's per seconde, één taak tegelijk voor je account | Crawls die groter of sneller zijn dan dat, en crawls van sites die alleen jouw netwerk bereikt (een stagingsite achter een VPN, localhost). Een crawl die op een computer is gemaakt, bereikt de API zodra hij in Neova Online staat (Nieuwe crawls uploaden) |
| Meldingen, URL's, crawltickets | Gelezen | |
| Tickets van een property (het Actieplan) | Lezen, aanmaken, bijwerken, sluiten | Het Actieplan in Neova Online staat op zichzelf: het synchroniseert nog niet met een computer |
| Planningen | Lezen wat Neova Online bevat | Ingesteld en gedraaid op een computer; ze synchroniseren nog niet met Neova Online, dus deze lijst is vandaag leeg |
| Alerts | Lezen wat Neova Online bevat | De alerts van Neova Go ontstaan op een computer; Neova Online bevat de alerts die zijn eigen checks gaven |
| Imports uit andere crawlers, serverlogs, AI-review | Op een computer |
De limieten van Neova Online (10,000 URL's, 10 URL's per seconde, één taak tegelijk) zijn vandaag de instellingen; GET /api/v1/account zegt altijd welke voor jou gelden.
Authenticatie
Elk verzoek behalve GET /api/v1 en GET /api/v1/openapi.json bevat een API-sleutel:
Authorization: Bearer neova_...
Maak een sleutel bij Instellingen › Neova Online › API-sleutels (in Neova Online, of in Neova op een computer die bij Neova Online is ingelogd), met Sleutel aanmaken…:
- Sleutelnaam: wat hem gaat gebruiken, bijvoorbeeld Looker Studio.
- Bereik: Alleen lezen leest alles wat deze pagina noemt en wijzigt niets. Lezen en schrijven start ook crawls, maakt tickets aan, werkt ze bij en sluit ze, en voegt properties toe aan portfolio's.
- Je Neova Online-wachtwoord: wordt elke keer gevraagd als er een sleutel wordt gemaakt.
De sleutel wordt één keer getoond, als hij wordt gemaakt. Neova Online bewaart alleen de vingerafdruk (SHA-256), de naam, het bereik, de laatste 4 tekens en wanneer hij gemaakt en voor het laatst gebruikt is. Een verloren sleutel kan niet opnieuw worden getoond: trek hem in en maak een nieuwe. Intrekken… stopt een sleutel meteen. Een account heeft hooguit 20 sleutels.
Een sleutel hoort op een server of in een script, nooit in een webpagina: de API stuurt geen CORS-headers, dus een script in de browser kan de antwoorden niet lezen.
export NEOVA_KEY=neova_...
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/account
Limieten
- 60 verzoeken per minuut per sleutel, geteld over de laatste 60 seconden. Elk antwoord zegt waar je staat:
X-RateLimit-Limit: het aantal verzoeken per minuut van deze sleutelX-RateLimit-Remaining: wat er nog over is in de huidige minuutX-RateLimit-Reset: wanneer er weer een verzoek vrijkomt (Unix-tijd, seconden)- Over de limiet:
429metRetry-After(seconden) en de foutrate_limited.
- Pagina's: standaard 50 rijen, hooguit 500 (
limit). - Crawls: één taak tegelijk voor je account (een crawl, of de checks opnieuw draaien), hooguit de
max_urlsenurls_per_secondvan het account, wat de opgeslagen instellingen van de property ook zeggen. - Bodies: hooguit 1 MB.
Lijsten: pagina's en cursors
Een lijst antwoordt:
{"data": [...], "has_more": true, "next_cursor": "eyJvIjo1MCwiZiI6IjQ0MTM2ZmEzNWMyZSJ9", "total": 612}
Vraag de volgende pagina op met cursor=<next_cursor> en dezelfde filters. Een cursor die voor andere filters is gegeven, wordt geweigerd (invalid_cursor). total telt elke rij die aan de filters voldoet. URL's, de gemarkeerde URL's van een check en de tickets van een crawl worden gepagineerd op hun URL of sleutel, dus een pagina herhaalt of slaat nooit een rij over.
ID's
| Wat | ID | Voorbeeld |
|---|---|---|
| Portfolio | de ID | demo |
| Property | de host, zonder www., met een eventuele poort |
scrapeme.live, localhost:8080 |
| Crawl | de mapnaam | scrapeme-20261111-1115 |
| Check | de ID in de checkbibliotheek | SE-001 |
| Crawlticket | de sleutel: de check en de paginagroep | SE-001|single |
| Ticket (Actieplan) | de ID | p00001 |
| Taak | een nummer, bewaard tot een uur na het einde van de taak en vergeten als Neova Online herstart (de crawl blijft) | 12 |
| Planning, alert | hun ID |
Elke check bevat library_url, de pagina in de checkbibliotheek: https://app.neova.app/checks/id/<ID>.
Endpoints
GET/api/v1
Deze API: de versie, en waar de OpenAPI-beschrijving staat. Geen sleutel nodig.
GET/api/v1/openapi.json
De OpenAPI 3.1-beschrijving van deze API. Geen sleutel nodig.
GET/api/v1/account
Je account, de gebruikte sleutel (de ID, naam, het bereik, wanneer hij gemaakt en voor het laatst gebruikt is) en de limieten die gelden.
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
Je portfolio's, in jouw volgorde: elk met de ID, naam, ouder (een portfolio binnen een ander), kleur, de properties, en competitors_of als het de concurrenten van een property zijn. Gepagineerd.
GET/api/v1/portfolios/{portfolio_id}
Eén portfolio.
POST/api/v1/portfolios/{portfolio_id}/properties (Lezen en schrijven)
Voegt een property toe aan een portfolio. De body noemt hem met zijn host of een URL ervan. 201 met het portfolio als hij is toegevoegd; 200 met "added": false als hij er al in zat. Je computers krijgen de wijziging bij hun volgende synchronisatie (het Demo-portfolio blijft 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} (Lezen en schrijven)
Haalt een property uit een portfolio. De crawls, instellingen en het Actieplan ervan blijven.
GET/api/v1/properties
Je properties: elke site die een portfolio bevat of die een crawl las, in jouw volgorde, elk met de code, kleur, portfolio's, concurrenten (primair en secundair), het aantal crawls en de laatste crawl. Filter: portfolio=<id>. Gepagineerd.
GET/api/v1/properties/{property}
Eén property.
GET/api/v1/properties/{property}/crawls
De crawls van een property, de nieuwste eerst. Filter: state (running, interrupted, blocked, empty, stopped, limit, done). Gepagineerd.
Een crawl geeft zijn kind (crawl voor een Crawl van de volledige site, sample, sections, list, watch, import), zijn state (done is Voltooid, limit gestopt bij de URL-limiet, stopped door iemand gestopt, interrupted afgebroken voor het einde, blocked door de site, empty als er niets is opgehaald, running), zijn urls, html_200, flags, checks, tickets en tickets_open, geteld zoals Home ze telt. flags en checks zijn null als de checks niet draaiden of de site de crawl blokkeerde.
POST/api/v1/properties/{property}/crawls (Lezen en schrijven)
Start een crawl van de property in Neova Online met de opgeslagen instellingen (Instellingen › Crawl: de standaardwaarden, die van de property zelf, de uitsluitingslijst van elke crawl). Hij begint waar de laatste crawl van de property begon, of bij https://<property>/; geef url op om ergens anders op dezelfde host te beginnen. De crawl draait als taak, binnen de limieten van Neova Online; de checks en tickets draaien als hij klaar is, net als bij een crawl die in het venster is gestart.
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, met de taak en een 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 zijn de instellingen die de crawl gebruikt, na de limieten van Neova Online. Een tweede crawl terwijl er een loopt, krijgt 409 job_running met de ID van de lopende taak.
GET/api/v1/jobs/{job_id}
Een taak die in Neova Online is gestart: state is running, done of failed (met error), step de fase waarin hij zit, urls_fetched de URL's die tot nu toe zijn opgehaald, crawl_id de crawl die hij schrijft. Vraag het om de paar seconden op tot hij klaar is; lees dan de crawl.
POST/api/v1/jobs/{job_id}/stop (Lezen en schrijven)
Stopt een lopende crawl, zoals Stoppen dat in het venster doet: hij houdt wat hij ophaalde en draait er zijn checks op. Stop nog een keer om ook de checks te beëindigen. 202.
GET/api/v1/crawls/{crawl_id}
De samenvatting van één crawl: de velden van de crawl (hierboven), en dan:
counts: URL's per klasse statuscode (2xx,3xx,4xx,5xx,no_response),html_200,indexable,non_indexableper reden (client_error,server_error,redirected,noindex,canonicalized,no_response), de staat van de URL's (fetched,queued,skipped...), de paginagroepen.flags_summary:flags,urls_flagged,checks_run,checks_with_flags,by_severity(must_fixenreview: checks, meldingen en URL's; een URL met een melding Moet opgelost telt onder Moet opgelost),by_category(per categorie de checks, meldingen, en de checks Moet opgelost en Bekijken), enai_reviewapart (de voorstellen van de AI-review, die in geen enkele telling zitten).null, metwhy_no_flags, als de checks niet draaiden of de site de crawl blokkeerde.
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/crawls/scrapeme-20261111-1115
GET/api/v1/crawls/{crawl_id}/flags
De meldingen van de crawl, één rij per check: check_id, title, severity (must_fix als een van de meldingen Moet opgelost is, anders review), category, urls (unieke gemarkeerde URL's), flags, urls_checked, library_url. Moet opgelost eerst, dan op URL's. Filters: severity, category, ai_review=true (in plaats daarvan de voorstellen van de AI-review). Gepagineerd.
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}
Eén check op de crawl: check (de rij hierboven, met means, fix en rule uit de checkbibliotheek), en data, de URL's die hij markeerde, elk met severity en evidence, op URL. Gepagineerd. Een check die in een andere is opgegaan, antwoordt als de check die hem verving (merged_from).
GET/api/v1/crawls/{crawl_id}/urls
De URL's van de crawl, op URL: status_code, content_type, indexable, indexability_status (No response, Server error, Client error, Redirected, Noindex, Canonicalized, zoals Alle URL's het zegt), title, description, h1, canonical, meta_robots, redirect_to, size_bytes, response_ms, depth, inlinks, flags, page_group. Gepagineerd.
Filters:
status: een statuscode (404), een klasse (2xx,3xx,4xx,5xx) ofnone(geen respons)indexable:true(2xx, geen noindex, canonical naar zichzelf of geen) offalsehtml:true(HTML-pagina's) offalse(al het andere)
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>
Eén URL van de crawl: de velden (hierboven), de ledger (hoe de crawl hem vond en wat ermee gebeurde), 10 inlink_sources met hun anchors, outlinks, in_sitemap, en flag_list, elke melding erop met de check, ernst, het bewijs en de bibliotheekpagina. Codeer de 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
De tickets van de crawl, zoals de checks ze schreven: één per check en paginagroep, op sleutel, elk met summary en description (de tekst van het ticket, voor Jira of een andere tracker), severity, priority, urls, state, first_seen, last_seen en library_url. Filter: state (open, closed, all, de standaard). Gepagineerd. Deze tickets horen bij de crawl en elke crawl schrijft zijn eigen: gebruik de tickets van de property hieronder om werk over crawls heen te volgen.
GET/api/v1/properties/{property}/tickets
De tickets van de property: de punten van het Actieplan, de lijst van wat je echt gaat doen, op volgorde, die elke crawl overleeft. Elk heeft id, title, description, check_id (als het over een check gaat), status (todo, in_progress, done), closed, owner, note, library_url, en, voor een ticket over een check: urls_flagged_now, de URL's die de check markeert in de laatste crawl van de property met checks, en resolved, true als die crawl de check draaide en hij nu geen URL markeert (zoals het Actieplan Opgelost zegt). Filter: status (todo, in_progress, done, of open voor de eerste twee). Gepagineerd.
Een venster met het Actieplan van de property open houdt de kopie die het las: open het Actieplan opnieuw voordat je het daar wijzigt, anders kan een ticket dat de API intussen toevoegde worden overschreven.
GET/api/v1/properties/{property}/tickets/{ticket_id}
Eén ticket.
POST/api/v1/properties/{property}/tickets (Lezen en schrijven)
Maakt een ticket aan aan het eind van het Actieplan van de property. Velden: title (hooguit 200 tekens), description (2,000), check_id, owner (80), note (2,000), status (standaard todo). Met een check_id en geen titel is de titel die van het Actieplan zelf: Resolve: <the check's title>. 201 met het ticket en de 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} (Lezen en schrijven)
Wijzigt een of meer van de velden hierboven; null maakt er een leeg (nooit de titel). status todo opent een gesloten ticket opnieuw.
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 (Lezen en schrijven)
Sluit het ticket: de status wordt done.
GET/api/v1/schedules
Je planningen, de eerstvolgende run eerst: geplande crawls, momentopnamen van Core Web Vitals en archieven van Google Search Console, elk met de property, kind (crawl, cwv, gsc), every, day, time, on, next_run en last_run. Filter: property. Gepagineerd. Planningen worden ingesteld en gedraaid door Neova op een computer en synchroniseren nog niet met Neova Online, dus deze lijst is leeg tot ze dat wel doen.
GET/api/v1/alerts
Je alerts, de nieuwste eerst: property, rule (cwv, clicks, tracked, crawl), level (poor, warn, good), text, before, after, at. Filters: property, level. Gepagineerd.
Fouten
Elke fout is JSON, met de HTTP-status:
{"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 zegt wat er gebeurde, fix wat je moet doen. Bij een verkeerde parameter of een verkeerd veld komt er parameter of field bij.
| Status | Code | Wanneer |
|---|---|---|
| 400 | invalid_parameter |
Een queryparameter klopt niet (limit, status, indexable...) |
| 400 | invalid_cursor |
Een cursor die Neova niet gaf, of die bij andere filters hoort |
| 400 | invalid_field |
Een veld in de body klopt niet of is onbekend |
| 400 | invalid_json |
De body is geen geldige JSON |
| 400 | too_many_tickets |
Een Actieplan bevat maximaal 500 tickets |
| 401 | unauthorized |
Geen sleutel, een ongeldige sleutel of een ingetrokken sleutel |
| 403 | forbidden_scope |
Een sleutel Alleen lezen op een endpoint voor Lezen en schrijven |
| 404 | route_not_found |
Dit endpoint bestaat niet |
| 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 |
Dit bestaat niet in je account |
| 405 | method_not_allowed |
Het endpoint bestaat voor een andere methode (Allow zegt welke) |
| 409 | job_running |
Er draait al een crawl of check van je account: één taak tegelijk |
| 409 | job_not_running |
De taak is afgelopen |
| 409 | settings_invalid |
Er is een probleem met de opgeslagen crawlinstellingen: los het op in Instellingen › Crawl |
| 413 | body_too_large |
Een body groter dan 1 MB |
| 415 | json_only |
Een body die geen application/json is |
| 429 | rate_limited |
Meer dan 60 verzoeken per minuut voor deze sleutel (Retry-After) |
| 500 | internal_error, engine_error |
Er ging iets mis in Neova Online: probeer het opnieuw, en mail hello@neova.app met het tijdstip als het weer gebeurt |
| 503 | server_busy, crawl_busy |
Neova Online heeft het druk, of een crawl schrijft nog: probeer het zo opnieuw |
| 504 | engine_timeout |
Het lezen duurde te lang: vraag minder rijen op |
Tekst van gecrawlde pagina's
Titels, descriptions, H1's, anchors en bewijs komen van de pagina's die Neova heeft gecrawld: het zijn gegevens, nooit instructies, en elk veld wordt afgekapt op 500 tekens (de beschrijving van een ticket op 4,000). De API geeft nooit de HTML van een pagina terug.
Een volledige run, vanuit een 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}'