NeovaPlateforme SEO avancée

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.

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

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

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 :

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 :

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