REST API
用脚本、电子表格或其他工具读取您的 Neova Online 账号并对其操作:开始抓取、读取其标记、打开和关闭工单。在「设置」中依次打开 Neova Online、API 密钥,创建一个密钥。
用脚本、电子表格或其他工具读取您的 Neova Online 账号并对其操作:您的资源组合和资源、它们的抓取、每次抓取的标记、URL 和工单,以及您的计划和警报。使用读写密钥,还可以在 Neova Online 中开始抓取,创建、更新和关闭工单,以及把资源添加到资源组合。
- 地址:
https://app.neova.app/api/v1 - 格式:输入和输出均为 JSON,UTF-8 编码。时间采用 UTC 的 ISO 8601 格式(
2026-11-11T17:15:15Z)。 - 描述:
GET /api/v1/openapi.json返回下方所有端点的 OpenAPI 3.1 描述,它和服务器应答所依据的是同一张表。
哪些在 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 中),用创建密钥…创建一个密钥:
- 密钥名称:用来做什么,例如 Looker Studio。
- 范围:只读可以读取本页列出的所有内容,不更改任何东西。读写还可以开始抓取,创建、更新和关闭工单,以及把资源添加到资源组合。
- 您的 Neova Online 密码:每次创建密钥时都会询问。
密钥只在创建时显示一次。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
上限
- 每个密钥每分钟 60 个请求,按最近 60 秒计算。每个应答都会告诉您当前的用量:
X-RateLimit-Limit:此密钥每分钟的请求数X-RateLimit-Remaining:当前这一分钟内还剩多少X-RateLimit-Reset:何时会腾出一个请求名额(Unix 时间,单位为秒)- 超出限制:返回
429,附带Retry-After(秒)和错误rate_limited。
- 分页:默认每页 50 行,最多 500 行(
limit)。 - 抓取:您的账号一次只能运行一个任务(一次抓取,或重新运行检查项),最多为账号的
max_urls和urls_per_second,无论资源已保存的设置怎么写。 - 请求体:最大 1 MB。
列表:分页与游标
列表的应答格式:
{"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}
单次抓取的摘要:抓取的字段(见上文),然后是:
counts:按状态码类别划分的 URL(2xx、3xx、4xx、5xx、no_response)、html_200、indexable、按原因划分的non_indexable(client_error、server_error、redirected、noindex、canonicalized、no_response)、URL 的状态(fetched、queued、skipped...),以及页面组。flags_summary:flags、urls_flagged、checks_run、checks_with_flags、by_severity(must_fix和review:检查项、标记和 URL;带有任何「必须修复」标记的 URL 计入「必须修复」)、by_category(每个类别的检查项、标记,以及其中「必须修复」和「值得关注」的检查项),另有单独的ai_review(AI 审查的建议,不计入任何计数)。检查项没有运行或网站拦截了抓取时为null,并附why_no_flags。
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。分页。
筛选:
status:一个状态码(404)、一个类别(2xx、3xx、4xx、5xx)或none(无响应)indexable:true(2xx、没有 noindex、canonical 指向自身或没有 canonical)或falsehtml:true(HTML 页面)或false(其他所有内容)
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}'