NeovaPlataforma avançada de SEO

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.

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

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

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:

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:

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