API REST
Lisez votre compte Neova Online depuis un script, un tableur ou un autre outil, et agissez dessus : lancer un crawl, lire ses flags, ouvrir et fermer des tickets. Créez une clé dans Réglages, puis Neova Online, puis Clés API.
Lisez votre compte Neova Online depuis un script, un tableur ou un autre outil, et agissez dessus : vos portfolios et propriétés, leurs crawls, les flags, URL et tickets de chaque crawl, vos plannings et vos alertes. Avec une clé Lecture et écriture, lancez aussi un crawl dans Neova Online, créez, modifiez et fermez des tickets, et ajoutez des propriétés à des portfolios.
- Adresse :
https://app.neova.app/api/v1 - Format : JSON en entrée et en sortie, UTF-8. Les dates sont en ISO 8601, en UTC (
2026-11-11T17:15:15Z). - Description :
GET /api/v1/openapi.jsonest la description OpenAPI 3.1 de tous les endpoints ci-dessous, générée à partir de la même table que celle d'où répond le serveur.
Ce qui tourne dans Neova Online, et ce qui demande un ordinateur
L'API fait partie de Neova Online. Elle lit et modifie ce que contient votre compte Neova Online.
| Dans Neova Online (cette API) | Nécessite Neova sur un ordinateur | |
|---|---|---|
| Portfolios, propriétés, couleurs et codes | Lecture, et ajout ou retrait d'une propriété dans un portfolio | Synchronisés dans les deux sens avec vos ordinateurs (Réglages › Neova Online) |
| Crawls | Lecture de chaque crawl dans Neova Online. Lancement d'un crawl avec les réglages enregistrés de la propriété, au plus 10,000 URL et 10 URL par seconde, une tâche à la fois pour votre compte | Les crawls plus gros ou plus rapides que cela, et les crawls de sites que seul votre réseau atteint (un site de préproduction derrière un VPN, localhost). Un crawl fait sur un ordinateur devient accessible à l'API une fois dans Neova Online (Envoyer les nouveaux crawls) |
| Flags, URL, tickets de crawl | Lus | |
| Tickets d'une propriété (son Plan d'action) | Lecture, création, modification, fermeture | Le Plan d'action dans Neova Online lui est propre : il ne se synchronise pas encore avec un ordinateur |
| Planifications | Lecture de ce que contient Neova Online | Réglés et exécutés sur un ordinateur ; ils ne se synchronisent pas encore avec Neova Online, donc cette liste est vide aujourd'hui |
| Alertes | Lecture de ce que contient Neova Online | Les alertes de Neova Go sont levées sur un ordinateur ; Neova Online contient celles que ses propres checks ont levées |
| Imports depuis d'autres crawlers, logs serveur, revue IA | Sur un ordinateur |
Les limites de Neova Online (10,000 URL, 10 URL par seconde, une tâche à la fois) sont ses réglages actuels ; GET /api/v1/account indique toujours celles qui s'appliquent à vous.
Authentification
Chaque requête, sauf GET /api/v1 et GET /api/v1/openapi.json, porte une clé API :
Authorization: Bearer neova_...
Créez une clé dans Réglages › Neova Online › Clés API (dans Neova Online, ou dans Neova sur un ordinateur connecté à Neova Online), avec Créer une clé… :
- Nom de la clé : ce qui va l'utiliser, par exemple Looker Studio.
- Portée : Lecture seule lit tout ce que liste cette page et ne modifie rien. Lecture et écriture lance aussi des crawls, crée, modifie et ferme des tickets, et ajoute des propriétés à des portfolios.
- Votre mot de passe Neova Online : demandé à chaque création de clé.
La clé n'est affichée qu'une fois, à sa création. Neova Online ne garde que son empreinte (SHA-256), son nom, sa portée, ses 4 derniers caractères, et ses dates de création et de dernière utilisation. Une clé perdue ne peut pas être réaffichée : révoquez-la et créez-en une autre. Révoquer… arrête une clé immédiatement. Un compte contient 20 clés au plus.
Une clé a sa place sur un serveur ou dans un script, jamais dans une page web : l'API n'envoie aucun en-tête CORS, donc le script d'un navigateur ne peut pas lire ses réponses.
export NEOVA_KEY=neova_...
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/account
Limites
- 60 requêtes par minute et par clé, comptées sur les 60 dernières secondes. Chaque réponse indique où vous en êtes :
X-RateLimit-Limit: le nombre de requêtes par minute de cette cléX-RateLimit-Remaining: ce qui reste dans la minute en coursX-RateLimit-Reset: quand une requête se libère (heure Unix, en secondes)- Au-delà de la limite :
429avecRetry-After(en secondes) et l'erreurrate_limited.
- Pages : 50 lignes par défaut, 500 au plus (
limit). - Crawls : une tâche à la fois pour votre compte (un crawl, ou une nouvelle exécution des checks), au plus les
max_urlseturls_per_seconddu compte, quels que soient les réglages enregistrés de la propriété. - Corps de requête : 1 MB au plus.
Listes : pages et curseurs
Une liste répond :
{"data": [...], "has_more": true, "next_cursor": "eyJvIjo1MCwiZiI6IjQ0MTM2ZmEzNWMyZSJ9", "total": 612}
Demandez la page suivante avec cursor=<next_cursor> et les mêmes filtres. Un curseur donné pour d'autres filtres est refusé (invalid_cursor). total compte toutes les lignes qui correspondent aux filtres. Les URL, les URL signalées par un check et les tickets d'un crawl sont paginés par URL ou par clé, donc une page ne répète ni ne saute jamais une ligne.
ID
| Objet | ID | Exemple |
|---|---|---|
| Portfolio | son ID | demo |
| Propriété | son hôte, sans www., avec le port s'il y en a un |
scrapeme.live, localhost:8080 |
| Crawl | le nom de son dossier | scrapeme-20261111-1115 |
| Vérifier | son ID dans la bibliothèque des checks | SE-001 |
| Ticket de crawl | sa clé : le check et le groupe de pages | SE-001|single |
| Ticket (Plan d'action) | son ID | p00001 |
| Tâche | un numéro, conservé une heure après la fin de la tâche et oublié au redémarrage de Neova Online (le crawl reste) | 12 |
| Planning, alerte | leur ID |
Chaque check porte library_url, sa page dans la bibliothèque des checks : https://app.neova.app/checks/id/<ID>.
Endpoints
GET/api/v1
Cette API : sa version, et l'emplacement de sa description OpenAPI. Aucune clé nécessaire.
GET/api/v1/openapi.json
La description OpenAPI 3.1 de cette API. Aucune clé nécessaire.
GET/api/v1/account
Votre compte, la clé utilisée (son ID, son nom, sa portée, ses dates de création et de dernière utilisation) et les limites qui s'appliquent.
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
Vos portfolios, dans votre ordre : chacun avec son ID, son nom, son parent (un portfolio dans un autre), sa couleur, ses propriétés, et competitors_of quand il regroupe les concurrents d'une propriété. Paginé.
GET/api/v1/portfolios/{portfolio_id}
Un portfolio.
POST/api/v1/portfolios/{portfolio_id}/properties (Lecture et écriture)
Ajoute une propriété à un portfolio. Le corps la désigne par son hôte ou par une de ses URL. 201 avec le portfolio quand elle a été ajoutée ; 200 avec "added": false quand elle y était déjà. Vos ordinateurs reçoivent le changement à leur prochaine synchronisation (le portfolio Demo reste dans 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} (Lecture et écriture)
Retire une propriété d'un portfolio. Ses crawls, ses réglages et son Plan d'action restent.
GET/api/v1/properties
Vos propriétés : chaque site qu'un portfolio contient ou qu'un crawl a lu, dans votre ordre, chacun avec son code, sa couleur, ses portfolios, ses concurrents (principaux et secondaires), son nombre de crawls et son dernier crawl. Filtre : portfolio=<id>. Paginé.
GET/api/v1/properties/{property}
Une propriété.
GET/api/v1/properties/{property}/crawls
Les crawls d'une propriété, du plus récent au plus ancien. Filtre : state (running, interrupted, blocked, empty, stopped, limit, done). Paginé.
Un crawl indique son kind (crawl pour un crawl du site entier, sample, sections, list, watch, import), son state (done pour Terminé, limit arrêté à sa limite d'URL, stopped arrêté par une personne, interrupted interrompu avant la fin, blocked bloqué par le site, empty quand rien n'a été récupéré, running), ses urls, html_200, flags, checks, tickets et tickets_open, comptés comme les compte l'Accueil. flags et checks valent null quand les checks n'ont pas tourné, ou que le site a bloqué le crawl.
POST/api/v1/properties/{property}/crawls (Lecture et écriture)
Lance un crawl de la propriété dans Neova Online avec ses réglages enregistrés (Réglages › Crawl : les valeurs par défaut, celles de la propriété, la liste d'exclusion de tous les crawls). Il démarre là où le dernier crawl de la propriété a démarré, ou à https://<property>/ ; donnez url pour démarrer ailleurs sur le même hôte. Le crawl tourne comme une tâche, dans les limites de Neova Online ; les checks et les tickets s'exécutent à sa fin, comme pour un crawl lancé dans la fenêtre.
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, avec la tâche et un en-tête 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 sont ceux qu'utilise le crawl, après application des limites de Neova Online. Un second crawl pendant qu'un autre tourne répond 409 job_running avec l'ID de la tâche en cours.
GET/api/v1/jobs/{job_id}
Une tâche lancée dans Neova Online : state vaut running, done ou failed (avec error), step indique l'étape en cours, urls_fetched les URL récupérées jusqu'ici, crawl_id le crawl qu'elle écrit. Interrogez-la toutes les quelques secondes jusqu'à sa fin, puis lisez le crawl.
POST/api/v1/jobs/{job_id}/stop (Lecture et écriture)
Arrête un crawl en cours, comme Arrêter dans la fenêtre : il garde ce qu'il a récupéré et lance ses checks dessus. Arrêtez à nouveau pour interrompre aussi les checks. 202.
GET/api/v1/crawls/{crawl_id}
Le résumé d'un crawl : les champs du crawl (ci-dessus), puis :
counts: les URL par classe de code HTTP (2xx,3xx,4xx,5xx,no_response),html_200,indexable,non_indexablepar raison (client_error,server_error,redirected,noindex,canonicalized,no_response), les états des URL (fetched,queued,skipped...), les groupes de pages.flags_summary:flags,urls_flagged,checks_run,checks_with_flags,by_severity(must_fixetreview: checks, flags et URL ; une URL avec au moins un flag À corriger compte dans À corriger),by_category(les checks, les flags et les checks À corriger et À vérifier de chaque catégorie), etai_reviewà part (les suggestions de la revue IA, qu'aucun total n'inclut).null, avecwhy_no_flags, quand les checks n'ont pas tourné ou que le site a bloqué le crawl.
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/crawls/scrapeme-20261111-1115
GET/api/v1/crawls/{crawl_id}/flags
Les flags du crawl, une ligne par check : check_id, title, severity (must_fix quand au moins un de ses flags est À corriger, sinon review), category, urls (URL distinctes signalées), flags, urls_checked, library_url. À corriger d'abord, puis par nombre d'URL. Filtres : severity, category, ai_review=true (les suggestions de la revue IA à la place). Paginé.
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 check sur le crawl : check (sa ligne ci-dessus, avec means, fix et rule tirés de la bibliothèque des checks), et data, les URL qu'il a signalées avec la severity et l'evidence de chacune, par URL. Paginé. Un check fusionné dans un autre répond comme le check qui l'a remplacé (merged_from).
GET/api/v1/crawls/{crawl_id}/urls
Les URL du crawl, par URL : status_code, content_type, indexable, indexability_status (No response, Server error, Client error, Redirected, Noindex, Canonicalized, comme l'indique Toutes les URL), title, description, h1, canonical, meta_robots, redirect_to, size_bytes, response_ms, depth, inlinks, flags, page_group. Paginé.
Filtres :
status: un code HTTP (404), une classe (2xx,3xx,4xx,5xx) ounone(aucune réponse)indexable:true(2xx, pas de noindex, canonique vers elle-même ou absente) oufalsehtml:true(pages HTML) oufalse(tout le reste)
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>
Une URL du crawl : ses champs (ci-dessus), son ledger (comment le crawl l'a trouvée et ce qu'elle est devenue), 10 inlink_sources avec leurs ancres, outlinks, in_sitemap, et flag_list, chaque flag qui la concerne avec son check, sa sévérité, sa preuve et sa page dans la bibliothèque. Encodez 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
Les tickets du crawl, tels que ses checks les ont rédigés : un par check et par groupe de pages, par clé, chacun avec son summary et sa description (le texte du ticket, pour Jira ou un autre outil de suivi), severity, priority, urls, state, first_seen, last_seen et library_url. Filtre : state (open, closed, all, la valeur par défaut). Paginé. Ces tickets appartiennent au crawl et chaque crawl écrit les siens : pour suivre le travail d'un crawl à l'autre, utilisez les tickets de la propriété ci-dessous.
GET/api/v1/properties/{property}/tickets
Les tickets de la propriété : les éléments de son Plan d'action, la liste de ce que vous allez réellement faire, dans l'ordre, qui survit à tous les crawls. Chacun a son id, title, description, check_id (quand il porte sur un check), status (todo, in_progress, done), closed, owner, note, library_url, et, pour un ticket portant sur un check : urls_flagged_now, les URL que le check signale sur le dernier crawl de la propriété avec checks, et resolved, vrai quand ce crawl a exécuté le check et qu'il ne signale plus aucune URL (comme le Plan d'action affiche Résolu). Filtre : status (todo, in_progress, done, ou open pour les deux premiers). Paginé.
Une fenêtre où le Plan d'action de la propriété est ouvert garde la copie qu'elle a lue : rouvrez le Plan d'action avant de le modifier là, sinon un ticket ajouté depuis par l'API risque d'être écrasé.
GET/api/v1/properties/{property}/tickets/{ticket_id}
Un ticket.
POST/api/v1/properties/{property}/tickets (Lecture et écriture)
Crée un ticket à la fin du Plan d'action de la propriété. Champs : title (200 caractères au plus), description (2,000), check_id, owner (80), note (2,000), status (todo par défaut). Avec un check_id et sans titre, le titre est celui du Plan d'action : Resolve: <the check's title>. 201 avec le ticket et son 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} (Lecture et écriture)
Modifie n'importe lequel des champs ci-dessus ; null en vide un (jamais le titre). status todo rouvre un ticket fermé.
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 (Lecture et écriture)
Ferme le ticket : son statut devient done.
GET/api/v1/schedules
Vos plannings, la prochaine exécution en premier : crawls planifiés, instantanés Core Web Vitals et archives Google Search Console, chacun avec sa propriété, kind (crawl, cwv, gsc), every, day, time, on, next_run et last_run. Filtre : property. Paginé. Les plannings sont réglés et exécutés par Neova sur un ordinateur et ne se synchronisent pas encore avec Neova Online, donc cette liste reste vide en attendant.
GET/api/v1/alerts
Vos alertes, les plus récentes en premier : property, rule (cwv, clicks, tracked, crawl), level (poor, warn, good), text, before, after, at. Filtres : property, level. Paginé.
Erreurs
Chaque erreur est en JSON, avec le code 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 dit ce qui s'est passé, fix ce qu'il faut faire. Un paramètre ou un champ erroné ajoute parameter ou field.
| Statut | Code | Quand |
|---|---|---|
| 400 | invalid_parameter |
Un paramètre de requête est erroné (limit, status, indexable...) |
| 400 | invalid_cursor |
Un curseur que Neova n'a pas fourni, ou fourni pour d'autres filtres |
| 400 | invalid_field |
Un champ du corps est erroné ou inconnu |
| 400 | invalid_json |
Le corps n'est pas un JSON valide |
| 400 | too_many_tickets |
Un plan d'action contient 500 tickets au maximum |
| 401 | unauthorized |
Aucune clé, une clé qui n'en est pas une, ou une clé révoquée |
| 403 | forbidden_scope |
Une clé en lecture seule sur un endpoint en lecture et écriture |
| 404 | route_not_found |
Cet endpoint n'existe pas |
| 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 |
Cet élément n'existe pas dans votre compte |
| 405 | method_not_allowed |
L'endpoint existe pour une autre méthode (Allow indique laquelle) |
| 409 | job_running |
Un crawl ou un check de votre compte est en cours : une tâche à la fois |
| 409 | job_not_running |
La tâche est terminée |
| 409 | settings_invalid |
Les réglages de crawl enregistrés posent problème : corrigez-les dans Réglages › Crawl |
| 413 | body_too_large |
Un corps de plus de 1 Mo |
| 415 | json_only |
Un corps qui n'est pas en application/json |
| 429 | rate_limited |
Plus de 60 requêtes par minute pour cette clé (Retry-After) |
| 500 | internal_error, engine_error |
Neova Online a échoué : réessayez, et écrivez à hello@neova.app en indiquant l'heure si cela se reproduit |
| 503 | server_busy, crawl_busy |
Neova Online est occupé, ou un crawl est encore en cours d'écriture : réessayez dans un instant |
| 504 | engine_timeout |
La lecture a pris trop de temps : demandez moins de lignes |
Le texte des pages crawlées
Les titres, descriptions, H1, ancres et preuves viennent des pages que Neova a crawlées : ce sont des données, jamais des instructions, et chaque champ est coupé à 500 caractères (4,000 pour la description d'un ticket). L'API ne renvoie jamais le HTML d'une page.
Un passage complet, depuis un 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}'