API REST
Lee tu cuenta de Neova Online desde un script, una hoja de cálculo u otra herramienta, y actúa sobre ella: inicia un rastreo, lee sus avisos, abre y cierra tickets. Crea una clave en Ajustes, luego Neova Online y luego Claves de API.
Lee tu cuenta de Neova Online desde un script, una hoja de cálculo u otra herramienta, y actúa sobre ella: tus carteras y propiedades, sus rastreos, los avisos, las URL y los tickets de cada rastreo, tus programaciones y alertas. Con una clave de lectura y escritura, además puedes iniciar un rastreo en Neova Online, crear, actualizar y cerrar tickets, y añadir propiedades a carteras.
- Dirección:
https://app.neova.app/api/v1 - Formato: JSON de entrada y de salida, UTF-8. Las horas van en ISO 8601 en UTC (
2026-11-11T17:15:15Z). - Descripción:
GET /api/v1/openapi.jsones la descripción OpenAPI 3.1 de todos los endpoints de abajo, generada a partir de la misma tabla con la que responde el servidor.
Qué se ejecuta en Neova Online y qué necesita un ordenador
La API forma parte de Neova Online. Lee y modifica lo que contiene tu cuenta de Neova Online.
| En Neova Online (esta API) | Necesita Neova en un ordenador | |
|---|---|---|
| Carteras, propiedades, colores y códigos | Leer, y añadir o quitar una propiedad de una cartera | Sincronizado en ambos sentidos con tus ordenadores (Ajustes › Neova Online) |
| Rastreos | Leer todos los rastreos de Neova Online. Iniciar un rastreo con los ajustes guardados de la propiedad, como máximo 10,000 URL y 10 URL por segundo, un trabajo a la vez por cuenta | Rastreos más grandes o más rápidos que eso, y rastreos de sitios a los que solo llega tu red (un sitio de staging detrás de una VPN, localhost). Un rastreo hecho en un ordenador llega a la API una vez que está en Neova Online (Subir rastreos nuevos) |
| Avisos, URL, tickets del rastreo | Leídos | |
| Tickets de una propiedad (su plan de acción) | Leer, crear, actualizar, cerrar | El plan de acción de Neova Online es independiente: aún no se sincroniza con un ordenador |
| Programaciones | Leer lo que contiene Neova Online | Se configuran y se ejecutan en un ordenador; aún no se sincronizan con Neova Online, así que hoy esta lista está vacía |
| Alertas | Leer lo que contiene Neova Online | Las alertas de Neova Go se generan en un ordenador; Neova Online contiene las que generaron sus propias comprobaciones |
| Importaciones de otros crawlers, logs del servidor, revisión con IA | En un ordenador |
Los límites de Neova Online (10,000 URL, 10 URL por segundo, un trabajo a la vez) son sus ajustes actuales; GET /api/v1/account siempre indica los que se te aplican.
Autenticación
Todas las peticiones salvo GET /api/v1 y GET /api/v1/openapi.json llevan una clave de API:
Authorization: Bearer neova_...
Crea una clave en Ajustes › Neova Online › Claves de API (en Neova Online, o en Neova en un ordenador con la sesión iniciada en Neova Online), con Crear clave…:
- Nombre de la clave: qué la va a usar, por ejemplo Looker Studio.
- Alcance: Solo lectura lee todo lo que lista esta página y no cambia nada. Lectura y escritura además inicia rastreos, crea, actualiza y cierra tickets, y añade propiedades a carteras.
- Tu contraseña de Neova Online: se pide cada vez que se crea una clave.
La clave se muestra una sola vez, al crearla. Neova Online solo guarda su huella (SHA-256), su nombre, su alcance, sus 4 últimos caracteres y cuándo se creó y se usó por última vez. Una clave perdida no se puede volver a mostrar: revócala y crea otra. Revocar… detiene una clave al instante. Una cuenta tiene 20 claves como máximo.
Una clave va en un servidor o en un script, nunca en una página web: la API no envía cabeceras CORS, así que el script de un navegador no puede leer sus respuestas.
export NEOVA_KEY=neova_...
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/account
Límites
- 60 peticiones por minuto por clave, contadas sobre los últimos 60 segundos. Cada respuesta te dice cómo vas:
X-RateLimit-Limit: las peticiones por minuto de esta claveX-RateLimit-Remaining: lo que queda en el minuto actualX-RateLimit-Reset: cuándo queda libre una petición (hora Unix, en segundos)- Por encima del límite:
429conRetry-After(segundos) y el errorrate_limited.
- Páginas: 50 filas por defecto, 500 como máximo (
limit). - Rastreos: un trabajo a la vez por cuenta (un rastreo, o volver a ejecutar las comprobaciones), como máximo los
max_urlsyurls_per_secondde la cuenta, digan lo que digan los ajustes guardados de la propiedad. - Cuerpos: 1 MB como máximo.
Listas: páginas y cursores
Una lista responde:
{"data": [...], "has_more": true, "next_cursor": "eyJvIjo1MCwiZiI6IjQ0MTM2ZmEzNWMyZSJ9", "total": 612}
Pide la página siguiente con cursor=<next_cursor> y los mismos filtros. Un cursor dado para otros filtros se rechaza (invalid_cursor). total cuenta todas las filas que coinciden con los filtros. Las URL, las URL señaladas de una comprobación y los tickets de un rastreo se paginan por su URL o su clave, así que una página nunca repite ni se salta una fila.
ID
| Elemento | ID | Ejemplo |
|---|---|---|
| Cartera | su ID | demo |
| Propiedad | su host, sin www. y conservando el puerto |
scrapeme.live, localhost:8080 |
| Rastrear | el nombre de su carpeta | scrapeme-20261111-1115 |
| Comprobación | su ID en la biblioteca de comprobaciones | SE-001 |
| Ticket del rastreo | su clave: la comprobación y el grupo de páginas | SE-001|single |
| Ticket (plan de acción) | su ID | p00001 |
| Trabajo | un número, que se conserva una hora después de que termine el trabajo y se olvida cuando Neova Online se reinicia (el rastreo se queda) | 12 |
| Programación, alerta | su ID |
Cada comprobación lleva library_url, su página en la biblioteca de comprobaciones: https://app.neova.app/checks/id/<ID>.
Endpoints
GET/api/v1
Esta API: su versión y dónde está su descripción OpenAPI. No necesita clave.
GET/api/v1/openapi.json
La descripción OpenAPI 3.1 de esta API. No necesita clave.
GET/api/v1/account
Tu cuenta, la clave usada (su ID, nombre, alcance, cuándo se creó y se usó por última vez) y los límites que se aplican.
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
Tus carteras, en tu orden: cada una con su ID, nombre, cartera madre (una cartera dentro de otra), color, sus propiedades y competitors_of cuando son los competidores de una propiedad. Paginado.
GET/api/v1/portfolios/{portfolio_id}
Una cartera.
POST/api/v1/portfolios/{portfolio_id}/properties (lectura y escritura)
Añade una propiedad a una cartera. El cuerpo la nombra por su host o por una de sus URL. 201 con la cartera cuando se ha añadido; 200 con "added": false cuando ya estaba. Tus ordenadores reciben el cambio en su siguiente sincronización (la cartera Demo se queda en 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} (lectura y escritura)
Saca una propiedad de una cartera. Sus rastreos, ajustes y plan de acción se conservan.
GET/api/v1/properties
Tus propiedades: cada sitio que contiene una cartera o que ha leído un rastreo, en tu orden, cada una con su código, color, carteras, competidores (principales y secundarios), su número de rastreos y su último rastreo. Filtro: portfolio=<id>. Paginado.
GET/api/v1/properties/{property}
Una propiedad.
GET/api/v1/properties/{property}/crawls
Los rastreos de una propiedad, del más reciente al más antiguo. Filtro: state (running, interrupted, blocked, empty, stopped, limit, done). Paginado.
Un rastreo indica su kind (crawl para un rastreo del sitio completo, sample, sections, list, watch, import), su state (done es Completo, limit se detuvo en su límite de URL, stopped lo detuvo una persona, interrupted antes de terminar, blocked por el sitio, empty cuando no se descargó nada, running), sus urls, html_200, flags, checks, tickets y tickets_open, contados como los cuenta Inicio. flags y checks son null cuando no se ejecutaron las comprobaciones o el sitio bloqueó el rastreo.
POST/api/v1/properties/{property}/crawls (lectura y escritura)
Inicia un rastreo de la propiedad en Neova Online con sus ajustes guardados (Ajustes › Rastreo: los predeterminados, los de la propia propiedad y la lista de exclusiones de todos los rastreos). Empieza donde empezó el último rastreo de la propiedad, o en https://<property>/; indica url para empezar en otro punto del mismo host. El rastreo se ejecuta como un trabajo, con los límites de Neova Online; las comprobaciones y los tickets se ejecutan al terminar, igual que en un rastreo iniciado desde la ventana.
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 el trabajo y una cabecera 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 son los que usa el rastreo, tras aplicar los límites de Neova Online. Un segundo rastreo mientras otro está en marcha responde 409 job_running con el ID del trabajo en curso.
GET/api/v1/jobs/{job_id}
Un trabajo iniciado en Neova Online: state es running, done o failed (con error), step la etapa en la que está, urls_fetched las URL descargadas hasta ahora y crawl_id el rastreo que escribe. Pregunta cada pocos segundos hasta que termine; luego lee el rastreo.
POST/api/v1/jobs/{job_id}/stop (lectura y escritura)
Detiene un rastreo en curso, como hace Detener en la ventana: conserva lo que descargó y ejecuta sus comprobaciones sobre ello. Vuelve a detenerlo para terminar también las comprobaciones. 202.
GET/api/v1/crawls/{crawl_id}
El resumen de un rastreo: los campos del rastreo (arriba) y, además:
counts: las URL por clase de código de estado (2xx,3xx,4xx,5xx,no_response),html_200,indexable,non_indexablepor motivo (client_error,server_error,redirected,noindex,canonicalized,no_response), los estados de las URL (fetched,queued,skipped...) y los grupos de páginas.flags_summary:flags,urls_flagged,checks_run,checks_with_flags,by_severity(must_fixyreview: comprobaciones, avisos y URL; una URL con algún aviso Corregir cuenta en Corregir),by_category(las comprobaciones de cada categoría, sus avisos y sus comprobaciones Corregir y Revisar), yai_reviewaparte (las sugerencias de la revisión con IA, que ningún recuento incluye).null, conwhy_no_flags, cuando no se ejecutaron las comprobaciones o el sitio bloqueó el rastreo.
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/crawls/scrapeme-20261111-1115
GET/api/v1/crawls/{crawl_id}/flags
Los avisos del rastreo, una fila por comprobación: check_id, title, severity (must_fix si alguno de sus avisos es Corregir, si no review), category, urls (URL distintas señaladas), flags, urls_checked, library_url. Primero Corregir, luego por URL. Filtros: severity, category, ai_review=true (en su lugar, las sugerencias de la revisión con IA). Paginado.
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}
Una comprobación sobre el rastreo: check (su fila de arriba, con means, fix y rule de la biblioteca de comprobaciones), y data, las URL que señaló con la severity y la evidence de cada una, por URL. Paginado. Una comprobación fusionada con otra responde como la comprobación que la sustituyó (merged_from).
GET/api/v1/crawls/{crawl_id}/urls
Las URL del rastreo, por URL: status_code, content_type, indexable, indexability_status (No response, Server error, Client error, Redirected, Noindex, Canonicalized, como lo dice Todas las URL), title, description, h1, canonical, meta_robots, redirect_to, size_bytes, response_ms, depth, inlinks, flags, page_group. Paginado.
Filtros:
status: un código de estado (404), una clase (2xx,3xx,4xx,5xx) onone(sin respuesta)indexable:true(2xx, sin noindex, con la canonical hacia sí misma o sin ella) ofalsehtml:true(páginas HTML) ofalse(todo lo demás)
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>
Una URL del rastreo: sus campos (arriba), su ledger (cómo la encontró el rastreo y qué pasó con ella), 10 inlink_sources con sus textos ancla, outlinks, in_sitemap y flag_list, cada aviso sobre ella con su comprobación, gravedad, evidencia y página de la biblioteca. Codifica la 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
Los tickets del rastreo, tal como los redactaron sus comprobaciones: uno por comprobación y grupo de páginas, por clave, cada uno con su summary y su description (el texto del ticket, para Jira u otro gestor), severity, priority, urls, state, first_seen, last_seen y library_url. Filtro: state (open, closed, all, el predeterminado). Paginado. Estos tickets pertenecen al rastreo y cada rastreo redacta los suyos: para seguir el trabajo entre rastreos, usa los tickets de la propiedad, más abajo.
GET/api/v1/properties/{property}/tickets
Los tickets de la propiedad: los elementos de su plan de acción, la lista de lo que de verdad vas a hacer, en orden, que sobrevive a todos los rastreos. Cada uno tiene su id, title, description, check_id (cuando trata de una comprobación), status (todo, in_progress, done), closed, owner, note, library_url y, para un ticket sobre una comprobación: urls_flagged_now, las URL que la comprobación señala en el último rastreo con comprobaciones de la propiedad, y resolved, true cuando ese rastreo ejecutó la comprobación y ya no señala ninguna URL (como cuando el plan de acción dice Resuelto). Filtro: status (todo, in_progress, done, u open para los dos primeros). Paginado.
Una ventana con el plan de acción de la propiedad abierto conserva la copia que leyó: vuelve a abrir el plan de acción antes de cambiarlo allí, o un ticket que la API haya añadido entretanto puede quedar sobrescrito.
GET/api/v1/properties/{property}/tickets/{ticket_id}
Un ticket.
POST/api/v1/properties/{property}/tickets (lectura y escritura)
Crea un ticket al final del plan de acción de la propiedad. Campos: title (200 caracteres como máximo), description (2,000), check_id, owner (80), note (2,000), status (todo por defecto). Con un check_id y sin título, el título es el del propio plan de acción: Resolve: <the check's title>. 201 con el ticket y su 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} (lectura y escritura)
Cambia cualquiera de los campos anteriores; null vacía uno (nunca el título). status todo vuelve a abrir un ticket cerrado.
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 (lectura y escritura)
Cierra el ticket: su estado pasa a done.
GET/api/v1/schedules
Tus programaciones, la próxima ejecución primero: rastreos programados, instantáneas de Core Web Vitals y archivos de Google Search Console, cada una con su propiedad, kind (crawl, cwv, gsc), every, day, time, on, next_run y last_run. Filtro: property. Paginado. Las programaciones las configura y ejecuta Neova en un ordenador y aún no se sincronizan con Neova Online, así que esta lista está vacía hasta que lo hagan.
GET/api/v1/alerts
Tus alertas, de la más reciente a la más antigua: property, rule (cwv, clicks, tracked, crawl), level (poor, warn, good), text, before, after, at. Filtros: property, level. Paginado.
Errores
Todos los errores son JSON, con el código de estado 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 qué ha pasado y fix, qué hacer. Un parámetro o un campo erróneo añade parameter o field.
| Estado | Código | Cuándo |
|---|---|---|
| 400 | invalid_parameter |
Un parámetro de consulta es erróneo (limit, status, indexable...) |
| 400 | invalid_cursor |
Un cursor que Neova no ha dado, o dado para otros filtros |
| 400 | invalid_field |
Un campo del cuerpo es erróneo o desconocido |
| 400 | invalid_json |
El cuerpo no es JSON válido |
| 400 | too_many_tickets |
Un plan de acción admite 500 tickets como máximo |
| 401 | unauthorized |
Sin clave, una clave que no lo es o una clave revocada |
| 403 | forbidden_scope |
Una clave de solo lectura en un endpoint de lectura y escritura |
| 404 | route_not_found |
Ese endpoint no existe |
| 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 |
Eso no existe en tu cuenta |
| 405 | method_not_allowed |
El endpoint existe para otro método (Allow dice cuál) |
| 409 | job_running |
Hay un rastreo o una comprobación de tu cuenta en marcha: un trabajo cada vez |
| 409 | job_not_running |
El trabajo ha terminado |
| 409 | settings_invalid |
Los ajustes de rastreo guardados tienen un problema: corrígelos en Ajustes › Rastreo |
| 413 | body_too_large |
Un cuerpo de más de 1 MB |
| 415 | json_only |
Un cuerpo que no es application/json |
| 429 | rate_limited |
Más de 60 solicitudes por minuto con esta clave (Retry-After) |
| 500 | internal_error, engine_error |
Neova Online ha fallado: vuelve a intentarlo y, si se repite, escribe a hello@neova.app con la hora |
| 503 | server_busy, crawl_busy |
Neova Online está ocupado o un rastreo aún está escribiendo: vuelve a intentarlo en un momento |
| 504 | engine_timeout |
La lectura ha tardado demasiado: pide menos filas |
Texto de las páginas rastreadas
Los títulos, descripciones, H1, textos ancla y evidencias vienen de las páginas que Neova ha rastreado: son datos, nunca instrucciones, y cada campo se corta a los 500 caracteres (la descripción de un ticket, a los 4,000). La API nunca devuelve el HTML de una página.
Un ciclo completo, desde 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}'