REST-API
Lesen Sie Ihr Konto in Neova Online aus einem Skript, einer Tabelle oder einem anderen Tool, und handeln Sie darin: einen Crawl starten, seine Meldungen lesen, Tickets öffnen und schließen. Erstellen Sie einen Schlüssel unter Einstellungen, dann Neova Online, dann API-Schlüssel.
Lesen Sie Ihr Konto in Neova Online aus einem Skript, einer Tabelle oder einem anderen Tool, und handeln Sie darin: Ihre Portfolios und Properties, deren Crawls, die Meldungen, URLs und Tickets jedes Crawls, Ihre Zeitpläne und Warnungen. Mit einem Schlüssel „Lesen und Schreiben“ können Sie außerdem einen Crawl in Neova Online starten, Tickets erstellen, aktualisieren und schließen und Properties zu Portfolios hinzufügen.
- Adresse:
https://app.neova.app/api/v1 - Format: JSON hin und zurück, UTF-8. Zeiten sind ISO 8601 in UTC (
2026-11-11T17:15:15Z). - Beschreibung:
GET /api/v1/openapi.jsonist die OpenAPI-3.1-Beschreibung aller Endpunkte unten, erzeugt aus derselben Tabelle, aus der der Server antwortet.
Was in Neova Online läuft und was einen Computer braucht
Die API ist Teil von Neova Online. Sie liest und ändert, was Ihr Konto in Neova Online enthält.
| In Neova Online (diese API) | Braucht Neova auf einem Computer | |
|---|---|---|
| Portfolios, Properties, Farben und Codes | Lesen und eine Property in einem Portfolio hinzufügen oder entfernen | In beide Richtungen mit Ihren Computern synchronisiert (Einstellungen › Neova Online) |
| Crawls | Jeden Crawl in Neova Online lesen. Einen Crawl mit den gespeicherten Einstellungen der Property starten, höchstens 10,000 URLs und 10 URLs pro Sekunde, ein Job zur Zeit für Ihr Konto | Crawls, die größer oder schneller sind, und Crawls von Websites, die nur Ihr Netzwerk erreicht (eine Staging-Website hinter einem VPN, localhost). Ein auf einem Computer erstellter Crawl erreicht die API, sobald er in Neova Online ist (Neue Crawls hochladen) |
| Meldungen, URLs, Crawl-Tickets | Gelesen | |
| Tickets einer Property (ihr Aktionsplan) | Lesen, erstellen, aktualisieren, schließen | Der Aktionsplan in Neova Online ist eigenständig: Er synchronisiert sich noch nicht mit einem Computer |
| Zeitpläne | Lesen, was Neova Online enthält | Auf einem Computer festgelegt und ausgeführt; sie synchronisieren sich noch nicht mit Neova Online, daher ist diese Liste heute leer |
| Warnungen | Lesen, was Neova Online enthält | Die Warnungen von Neova Go entstehen auf einem Computer; Neova Online enthält die, die seine eigenen Checks ausgelöst haben |
| Importe aus anderen Crawlern, Server-Logs, KI-Prüfung | Auf einem Computer |
Die Limits von Neova Online (10,000 URLs, 10 URLs pro Sekunde, ein Job zur Zeit) sind seine heutigen Einstellungen; GET /api/v1/account nennt immer die, die für Sie gelten.
Authentifizierung
Jede Anfrage außer GET /api/v1 und GET /api/v1/openapi.json trägt einen API-Schlüssel:
Authorization: Bearer neova_...
Erstellen Sie einen Schlüssel unter Einstellungen › Neova Online › API-Schlüssel (in Neova Online oder in Neova auf einem Computer, der bei Neova Online angemeldet ist), mit Schlüssel erstellen…:
- Schlüsselname: was ihn nutzen wird, zum Beispiel Looker Studio.
- Umfang: Nur Lesen liest alles, was diese Seite aufführt, und ändert nichts. Lesen und Schreiben startet außerdem Crawls, erstellt, aktualisiert und schließt Tickets und fügt Properties zu Portfolios hinzu.
- Ihr Passwort für Neova Online: wird bei jedem neuen Schlüssel abgefragt.
Der Schlüssel wird einmal angezeigt, wenn er erstellt wird. Neova Online speichert nur seinen Fingerabdruck (SHA-256), seinen Namen, seinen Umfang, seine letzten 4 Zeichen und wann er erstellt und zuletzt genutzt wurde. Ein verlorener Schlüssel lässt sich nicht noch einmal anzeigen: Widerrufen Sie ihn und erstellen Sie einen neuen. Widerrufen… stoppt einen Schlüssel sofort. Ein Konto hat höchstens 20 Schlüssel.
Ein Schlüssel gehört auf einen Server oder in ein Skript, nie in eine Webseite: Die API sendet keine CORS-Header, daher kann das Skript eines Browsers ihre Antworten nicht lesen.
export NEOVA_KEY=neova_...
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/account
Limits
- 60 Anfragen pro Minute und Schlüssel, gezählt über die letzten 60 Sekunden. Jede Antwort sagt, wo Sie stehen:
X-RateLimit-Limit: die Anfragen pro Minute dieses SchlüsselsX-RateLimit-Remaining: was in der aktuellen Minute übrig istX-RateLimit-Reset: wann eine Anfrage frei wird (Unix-Zeit, Sekunden)- Über dem Limit:
429mitRetry-After(Sekunden) und dem Fehlerrate_limited.
- Seiten: standardmäßig 50 Zeilen, höchstens 500 (
limit). - Crawls: ein Job zur Zeit für Ihr Konto (ein Crawl oder ein erneuter Lauf der Checks), höchstens
max_urlsundurls_per_seconddes Kontos, egal was die gespeicherten Einstellungen der Property sagen. - Bodys: höchstens 1 MB.
Listen: Seiten und Cursor
Eine Liste antwortet:
{"data": [...], "has_more": true, "next_cursor": "eyJvIjo1MCwiZiI6IjQ0MTM2ZmEzNWMyZSJ9", "total": 612}
Fordern Sie die nächste Seite mit cursor=<next_cursor> und denselben Filtern an. Ein Cursor, der für andere Filter ausgegeben wurde, wird abgelehnt (invalid_cursor). total zählt jede Zeile, die zu den Filtern passt. URLs, die gemeldeten URLs eines Checks und die Tickets eines Crawls werden nach ihrer URL oder ihrem Schlüssel paginiert, sodass eine Seite nie eine Zeile wiederholt oder auslässt.
IDs
| Objekt | ID | Beispiel |
|---|---|---|
| Portfolio | seine ID | demo |
| Property | ihr Host, ohne www., mit Port, falls vorhanden |
scrapeme.live, localhost:8080 |
| Crawl | sein Ordnername | scrapeme-20261111-1115 |
| Check | seine ID im Check-Katalog | SE-001 |
| Crawl-Ticket | sein Schlüssel: der Check und die Seitengruppe | SE-001|single |
| Ticket (Aktionsplan) | seine ID | p00001 |
| Job | eine Nummer, eine Stunde nach Ende des Jobs aufbewahrt und vergessen, wenn Neova Online neu startet (der Crawl bleibt) | 12 |
| Zeitplan, Warnung | ihre ID |
Jeder Check trägt library_url, seine Seite im Check-Katalog: https://app.neova.app/checks/id/<ID>.
Endpunkte
GET/api/v1
Diese API: ihre Version und wo ihre OpenAPI-Beschreibung liegt. Kein Schlüssel nötig.
GET/api/v1/openapi.json
Die OpenAPI-3.1-Beschreibung dieser API. Kein Schlüssel nötig.
GET/api/v1/account
Ihr Konto, der verwendete Schlüssel (seine ID, sein Name, sein Umfang, wann er erstellt und zuletzt genutzt wurde) und die geltenden Limits.
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
Ihre Portfolios, in Ihrer Reihenfolge: jedes mit ID, Name, übergeordnetem Portfolio (ein Portfolio in einem anderen), Farbe, seinen Properties und competitors_of, wenn es die Wettbewerber einer Property enthält. Paginiert.
GET/api/v1/portfolios/{portfolio_id}
Ein Portfolio.
POST/api/v1/portfolios/{portfolio_id}/properties (Lesen und Schreiben)
Fügt eine Property zu einem Portfolio hinzu. Der Body nennt sie über ihren Host oder eine ihrer URLs. 201 mit dem Portfolio, wenn sie hinzugefügt wurde; 200 mit "added": false, wenn sie schon darin war. Ihre Computer erhalten die Änderung bei der nächsten Synchronisierung (das Portfolio Demo bleibt 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} (Lesen und Schreiben)
Nimmt eine Property aus einem Portfolio heraus. Ihre Crawls, Einstellungen und ihr Aktionsplan bleiben.
GET/api/v1/properties
Ihre Properties: jede Website, die ein Portfolio enthält oder ein Crawl gelesen hat, in Ihrer Reihenfolge, jede mit Code, Farbe, Portfolios, Wettbewerbern (primär und sekundär), der Anzahl ihrer Crawls und ihrem letzten Crawl. Filter: portfolio=<id>. Paginiert.
GET/api/v1/properties/{property}
Eine Property.
GET/api/v1/properties/{property}/crawls
Die Crawls einer Property, die neuesten zuerst. Filter: state (running, interrupted, blocked, empty, stopped, limit, done). Paginiert.
Ein Crawl nennt seine kind (crawl für einen Crawl der ganzen Website, sample, sections, list, watch, import), seinen state (done ist Abgeschlossen, limit an seinem URL-Limit gestoppt, stopped von einer Person, interrupted vor seinem Ende, blocked von der Website, empty, wenn nichts abgerufen wurde, running), seine urls, html_200, flags, checks, tickets und tickets_open, gezählt wie auf der Startseite. flags und checks sind null, wenn die Checks nicht gelaufen sind oder die Website den Crawl blockiert hat.
POST/api/v1/properties/{property}/crawls (Lesen und Schreiben)
Startet einen Crawl der Property in Neova Online mit ihren gespeicherten Einstellungen (Einstellungen › Crawl: die Standardwerte, die eigenen der Property, die Ausschlussliste jedes Crawls). Er startet dort, wo der letzte Crawl der Property gestartet ist, oder bei https://<property>/; geben Sie url an, um woanders auf demselben Host zu starten. Der Crawl läuft als Job, unter den Limits von Neova Online; die Checks und die Tickets laufen, wenn er endet, wie bei einem im Fenster gestarteten Crawl.
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, mit dem Job und einem 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 sind die Einstellungen, die der Crawl nutzt, nach den Limits von Neova Online. Ein zweiter Crawl, während einer läuft, antwortet mit 409 job_running und der ID des laufenden Jobs.
GET/api/v1/jobs/{job_id}
Ein in Neova Online gestarteter Job: state ist running, done oder failed (mit error), step die Phase, in der er ist, urls_fetched die bisher abgerufenen URLs, crawl_id der Crawl, den er schreibt. Fragen Sie alle paar Sekunden nach, bis er endet; lesen Sie dann den Crawl.
POST/api/v1/jobs/{job_id}/stop (Lesen und Schreiben)
Stoppt einen laufenden Crawl, wie „Stoppen“ im Fenster: Er behält, was er abgerufen hat, und führt seine Checks darauf aus. Stoppen Sie erneut, um auch die Checks zu beenden. 202.
GET/api/v1/crawls/{crawl_id}
Die Zusammenfassung eines Crawls: die Felder des Crawls (oben), dann:
counts: URLs nach Statuscode-Klasse (2xx,3xx,4xx,5xx,no_response),html_200,indexable,non_indexablenach Grund (client_error,server_error,redirected,noindex,canonicalized,no_response), die Zustände der URLs (fetched,queued,skipped...), die Seitengruppen.flags_summary:flags,urls_flagged,checks_run,checks_with_flags,by_severity(must_fixundreview: Checks, Meldungen und URLs; eine URL mit einer Meldung „Muss behoben werden“ zählt unter „Muss behoben werden“),by_category(die Checks und Meldungen jeder Kategorie sowie ihre Checks „Muss behoben werden“ und „Prüfenswert“) undai_reviewseparat (die Vorschläge der KI-Prüfung, die keine Zählung enthält).null, mitwhy_no_flags, wenn die Checks nicht gelaufen sind oder die Website den Crawl blockiert hat.
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/crawls/scrapeme-20261111-1115
GET/api/v1/crawls/{crawl_id}/flags
Die Meldungen des Crawls, eine Zeile pro Check: check_id, title, severity (must_fix, wenn eine seiner Meldungen „Muss behoben werden“ ist, sonst review), category, urls (verschiedene gemeldete URLs), flags, urls_checked, library_url. „Muss behoben werden“ zuerst, dann nach URLs. Filter: severity, category, ai_review=true (stattdessen die Vorschläge der KI-Prüfung). Paginiert.
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}
Ein Check des Crawls: check (seine Zeile von oben, mit means, fix und rule aus dem Check-Katalog) und data, die URLs, die er gemeldet hat, jeweils mit severity und evidence, nach URL. Paginiert. Ein Check, der mit einem anderen zusammengeführt wurde, antwortet als der Check, der ihn ersetzt hat (merged_from).
GET/api/v1/crawls/{crawl_id}/urls
Die URLs des Crawls, nach URL: status_code, content_type, indexable, indexability_status (No response, Server error, Client error, Redirected, Noindex, Canonicalized, wie „Alle URLs“ es angibt), title, description, h1, canonical, meta_robots, redirect_to, size_bytes, response_ms, depth, inlinks, flags, page_group. Paginiert.
Filter:
status: ein Statuscode (404), eine Klasse (2xx,3xx,4xx,5xx) odernone(keine Antwort)indexable:true(2xx, kein noindex, Canonical auf sich selbst oder keines) oderfalsehtml:true(HTML-Seiten) oderfalse(alles 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>
Eine URL des Crawls: ihre Felder (oben), ihr ledger (wie der Crawl sie gefunden hat und was aus ihr wurde), 10 inlink_sources mit ihren Ankertexten, outlinks, in_sitemap und flag_list, jede Meldung zu ihr mit Check, Schweregrad, Beleg und Katalogseite. Kodieren Sie die 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
Die Tickets des Crawls, so wie seine Checks sie geschrieben haben: eines pro Check und Seitengruppe, nach Schlüssel, jeweils mit summary und description (der Text des Tickets, für Jira oder einen anderen Tracker), severity, priority, urls, state, first_seen, last_seen und library_url. Filter: state (open, closed, all, der Standard). Paginiert. Diese Tickets gehören zum Crawl, und jeder Crawl schreibt seine eigenen: Um Arbeit über Crawls hinweg zu verfolgen, nutzen Sie die Tickets der Property unten.
GET/api/v1/properties/{property}/tickets
Die Tickets der Property: die Einträge ihres Aktionsplans, die Liste dessen, was Sie tatsächlich tun werden, der Reihe nach, die jeden Crawl überdauert. Jedes hat id, title, description, check_id (wenn es um einen Check geht), status (todo, in_progress, done), closed, owner, note, library_url und, bei einem Ticket zu einem Check: urls_flagged_now, die URLs, die der Check im letzten Crawl der Property mit Checks meldet, und resolved, true, wenn dieser Crawl den Check ausgeführt hat und er jetzt keine URL meldet (so wie der Aktionsplan „Behoben“ sagt). Filter: status (todo, in_progress, done oder open für die ersten beiden). Paginiert.
Ein Fenster, in dem der Aktionsplan der Property offen ist, behält die Kopie, die es gelesen hat: Öffnen Sie den Aktionsplan erneut, bevor Sie ihn dort ändern, sonst wird ein Ticket, das die API inzwischen hinzugefügt hat, womöglich überschrieben.
GET/api/v1/properties/{property}/tickets/{ticket_id}
Ein Ticket.
POST/api/v1/properties/{property}/tickets (Lesen und Schreiben)
Erstellt ein Ticket am Ende des Aktionsplans der Property. Felder: title (höchstens 200 Zeichen), description (2,000), check_id, owner (80), note (2,000), status (standardmäßig todo). Mit einer check_id und ohne Titel ist der Titel der des Aktionsplans: Resolve: <the check's title>. 201 mit dem Ticket und seiner 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} (Lesen und Schreiben)
Ändert beliebige der Felder oben; null leert eines (nie den Titel). status todo öffnet ein geschlossenes Ticket wieder.
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 (Lesen und Schreiben)
Schließt das Ticket: Sein Status wird done.
GET/api/v1/schedules
Ihre Zeitpläne, der nächste Lauf zuerst: geplante Crawls, Core-Web-Vitals-Snapshots und Archive der Google Search Console, jeweils mit ihrer Property, kind (crawl, cwv, gsc), every, day, time, on, next_run und last_run. Filter: property. Paginiert. Zeitpläne werden von Neova auf einem Computer festgelegt und ausgeführt und synchronisieren sich noch nicht mit Neova Online, daher ist diese Liste leer, bis sie es tun.
GET/api/v1/alerts
Ihre Warnungen, die neuesten zuerst: property, rule (cwv, clicks, tracked, crawl), level (poor, warn, good), text, before, after, at. Filter: property, level. Paginiert.
Fehler
Jeder Fehler ist JSON, mit dem 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 sagt, was passiert ist, fix, was zu tun ist. Bei einem falschen Parameter oder Feld kommt parameter bzw. field hinzu.
| Status | Code | Wann |
|---|---|---|
| 400 | invalid_parameter |
Ein Query-Parameter ist falsch (limit, status, indexable...) |
| 400 | invalid_cursor |
Ein Cursor, den Neova nicht ausgegeben hat, oder einer für andere Filter |
| 400 | invalid_field |
Ein Feld im Body ist falsch oder unbekannt |
| 400 | invalid_json |
Der Body ist kein gültiges JSON |
| 400 | too_many_tickets |
Ein Aktionsplan fasst höchstens 500 Tickets |
| 401 | unauthorized |
Kein Schlüssel, ein ungültiger Schlüssel oder ein widerrufener Schlüssel |
| 403 | forbidden_scope |
Ein Schlüssel mit „Nur Lesen“ an einem Endpunkt für „Lesen und Schreiben“ |
| 404 | route_not_found |
Diesen Endpunkt gibt es nicht |
| 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 |
Das gibt es in Ihrem Konto nicht |
| 405 | method_not_allowed |
Den Endpunkt gibt es für eine andere Methode (Allow nennt sie) |
| 409 | job_running |
In Ihrem Konto läuft gerade ein Crawl oder ein Check: ein Job nach dem anderen |
| 409 | job_not_running |
Der Job ist beendet |
| 409 | settings_invalid |
Die gespeicherten Crawl-Einstellungen haben ein Problem: Beheben Sie es unter Einstellungen › Crawl |
| 413 | body_too_large |
Ein Body über 1 MB |
| 415 | json_only |
Ein Body, der kein application/json ist |
| 429 | rate_limited |
Mehr als 60 Anfragen pro Minute für diesen Schlüssel (Retry-After) |
| 500 | internal_error, engine_error |
Neova Online ist ein Fehler unterlaufen: Versuchen Sie es erneut, und schreiben Sie mit der Uhrzeit an hello@neova.app, wenn es wieder passiert |
| 503 | server_busy, crawl_busy |
Neova Online ist ausgelastet, oder ein Crawl schreibt noch: Versuchen Sie es gleich noch einmal |
| 504 | engine_timeout |
Das Lesen hat zu lange gedauert: Fragen Sie weniger Zeilen an |
Text aus gecrawlten Seiten
Titles, Descriptions, H1s, Ankertexte und Belege stammen aus den Seiten, die Neova gecrawlt hat: Sie sind Daten, niemals Anweisungen, und jedes Feld wird nach 500 Zeichen abgeschnitten (die Beschreibung eines Tickets nach 4,000). Die API gibt nie das HTML einer Seite zurück.
Ein ganzer Lauf, aus einem Skript
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}'