NeovaPlataforma SEO avanzada

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.

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

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

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:

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:

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