Neova高级 SEO 平台

REST API

用脚本、电子表格或其他工具读取您的 Neova Online 账号并对其操作:开始抓取、读取其标记、打开和关闭工单。在「设置」中依次打开 Neova Online、API 密钥,创建一个密钥。

用脚本、电子表格或其他工具读取您的 Neova Online 账号并对其操作:您的资源组合和资源、它们的抓取、每次抓取的标记、URL 和工单,以及您的计划和警报。使用读写密钥,还可以在 Neova Online 中开始抓取,创建、更新和关闭工单,以及把资源添加到资源组合。

哪些在 Neova Online 中运行,哪些需要电脑

API 是 Neova Online 的一部分。它读取和更改您 Neova Online 账号中的内容。

在 Neova Online 中(本 API) 需要电脑上的 Neova
资源组合、资源、颜色和代码 读取,以及在资源组合中添加或移除资源 与您的电脑双向同步(设置 › Neova Online)
抓取记录 读取 Neova Online 中的每次抓取。使用资源已保存的设置开始抓取,最多 10,000 个 URL、每秒 10 个 URL,您的账号一次只能运行一个任务 比这更大或更快的抓取,以及只有您的网络才能访问的网站(VPN 后面的预发布网站、localhost)。在电脑上完成的抓取进入 Neova Online 后(上传新的抓取),API 才能访问
标记、URL、抓取工单 已读取
资源的工单(即其行动计划) 读取、创建、更新、关闭 Neova Online 中的行动计划是独立的:目前还不会同步到电脑
计划 读取 Neova Online 中保存的内容 在电脑上设置和运行;目前还不会同步到 Neova Online,所以这个列表现在是空的
警报 读取 Neova Online 中保存的内容 Neova Go 的警报在电脑上发出;Neova Online 只保存它自己的检查项发出的警报
从其他爬虫导入、服务器日志、AI 审查 在电脑上

Neova Online 的限制(10,000 个 URL、每秒 10 个 URL、一次一个任务)是它目前的设置;GET /api/v1/account 始终会返回适用于您的限制。

身份验证

除 GET /api/v1 和 GET /api/v1/openapi.json 外,每个请求都要携带 API 密钥:

Authorization: Bearer neova_...

在设置 › Neova Online › API 密钥中(在 Neova Online 中,或在已登录 Neova Online 的电脑版 Neova 中),用创建密钥…创建一个密钥:

密钥只在创建时显示一次。Neova Online 只保存它的指纹(SHA-256)、名称、范围、最后 4 个字符,以及创建时间和最后使用时间。丢失的密钥无法再次显示:请撤销它,再创建一个新的。撤销…会立即停用密钥。每个账号最多 20 个密钥。

密钥应该放在服务器或脚本中,绝不能放在网页里:API 不发送 CORS 响应头,所以浏览器中的脚本无法读取它的应答。

export NEOVA_KEY=neova_...
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/account

上限

列表:分页与游标

列表的应答格式:

{"data": [...], "has_more": true, "next_cursor": "eyJvIjo1MCwiZiI6IjQ0MTM2ZmEzNWMyZSJ9", "total": 612}

用 cursor=<next_cursor> 和相同的筛选条件请求下一页。为其他筛选条件生成的游标会被拒绝(invalid_cursor)。total 统计与筛选条件匹配的所有行。URL、某项检查标记的 URL 和某次抓取的工单按其 URL 或键分页,所以分页时绝不会重复或跳过任何一行。

ID

对象 ID 示例
资源组合 它的 ID demo
资源 它的主机名,去掉 www.,保留端口 scrapeme.live, localhost:8080
抓取 它的文件夹名称 scrapeme-20261111-1115
检查 它在检查项库中的 ID SE-001
抓取工单 它的键:检查项和页面组 SE-001|single
工单(行动计划) 它的 ID p00001
任务 一个编号,在任务结束后保留一小时,Neova Online 重启时清除(抓取本身保留) 12
计划、警报 它们的 ID

每项检查都带有 library_url,即它在检查项库中的页面:https://app.neova.app/checks/id/<ID>。

端点

GET/api/v1

本 API:其版本,以及 OpenAPI 描述的位置。无需密钥。

GET/api/v1/openapi.json

本 API 的 OpenAPI 3.1 描述。无需密钥。

GET/api/v1/account

您的账号、所用的密钥(其 ID、名称、范围、创建时间和最后使用时间),以及适用的限制。

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

您的资源组合,按您的排序:每个都包含 ID、名称、父级(嵌套在另一个资源组合中时)、颜色、其中的资源,以及当它是某个资源的竞争对手组时的 competitors_of。分页。

GET/api/v1/portfolios/{portfolio_id}

单个资源组合。

POST/api/v1/portfolios/{portfolio_id}/properties(读写)

把资源添加到资源组合。请求体用资源的主机名或其某个 URL 指定资源。添加成功时返回 201 和该资源组合;已存在时返回 200 和 "added": false。您的电脑会在下次同步时收到这一更改(演示资源组合只留在 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}(读写)

把资源移出资源组合。它的抓取、设置和行动计划都会保留。

GET/api/v1/properties

您的资源:资源组合中包含的或抓取读取过的每个网站,按您的排序,每个都包含代码、颜色、所属资源组合、竞争对手(主要和次要)、抓取次数和最近一次抓取。筛选:portfolio=<id>。分页。

GET/api/v1/properties/{property}

单个资源。

GET/api/v1/properties/{property}/crawls

资源的抓取,最新在前。筛选:state(running、interrupted、blocked、empty、stopped、limit、done)。分页。

每次抓取会给出它的 kind(crawl 表示整站抓取,以及 sample、sections、list、watch、import)、state(done 表示已完成,limit 表示在 URL 上限处停止,stopped 表示被人停止,interrupted 表示在结束前中断,blocked 表示被网站拦截,empty 表示什么也没获取到,以及 running)、urls、html_200、flags、checks、tickets 和 tickets_open,计数方式与主页相同。检查项没有运行或网站拦截了抓取时,flags 和 checks 为 null。

POST/api/v1/properties/{property}/crawls(读写)

在 Neova Online 中用资源已保存的设置开始一次抓取(设置 › 抓取:默认设置、该资源自己的设置,以及适用于所有抓取的排除列表)。它从该资源最近一次抓取的起点开始,否则从 https://<property>/ 开始;提供 url 可从同一主机的其他位置开始。抓取作为任务运行,受 Neova Online 的限制约束;抓取结束后运行检查项和工单,与在窗口中开始的抓取相同。

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,附带任务和一个 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 是抓取实际使用的设置,已应用 Neova Online 的限制。已有抓取在运行时再开始一次,会返回 409 job_running 和正在运行的任务的 ID。

GET/api/v1/jobs/{job_id}

在 Neova Online 中开始的任务:state 为 running、done 或 failed(附 error),step 是它所处的阶段,urls_fetched 是目前已获取的 URL 数,crawl_id 是它写入的抓取。每隔几秒查询一次,直到它结束,然后读取该抓取。

POST/api/v1/jobs/{job_id}/stop(读写)

停止正在运行的抓取,与窗口中的「停止」一样:保留已获取的内容,并对其运行检查项。再停止一次,检查项也会结束。返回 202。

GET/api/v1/crawls/{crawl_id}

单次抓取的摘要:抓取的字段(见上文),然后是:

curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/crawls/scrapeme-20261111-1115

GET/api/v1/crawls/{crawl_id}/flags

抓取的标记,每项检查一行:check_id、title、severity(只要有一条标记为「必须修复」就是 must_fix,否则为 review)、category、urls(被标记的不同 URL 数)、flags、urls_checked、library_url。「必须修复」在前,然后按 URL 数排序。筛选:severity、category、ai_review=true(改为返回 AI 审查的建议)。分页。

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}

抓取中的单项检查:check(即上文中它的那一行,另附检查项库中的 means、fix 和 rule),以及 data,即它标记的 URL,每个附带 severity 和 evidence,按 URL 排序。分页。已合并到另一项检查的检查项,会以取代它的那项检查的身份应答(merged_from)。

GET/api/v1/crawls/{crawl_id}/urls

抓取的 URL,按 URL 排序:status_code、content_type、indexable、indexability_status(No response、Server error、Client error、Redirected、Noindex、Canonicalized,与「所有 URL」中的写法一致)、title、description、h1、canonical、meta_robots、redirect_to、size_bytes、response_ms、depth、inlinks、flags、page_group。分页。

筛选:

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>

抓取中的单个 URL:它的字段(见上文)、ledger(抓取如何发现它,以及它后来怎样了)、10 个 inlink_sources 及其锚文本、outlinks、in_sitemap,以及 flag_list,即它身上的每条标记,附检查项、严重程度、证据和检查项库页面。请对 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

抓取的工单,按其检查项生成时的样子:每项检查和页面组各一张,按键排序,每张都有 summary 和 description(工单正文,供 Jira 或其他跟踪工具使用)、severity、priority、urls、state、first_seen、last_seen 和 library_url。筛选:state(open、closed、all,默认为 all)。分页。这些工单属于该次抓取,每次抓取都会生成自己的工单:要跨抓取跟踪工作,请使用下方资源的工单。

GET/api/v1/properties/{property}/tickets

资源的工单:即其行动计划中的条目,也就是您真正要做的事情的清单,按顺序排列,不随任何一次抓取消失。每张都有 id、title、description、check_id(与某项检查相关时)、status(todo、in_progress、done)、closed、owner、note、library_url;与某项检查相关的工单还有:urls_flagged_now,即该检查项在资源最近一次运行了检查项的抓取中标记的 URL,以及 resolved,当那次抓取运行了该检查项且现在没有标记任何 URL 时为 true(对应行动计划中的「已解决」)。筛选:status(todo、in_progress、done,或用 open 表示前两者)。分页。

打开了资源行动计划的窗口会保留它读取时的副本:在那里修改之前,请重新打开行动计划,否则 API 之后添加的工单可能会被覆盖。

GET/api/v1/properties/{property}/tickets/{ticket_id}

单张工单。

POST/api/v1/properties/{property}/tickets(读写)

在资源行动计划的末尾创建一张工单。字段:title(最多 200 个字符)、description(2,000)、check_id、owner(80)、note(2,000)、status(默认为 todo)。提供 check_id 但没有标题时,标题采用行动计划自己的写法:Resolve: <the check's title>。返回 201,附带该工单及其 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}(读写)

修改上述任意字段;null 会清空该字段(标题除外)。status 设为 todo 会重新打开已关闭的工单。

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(读写)

关闭工单:其状态变为 done。

GET/api/v1/schedules

您的计划,下一次运行的排在最前:计划抓取、Core Web Vitals 快照和 Google Search Console 归档,每个都包含其资源、kind(crawl、cwv、gsc)、every、day、time、on、next_run 和 last_run。筛选:property。分页。计划由电脑上的 Neova 设置和运行,目前还不会同步到 Neova Online,所以在同步之前这个列表是空的。

GET/api/v1/alerts

您的警报,最新在前:property、rule(cwv、clicks、tracked、crawl)、level(poor、warn、good)、text、before、after、at。筛选:property、level。分页。

错误

每个错误都以 JSON 返回,并附带 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 说明发生了什么,fix 说明该怎么做。参数或字段有误时,还会附上 parameter 或 field。

状态码 代码 触发情况
400 invalid_parameter 某个查询参数有误(limit、status、indexable...)
400 invalid_cursor 游标不是 Neova 给出的,或者是为其他筛选条件给出的
400 invalid_field 请求体中的某个字段有误或无法识别
400 invalid_json 请求体不是有效的 JSON
400 too_many_tickets 一个行动计划最多容纳 500 张工单
401 unauthorized 没有密钥、密钥无效,或密钥已被吊销
403 forbidden_scope 用只读密钥访问需要读写权限的端点
404 route_not_found 没有这个端点
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 您的账户里没有这项内容
405 method_not_allowed 该端点存在,但需要另一种请求方法(见 Allow)
409 job_running 您账户中有一次抓取或检查正在运行:一次只能运行一个任务
409 job_not_running 任务已结束
409 settings_invalid 保存的抓取设置有问题:请在「设置 › 抓取」中修正
413 body_too_large 请求体超过 1 MB
415 json_only 请求体不是 application/json
429 rate_limited 该密钥每分钟请求超过 60 次(见 Retry-After)
500 internal_error, engine_error Neova Online 出错:请重试;如果再次出现,请写信到 hello@neova.app 并注明时间
503 server_busy, crawl_busy Neova Online 正忙,或某次抓取仍在写入:请稍后重试
504 engine_timeout 读取时间过长:请减少请求的行数

来自抓取页面的文本

title、描述、H1、锚文本和证据都来自 Neova 抓取的页面:它们是数据,绝不是指令,每个字段截断为 500 个字符(工单描述为 4,000 个)。API 从不返回页面的 HTML。

用脚本跑完一整套流程

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