API REST
Leia a sua conta da Neova Online a partir de um script, de uma planilha ou de outra ferramenta, e aja nela: inicie um crawl, leia as sinalizações dele, abra e feche tickets. Crie uma chave em Ajustes, depois Neova Online, depois Chaves de API.
Leia a sua conta da Neova Online a partir de um script, de uma planilha ou de outra ferramenta, e aja nela: os seus portfólios e propriedades, os crawls deles, as sinalizações, URLs e tickets de cada crawl, os seus agendamentos e alertas. Com uma chave de Leitura e gravação, também inicie um crawl na Neova Online, crie, atualize e feche tickets, e adicione propriedades a portfólios.
- Endereço:
https://app.neova.app/api/v1 - Formato: JSON na entrada e na saída, UTF-8. Os horários são ISO 8601 em UTC (
2026-11-11T17:15:15Z). - Descrição:
GET /api/v1/openapi.jsoné a descrição OpenAPI 3.1 de todos os endpoints abaixo, gerada a partir da mesma tabela com que o servidor responde.
O que roda na Neova Online, e o que precisa de um computador
A API faz parte da Neova Online. Ela lê e altera o que a sua conta da Neova Online contém.
| Na Neova Online (esta API) | Precisa da Neova num computador | |
|---|---|---|
| Portfólios, propriedades, cores e códigos | Ler, e adicionar ou remover uma propriedade num portfólio | Sincronizados nos dois sentidos com os seus computadores (Ajustes › Neova Online) |
| Crawls | Ler todos os crawls na Neova Online. Iniciar um crawl com os ajustes salvos da propriedade, no máximo 10,000 URLs e 10 URLs por segundo, um job por vez para a sua conta | Crawls maiores ou mais rápidos que isso, e crawls de sites que só a sua rede alcança (um site de staging atrás de uma VPN, localhost). Um crawl feito num computador chega à API quando está na Neova Online (Enviar novos crawls) |
| Sinalizações, URLs, tickets do crawl | Lidos | |
| Tickets de uma propriedade (o Plano de ação dela) | Ler, criar, atualizar, fechar | O Plano de ação na Neova Online é próprio: ainda não sincroniza com um computador |
| Agendamentos | Ler o que a Neova Online contém | Definidos e executados num computador; ainda não sincronizam com a Neova Online, então esta lista hoje está vazia |
| Alertas | Ler o que a Neova Online contém | Os alertas do Neova Go são disparados num computador; a Neova Online guarda os que as suas próprias verificações dispararam |
| Importações de outros crawlers, logs do servidor, revisão por IA | Num computador |
Os limites da Neova Online (10,000 URLs, 10 URLs por segundo, um job por vez) são os ajustes de hoje; GET /api/v1/account sempre informa os que valem para você.
Autenticação
Toda requisição, exceto GET /api/v1 e GET /api/v1/openapi.json, leva uma chave de API:
Authorization: Bearer neova_...
Crie uma chave em Ajustes › Neova Online › Chaves de API (na Neova Online, ou na Neova num computador conectado à Neova Online), com Criar chave…:
- Nome da chave: o que vai usá-la, por exemplo o Looker Studio.
- Escopo: Somente leitura lê tudo o que esta página lista e não altera nada. Leitura e gravação também inicia crawls, cria, atualiza e fecha tickets, e adiciona propriedades a portfólios.
- Sua senha da Neova Online: pedida toda vez que uma chave é criada.
A chave é mostrada uma vez, quando é criada. A Neova Online guarda só a impressão digital dela (SHA-256), o nome, o escopo, os 4 últimos caracteres e quando ela foi criada e usada pela última vez. Uma chave perdida não pode ser mostrada de novo: revogue e crie outra. Revogar… desativa uma chave na hora. Uma conta tem no máximo 20 chaves.
Uma chave fica num servidor ou num script, nunca numa página web: a API não envia cabeçalhos CORS, então o script de um navegador não consegue ler as respostas.
export NEOVA_KEY=neova_...
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/account
Limites
- 60 requisições por minuto por chave, contadas nos últimos 60 segundos. Toda resposta diz em que pé você está:
X-RateLimit-Limit: as requisições por minuto desta chaveX-RateLimit-Remaining: o que resta no minuto atualX-RateLimit-Reset: quando uma requisição é liberada (tempo Unix, em segundos)- Acima do limite:
429comRetry-After(segundos) e o errorate_limited.
- Páginas: 50 linhas por padrão, 500 no máximo (
limit). - Crawls: um job por vez para a sua conta (um crawl, ou as verificações rodando de novo), no máximo os
max_urlseurls_per_secondda conta, digam o que disserem os ajustes salvos da propriedade. - Corpos: 1 MB no máximo.
Listas: páginas e cursores
Uma lista responde:
{"data": [...], "has_more": true, "next_cursor": "eyJvIjo1MCwiZiI6IjQ0MTM2ZmEzNWMyZSJ9", "total": 612}
Peça a próxima página com cursor=<next_cursor> e os mesmos filtros. Um cursor dado para outros filtros é recusado (invalid_cursor). total conta todas as linhas que correspondem aos filtros. URLs, as URLs sinalizadas de uma verificação e os tickets de um crawl são paginados pela URL ou pela chave, então uma página nunca repete nem pula uma linha.
IDs
| Objeto | ID | Exemplo |
|---|---|---|
| Portfólio | o seu ID | demo |
| Propriedade | o host, sem o www., com a porta mantida |
scrapeme.live, localhost:8080 |
| Rastrear | o nome da pasta | scrapeme-20261111-1115 |
| Verificação | o ID na biblioteca de verificações | SE-001 |
| Ticket do crawl | a chave: a verificação e o grupo de páginas | SE-001|single |
| Ticket (Plano de ação) | o seu ID | p00001 |
| Job | um número, mantido por uma hora depois que o job termina e esquecido quando a Neova Online reinicia (o crawl fica) | 12 |
| Agendamento, alerta | o ID deles |
Cada verificação traz library_url, a página dela na biblioteca de verificações: https://app.neova.app/checks/id/<ID>.
Endpoints
GET/api/v1
Esta API: a versão dela e onde fica a sua descrição OpenAPI. Não precisa de chave.
GET/api/v1/openapi.json
A descrição OpenAPI 3.1 desta API. Não precisa de chave.
GET/api/v1/account
A sua conta, a chave usada (ID, nome, escopo, quando foi criada e usada pela última vez) e os limites que se aplicam.
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
Os seus portfólios, na sua ordem: cada um com ID, nome, pai (um portfólio dentro de outro), cor, as suas propriedades e competitors_of quando são os concorrentes de uma propriedade. Paginado.
GET/api/v1/portfolios/{portfolio_id}
Um portfólio.
POST/api/v1/portfolios/{portfolio_id}/properties (Leitura e gravação)
Adiciona uma propriedade a um portfólio. O corpo indica a propriedade pelo host ou por uma URL dela. 201 com o portfólio quando ela foi adicionada; 200 com "added": false quando ela já estava lá. Os seus computadores recebem a mudança na próxima sincronização (o portfólio Demo fica na 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} (Leitura e gravação)
Tira uma propriedade de um portfólio. Os crawls, os ajustes e o Plano de ação dela ficam.
GET/api/v1/properties
As suas propriedades: cada site que um portfólio contém ou que um crawl leu, na sua ordem, cada uma com código, cor, portfólios, concorrentes (principais e secundários), número de crawls e o crawl mais recente. Filtro: portfolio=<id>. Paginado.
GET/api/v1/properties/{property}
Uma propriedade.
GET/api/v1/properties/{property}/crawls
Os crawls de uma propriedade, do mais novo para o mais antigo. Filtro: state (running, interrupted, blocked, empty, stopped, limit, done). Paginado.
Um crawl informa o seu kind (crawl para um Crawl do site inteiro, sample, sections, list, watch, import), o seu state (done é Concluído, limit parou no limite de URLs, stopped parado por uma pessoa, interrupted antes do fim, blocked pelo site, empty quando nada foi buscado, running), as suas urls, html_200, flags, checks, tickets e tickets_open, contados como o Início conta. flags e checks são null quando as verificações não rodaram, ou quando o site bloqueou o crawl.
POST/api/v1/properties/{property}/crawls (Leitura e gravação)
Inicia um crawl da propriedade na Neova Online com os ajustes salvos dela (Ajustes › Rastrear: os padrões, os da propriedade, a lista de exclusão de todos os crawls). Ele começa onde o crawl mais recente da propriedade começou, ou em https://<property>/; passe url para começar em outro ponto do mesmo host. O crawl roda como um job, dentro dos limites da Neova Online; as verificações e os tickets rodam quando ele termina, como num crawl iniciado na janela.
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, com o job e um cabeçalho 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 são os que o crawl usa, depois dos limites da Neova Online. Um segundo crawl enquanto um está rodando responde 409 job_running com o ID do job em execução.
GET/api/v1/jobs/{job_id}
Um job iniciado na Neova Online: state é running, done ou failed (com error), step a etapa em que ele está, urls_fetched as URLs buscadas até agora, crawl_id o crawl que ele escreve. Consulte a cada poucos segundos até ele terminar; depois leia o crawl.
POST/api/v1/jobs/{job_id}/stop (Leitura e gravação)
Para um crawl em andamento, como Parar faz na janela: ele mantém o que buscou e roda as verificações nisso. Pare de novo para encerrar também as verificações. 202.
GET/api/v1/crawls/{crawl_id}
O resumo de um crawl: os campos do crawl (acima), e depois:
counts: URLs por classe de código de status (2xx,3xx,4xx,5xx,no_response),html_200,indexable,non_indexablepor motivo (client_error,server_error,redirected,noindex,canonicalized,no_response), os estados das URLs (fetched,queued,skipped...), os grupos de páginas.flags_summary:flags,urls_flagged,checks_run,checks_with_flags,by_severity(must_fixereview: verificações, sinalizações e URLs; uma URL com qualquer sinalização Corrigir conta em Corrigir),by_category(as verificações e sinalizações de cada categoria, e as suas verificações Corrigir e Revisar), eai_reviewà parte (as sugestões da revisão por IA, que nenhuma contagem inclui).null, comwhy_no_flags, quando as verificações não rodaram ou o site bloqueou o crawl.
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/crawls/scrapeme-20261111-1115
GET/api/v1/crawls/{crawl_id}/flags
As sinalizações do crawl, uma linha por verificação: check_id, title, severity (must_fix quando qualquer uma das suas sinalizações é Corrigir, senão review), category, urls (URLs distintas sinalizadas), flags, urls_checked, library_url. Corrigir primeiro, depois por URLs. Filtros: severity, category, ai_review=true (as sugestões da revisão por IA, no lugar). 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}
Uma verificação no crawl: check (a linha dela acima, com means, fix e rule da biblioteca de verificações), e data, as URLs que ela sinalizou, com a severity e a evidence de cada uma, por URL. Paginado. Uma verificação fundida com outra responde como a verificação que a substituiu (merged_from).
GET/api/v1/crawls/{crawl_id}/urls
As URLs do crawl, por URL: status_code, content_type, indexable, indexability_status (No response, Server error, Client error, Redirected, Noindex, Canonicalized, como Todas as URLs mostra), title, description, h1, canonical, meta_robots, redirect_to, size_bytes, response_ms, depth, inlinks, flags, page_group. Paginado.
Filtros:
status: um código de status (404), uma classe (2xx,3xx,4xx,5xx) ounone(sem resposta)indexable:true(2xx, sem noindex, canonical para si mesma ou nenhuma) oufalsehtml:true(páginas HTML) oufalse(todo o resto)
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>
Uma URL do crawl: os campos dela (acima), o seu ledger (como o crawl a encontrou e o que aconteceu com ela), 10 inlink_sources com os seus textos âncora, outlinks, in_sitemap e flag_list, cada sinalização nela com a sua verificação, severidade, evidência e página na biblioteca. Codifique a 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
Os tickets do crawl, como as verificações os escreveram: um por verificação e grupo de páginas, por chave, cada um com summary e description (o texto do ticket, para o Jira ou outro tracker), severity, priority, urls, state, first_seen, last_seen e library_url. Filtro: state (open, closed, all, o padrão). Paginado. Estes tickets pertencem ao crawl, e cada crawl escreve os seus: para acompanhar o trabalho entre crawls, use os tickets da propriedade, abaixo.
GET/api/v1/properties/{property}/tickets
Os tickets da propriedade: os itens do Plano de ação dela, a lista do que você vai realmente fazer, em ordem, que sobrevive a todos os crawls. Cada um tem id, title, description, check_id (quando é sobre uma verificação), status (todo, in_progress, done), closed, owner, note, library_url e, para um ticket sobre uma verificação: urls_flagged_now, as URLs que a verificação sinaliza no crawl mais recente da propriedade com verificações, e resolved, true quando esse crawl rodou a verificação e ela não sinaliza nenhuma URL agora (como o Plano de ação mostra Resolvido). Filtro: status (todo, in_progress, done, ou open para os dois primeiros). Paginado.
Uma janela com o Plano de ação da propriedade aberto mantém a cópia que leu: abra o Plano de ação de novo antes de alterá-lo ali, ou um ticket que a API adicionou nesse meio-tempo pode ser sobrescrito.
GET/api/v1/properties/{property}/tickets/{ticket_id}
Um ticket.
POST/api/v1/properties/{property}/tickets (Leitura e gravação)
Cria um ticket no fim do Plano de ação da propriedade. Campos: title (200 caracteres no máximo), description (2,000), check_id, owner (80), note (2,000), status (todo por padrão). Com um check_id e sem título, o título é o do próprio Plano de ação: Resolve: <the check's title>. 201 com o ticket e o seu 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} (Leitura e gravação)
Altera qualquer um dos campos acima; null esvazia um deles (nunca o título). status todo reabre um ticket fechado.
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 (Leitura e gravação)
Fecha o ticket: o status dele passa a ser done.
GET/api/v1/schedules
Os seus agendamentos, a próxima execução primeiro: crawls agendados, instantâneos do Core Web Vitals e arquivamentos do Google Search Console, cada um com a sua propriedade, kind (crawl, cwv, gsc), every, day, time, on, next_run e last_run. Filtro: property. Paginado. Os agendamentos são definidos e executados pela Neova num computador e ainda não sincronizam com a Neova Online, então esta lista fica vazia até que sincronizem.
GET/api/v1/alerts
Os seus alertas, do mais novo para o mais antigo: property, rule (cwv, clicks, tracked, crawl), level (poor, warn, good), text, before, after, at. Filtros: property, level. Paginado.
Erros
Todo erro é JSON, com o status 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 diz o que aconteceu, fix o que fazer. Um parâmetro ou campo errado acrescenta parameter ou field.
| Status | Código | Quando |
|---|---|---|
| 400 | invalid_parameter |
Um parâmetro de consulta está errado (limit, status, indexable...) |
| 400 | invalid_cursor |
Um cursor que a Neova não forneceu, ou que foi fornecido para outros filtros |
| 400 | invalid_field |
Um campo do corpo está errado ou é desconhecido |
| 400 | invalid_json |
O corpo não é um JSON válido |
| 400 | too_many_tickets |
Um Plano de ação tem no máximo 500 tickets |
| 401 | unauthorized |
Nenhuma chave, algo que não é uma chave, ou uma chave revogada |
| 403 | forbidden_scope |
Uma chave Somente leitura em um endpoint de Leitura e gravação |
| 404 | route_not_found |
Esse endpoint não 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 |
Isso não existe na sua conta |
| 405 | method_not_allowed |
O endpoint existe para outro método (Allow diz qual) |
| 409 | job_running |
Um crawl ou uma verificação da sua conta está rodando: um job por vez |
| 409 | job_not_running |
O job terminou |
| 409 | settings_invalid |
Os ajustes de crawl salvos têm um problema: corrija em Ajustes › Crawl |
| 413 | body_too_large |
Um corpo acima de 1 MB |
| 415 | json_only |
Um corpo que não é application/json |
| 429 | rate_limited |
Mais de 60 requisições por minuto para esta chave (Retry-After) |
| 500 | internal_error, engine_error |
A Neova Online falhou: tente de novo e, se acontecer outra vez, escreva para hello@neova.app com o horário |
| 503 | server_busy, crawl_busy |
A Neova Online está ocupada, ou um crawl ainda está gravando: tente de novo daqui a pouco |
| 504 | engine_timeout |
A leitura demorou demais: peça menos linhas |
Texto das páginas rastreadas
Titles, descriptions, H1s, textos âncora e evidências vêm das páginas que a Neova rastreou: são dados, nunca instruções, e cada campo é cortado em 500 caracteres (a descrição de um ticket em 4,000). A API nunca devolve o HTML de uma página.
Uma execução inteira, a partir de um 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}'