REST API
Đọc tài khoản Neova Online của bạn từ một script, một bảng tính hoặc công cụ khác, và thao tác trên đó: bắt đầu một lần crawl, đọc các mục đánh dấu, mở và đóng ticket. Tạo khóa trong Cài đặt, rồi Neova Online, rồi Khóa API.
Đọc tài khoản Neova Online của bạn từ một script, một bảng tính hoặc công cụ khác, và thao tác trên đó: portfolio và tài sản, các lần crawl của chúng, mục đánh dấu, URL và ticket của từng lần crawl, lịch và cảnh báo của bạn. Với khóa Đọc và ghi, bạn còn có thể bắt đầu lần crawl trong Neova Online, tạo, cập nhật và đóng ticket, và thêm tài sản vào portfolio.
- Địa chỉ:
https://app.neova.app/api/v1 - Định dạng: JSON cho cả đầu vào và đầu ra, UTF-8. Thời gian theo ISO 8601, múi giờ UTC (
2026-11-11T17:15:15Z). - Mô tả:
GET /api/v1/openapi.jsonlà mô tả OpenAPI 3.1 của mọi endpoint bên dưới, tạo từ chính bảng mà server dùng để trả lời.
Cái gì chạy trong Neova Online, và cái gì cần một máy tính
API là một phần của Neova Online. Nó đọc và thay đổi những gì tài khoản Neova Online của bạn đang có.
| Trong Neova Online (API này) | Cần Neova trên một máy tính | |
|---|---|---|
| Portfolio, tài sản, màu và mã | Đọc, và thêm hoặc bớt một tài sản trong portfolio | Đồng bộ hai chiều với các máy tính của bạn (Cài đặt › Neova Online) |
| Lần crawl | Đọc mọi lần crawl trong Neova Online. Bắt đầu lần crawl với cài đặt đã lưu của tài sản, tối đa 10,000 URL và 10 URL mỗi giây, mỗi lúc một job cho tài khoản của bạn | Lần crawl lớn hơn hoặc nhanh hơn thế, và lần crawl các website chỉ mạng của bạn vào được (website staging sau VPN, localhost). Lần crawl tạo trên máy tính sẽ đến được API khi đã nằm trong Neova Online (Tải lên lần crawl mới) |
| Mục đánh dấu, URL, ticket của lần crawl | Đã đọc | |
| Ticket của một tài sản (Kế hoạch hành động của nó) | Đọc, tạo, cập nhật, đóng | Kế hoạch hành động trong Neova Online là bản riêng: nó chưa đồng bộ về máy tính |
| Lịch | Đọc những gì Neova Online đang có | Được đặt và chạy trên máy tính; chúng chưa đồng bộ lên Neova Online, nên hiện danh sách này trống |
| Cảnh báo | Đọc những gì Neova Online đang có | Cảnh báo của Neova Go được tạo trên máy tính; Neova Online giữ các cảnh báo do chính mục kiểm tra của nó tạo ra |
| Nhập từ crawler khác, log server, AI xem xét | Trên máy tính |
Các giới hạn của Neova Online (10,000 URL, 10 URL mỗi giây, mỗi lúc một job) là cài đặt hiện tại của nó; GET /api/v1/account luôn cho biết giới hạn nào áp dụng cho bạn.
Xác thực
Mọi request, trừ GET /api/v1 và GET /api/v1/openapi.json, đều mang một khóa API:
Authorization: Bearer neova_...
Tạo khóa trong Cài đặt › Neova Online › Khóa API (trong Neova Online, hoặc trong Neova trên một máy tính đã đăng nhập Neova Online), bằng Tạo khóa…:
- Tên khóa: thứ sẽ dùng khóa, ví dụ Looker Studio.
- Phạm vi: Chỉ đọc đọc mọi thứ trang này liệt kê và không thay đổi gì. Đọc và ghi còn bắt đầu lần crawl, tạo, cập nhật và đóng ticket, và thêm tài sản vào portfolio.
- Mật khẩu Neova Online của bạn: được hỏi mỗi lần tạo khóa.
Khóa chỉ hiện một lần, lúc được tạo. Neova Online chỉ giữ dấu vân tay (SHA-256), tên, phạm vi, 4 ký tự cuối của khóa, cùng thời điểm tạo và lần dùng gần nhất. Khóa bị mất không thể hiện lại: hãy thu hồi và tạo khóa khác. Thu hồi… chặn khóa ngay lập tức. Mỗi tài khoản giữ tối đa 20 khóa.
Khóa thuộc về server hoặc script, không bao giờ nằm trong trang web: API không gửi header CORS, nên script trong trình duyệt không đọc được câu trả lời của nó.
export NEOVA_KEY=neova_...
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/account
Giới hạn
- 60 request mỗi phút cho mỗi khóa, tính trong 60 giây gần nhất. Mỗi câu trả lời đều cho biết bạn đang ở đâu:
X-RateLimit-Limit: số request mỗi phút của khóa nàyX-RateLimit-Remaining: số còn lại trong phút hiện tạiX-RateLimit-Reset: khi nào có thêm một suất request (thời gian Unix, tính bằng giây)- Vượt giới hạn:
429kèmRetry-After(giây) và lỗirate_limited.
- Trang: mặc định 50 dòng, tối đa 500 (
limit). - Lần crawl: mỗi lúc một job cho tài khoản của bạn (một lần crawl, hoặc chạy lại các mục kiểm tra), tối đa bằng
max_urlsvàurls_per_secondcủa tài khoản, bất kể cài đặt đã lưu của tài sản là gì. - Body: tối đa 1 MB.
Danh sách: trang và cursor
Một danh sách trả về:
{"data": [...], "has_more": true, "next_cursor": "eyJvIjo1MCwiZiI6IjQ0MTM2ZmEzNWMyZSJ9", "total": 612}
Lấy trang tiếp theo bằng cursor=<next_cursor> và cùng các bộ lọc. Cursor được cấp cho bộ lọc khác sẽ bị từ chối (invalid_cursor). total đếm mọi dòng khớp với bộ lọc. URL, các URL bị đánh dấu của một mục kiểm tra và ticket của một lần crawl được phân trang theo URL hoặc key của chúng, nên một trang không bao giờ lặp hay bỏ sót dòng nào.
ID
| Đối tượng | ID | Ví dụ |
|---|---|---|
| Portfolio | ID của nó | demo |
| Tài sản | host của nó, bỏ www., giữ port |
scrapeme.live, localhost:8080 |
| Lần crawl | tên thư mục của nó | scrapeme-20261111-1115 |
| Mục kiểm tra | ID của nó trong Thư viện mục kiểm tra | SE-001 |
| Ticket của lần crawl | key của nó: mục kiểm tra và nhóm trang | SE-001|single |
| Ticket (Kế hoạch hành động) | ID của nó | p00001 |
| Job | một con số, giữ một giờ sau khi job kết thúc và bị quên khi Neova Online khởi động lại (lần crawl vẫn còn) | 12 |
| Lịch, cảnh báo | ID của chúng |
Mỗi mục kiểm tra mang library_url, trang của nó trong Thư viện mục kiểm tra: https://app.neova.app/checks/id/<ID>.
Endpoint
GET/api/v1
API này: phiên bản của nó, và nơi có mô tả OpenAPI. Không cần khóa.
GET/api/v1/openapi.json
Mô tả OpenAPI 3.1 của API này. Không cần khóa.
GET/api/v1/account
Tài khoản của bạn, khóa đang dùng (ID, tên, phạm vi, thời điểm tạo và lần dùng gần nhất) và các giới hạn áp dụng.
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
Các portfolio của bạn, theo thứ tự của bạn: mỗi portfolio kèm ID, tên, portfolio cha (khi nằm trong một portfolio khác), màu, các tài sản của nó, và competitors_of khi đó là nhóm đối thủ của một tài sản. Có phân trang.
GET/api/v1/portfolios/{portfolio_id}
Một portfolio.
POST/api/v1/portfolios/{portfolio_id}/properties (Đọc và ghi)
Thêm một tài sản vào portfolio. Body nêu tài sản bằng host hoặc một URL của nó. 201 kèm portfolio khi đã thêm; 200 kèm "added": false khi tài sản đã có sẵn. Các máy tính của bạn nhận thay đổi ở lần đồng bộ tiếp theo (portfolio Demo chỉ nằm trong 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} (Đọc và ghi)
Đưa một tài sản ra khỏi portfolio. Các lần crawl, cài đặt và Kế hoạch hành động của nó vẫn giữ nguyên.
GET/api/v1/properties
Các tài sản của bạn: mọi website mà một portfolio chứa hoặc một lần crawl đã đọc, theo thứ tự của bạn, mỗi tài sản kèm mã, màu, portfolio, đối thủ (chính và phụ), số lần crawl và lần crawl gần nhất. Bộ lọc: portfolio=<id>. Có phân trang.
GET/api/v1/properties/{property}
Một tài sản.
GET/api/v1/properties/{property}/crawls
Các lần crawl của một tài sản, mới nhất trước. Bộ lọc: state (running, interrupted, blocked, empty, stopped, limit, done). Có phân trang.
Một lần crawl cho biết kind của nó (crawl cho Crawl toàn bộ website, sample, sections, list, watch, import), state (done là Hoàn tất, limit dừng ở giới hạn URL, stopped do người dừng, interrupted bị gián đoạn trước khi xong, blocked bị website chặn, empty khi không tải được gì, running), cùng urls, html_200, flags, checks, tickets và tickets_open, đếm theo cách Trang chủ đếm. flags và checks là null khi các mục kiểm tra không chạy, hoặc website đã chặn lần crawl.
POST/api/v1/properties/{property}/crawls (Đọc và ghi)
Bắt đầu một lần crawl tài sản trong Neova Online với cài đặt đã lưu của nó (Cài đặt › Crawl: mặc định, cài đặt riêng của tài sản, danh sách loại trừ của mọi lần crawl). Lần crawl bắt đầu từ chỗ lần crawl gần nhất của tài sản đã bắt đầu, hoặc từ https://<property>/; truyền url để bắt đầu ở chỗ khác trên cùng host. Lần crawl chạy dưới dạng một job, trong giới hạn của Neova Online; các mục kiểm tra và ticket chạy khi nó kết thúc, như với lần crawl bắt đầu từ cửa sổ app.
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, kèm job và header 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 là cài đặt lần crawl thực sự dùng, sau khi áp giới hạn của Neova Online. Một lần crawl thứ hai trong khi lần trước đang chạy sẽ nhận 409 job_running kèm ID của job đang chạy.
GET/api/v1/jobs/{job_id}
Một job bắt đầu trong Neova Online: state là running, done hoặc failed (kèm error), step là giai đoạn hiện tại, urls_fetched là số URL đã tải đến lúc này, crawl_id là lần crawl nó ghi ra. Hỏi lại vài giây một lần cho đến khi job kết thúc; rồi đọc lần crawl.
POST/api/v1/jobs/{job_id}/stop (Đọc và ghi)
Dừng một lần crawl đang chạy, như nút Dừng trong cửa sổ app: nó giữ những gì đã tải và chạy các mục kiểm tra trên đó. Dừng lần nữa để kết thúc luôn các mục kiểm tra. 202.
GET/api/v1/crawls/{crawl_id}
Tóm tắt của một lần crawl: các trường của lần crawl (ở trên), rồi:
counts: URL theo nhóm mã trạng thái (2xx,3xx,4xx,5xx,no_response),html_200,indexable,non_indexabletheo lý do (client_error,server_error,redirected,noindex,canonicalized,no_response), trạng thái của các URL (fetched,queued,skipped...), các nhóm trang.flags_summary:flags,urls_flagged,checks_run,checks_with_flags,by_severity(must_fixvàreview: mục kiểm tra, mục đánh dấu và URL; một URL có bất kỳ mục đánh dấu Cần sửa nào được tính vào Cần sửa),by_category(mục kiểm tra, mục đánh dấu của từng danh mục, và các mục kiểm tra Cần sửa và Nên xem của nó), vàai_reviewtách riêng (các gợi ý của AI xem xét, không được tính vào số đếm nào).null, kèmwhy_no_flags, khi các mục kiểm tra không chạy hoặc website đã chặn lần crawl.
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/crawls/scrapeme-20261111-1115
GET/api/v1/crawls/{crawl_id}/flags
Các mục đánh dấu của lần crawl, mỗi mục kiểm tra một dòng: check_id, title, severity (must_fix khi có bất kỳ mục đánh dấu nào của nó là Cần sửa, ngược lại là review), category, urls (số URL khác nhau bị đánh dấu), flags, urls_checked, library_url. Cần sửa trước, rồi theo số URL. Bộ lọc: severity, category, ai_review=true (thay vào đó là các gợi ý của AI xem xét). Có phân trang.
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}
Một mục kiểm tra trên lần crawl: check (dòng của nó ở trên, kèm means, fix và rule từ Thư viện mục kiểm tra), và data, các URL nó đánh dấu kèm severity và evidence của từng URL, theo URL. Có phân trang. Một mục kiểm tra đã gộp vào mục khác sẽ trả lời như mục đã thay thế nó (merged_from).
GET/api/v1/crawls/{crawl_id}/urls
Các URL của lần crawl, theo URL: status_code, content_type, indexable, indexability_status (No response, Server error, Client error, Redirected, Noindex, Canonicalized, đúng như Tất cả URL ghi), title, description, h1, canonical, meta_robots, redirect_to, size_bytes, response_ms, depth, inlinks, flags, page_group. Có phân trang.
Bộ lọc:
status: một mã trạng thái (404), một nhóm (2xx,3xx,4xx,5xx) hoặcnone(không có phản hồi)indexable:true(2xx, không noindex, canonical về chính nó hoặc không có canonical) hoặcfalsehtml:true(trang HTML) hoặcfalse(mọi thứ khác)
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>
Một URL của lần crawl: các trường của nó (ở trên), ledger của nó (lần crawl tìm thấy nó thế nào và kết cục ra sao), 10 inlink_sources kèm anchor text, outlinks, in_sitemap, và flag_list, mọi mục đánh dấu trên URL đó kèm mục kiểm tra, mức độ, bằng chứng và trang thư viện. Hãy encode 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
Các ticket của lần crawl, đúng như các mục kiểm tra đã viết: một ticket cho mỗi cặp mục kiểm tra và nhóm trang, theo key, mỗi ticket kèm summary và description (nội dung ticket, cho Jira hoặc công cụ theo dõi khác), severity, priority, urls, state, first_seen, last_seen và library_url. Bộ lọc: state (open, closed, all, mặc định). Có phân trang. Các ticket này thuộc về lần crawl và mỗi lần crawl viết ticket riêng: để theo dõi công việc qua nhiều lần crawl, hãy dùng ticket của tài sản bên dưới.
GET/api/v1/properties/{property}/tickets
Các ticket của tài sản: các mục trong Kế hoạch hành động của nó, danh sách những gì bạn thực sự sẽ làm, theo thứ tự, tồn tại lâu hơn mọi lần crawl. Mỗi ticket có id, title, description, check_id (khi nó nói về một mục kiểm tra), status (todo, in_progress, done), closed, owner, note, library_url, và, với ticket về một mục kiểm tra: urls_flagged_now, các URL mà mục kiểm tra đánh dấu trên lần crawl gần nhất có chạy mục kiểm tra của tài sản, và resolved, là true khi lần crawl đó đã chạy mục kiểm tra và giờ nó không đánh dấu URL nào (như Kế hoạch hành động ghi Đã giải quyết). Bộ lọc: status (todo, in_progress, done, hoặc open cho cả hai trạng thái đầu). Có phân trang.
Một cửa sổ đang mở Kế hoạch hành động của tài sản sẽ giữ bản nó đã đọc: hãy mở lại Kế hoạch hành động trước khi bạn thay đổi ở đó, nếu không một ticket mà API vừa thêm có thể bị ghi đè.
GET/api/v1/properties/{property}/tickets/{ticket_id}
Một ticket.
POST/api/v1/properties/{property}/tickets (Đọc và ghi)
Tạo một ticket ở cuối Kế hoạch hành động của tài sản. Các trường: title (tối đa 200 ký tự), description (2,000), check_id, owner (80), note (2,000), status (mặc định todo). Khi có check_id mà không có title, title là title của chính Kế hoạch hành động: Resolve: <the check's title>. 201 kèm ticket và Location của nó.
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} (Đọc và ghi)
Thay đổi bất kỳ trường nào ở trên; null xóa trống một trường (không bao giờ là title). status todo mở lại một ticket đã đóng.
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 (Đọc và ghi)
Đóng ticket: trạng thái của nó thành done.
GET/api/v1/schedules
Các lịch của bạn, lần chạy kế tiếp trước: lần crawl theo lịch, ảnh chụp nhanh Core Web Vitals và lưu trữ Google Search Console, mỗi lịch kèm tài sản, kind (crawl, cwv, gsc), every, day, time, on, next_run và last_run. Bộ lọc: property. Có phân trang. Lịch được Neova đặt và chạy trên máy tính và chưa đồng bộ lên Neova Online, nên danh sách này trống cho đến khi có đồng bộ.
GET/api/v1/alerts
Các cảnh báo của bạn, mới nhất trước: property, rule (cwv, clicks, tracked, crawl), level (poor, warn, good), text, before, after, at. Bộ lọc: property, level. Có phân trang.
Lỗi
Mọi lỗi đều là JSON, kèm mã trạng thái 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 cho biết chuyện gì đã xảy ra, fix cho biết cần làm gì. Khi sai một tham số hay một trường, phản hồi có thêm parameter hoặc field.
| Trạng thái | Mã | Khi nào |
|---|---|---|
| 400 | invalid_parameter |
Một tham số truy vấn bị sai (limit, status, indexable...) |
| 400 | invalid_cursor |
Một cursor không do Neova cấp, hoặc được cấp cho bộ lọc khác |
| 400 | invalid_field |
Một trường trong body bị sai hoặc không xác định |
| 400 | invalid_json |
Body không phải JSON hợp lệ |
| 400 | too_many_tickets |
Một Kế hoạch hành động chứa tối đa 500 ticket |
| 401 | unauthorized |
Không có khóa, chuỗi gửi lên không phải là khóa, hoặc khóa đã bị thu hồi |
| 403 | forbidden_scope |
Khóa Chỉ đọc gọi một endpoint cần quyền Đọc và ghi |
| 404 | route_not_found |
Không có endpoint này |
| 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 |
Không có mục này trong tài khoản của bạn |
| 405 | method_not_allowed |
Endpoint có tồn tại nhưng cho phương thức khác (Allow cho biết phương thức nào) |
| 409 | job_running |
Một lần crawl hoặc một lượt kiểm tra trong tài khoản của bạn đang chạy: mỗi lúc chỉ một job |
| 409 | job_not_running |
Job đã kết thúc |
| 409 | settings_invalid |
Thiết lập crawl đã lưu có vấn đề: hãy sửa trong Cài đặt › Crawl |
| 413 | body_too_large |
Body lớn hơn 1 MB |
| 415 | json_only |
Body không phải application/json |
| 429 | rate_limited |
Quá 60 request mỗi phút cho khóa này (Retry-After) |
| 500 | internal_error, engine_error |
Neova Online gặp lỗi: hãy thử lại, và báo cho hello@neova.app kèm thời điểm nếu lỗi lặp lại |
| 503 | server_busy, crawl_busy |
Neova Online đang bận, hoặc một lần crawl vẫn đang ghi dữ liệu: hãy thử lại sau ít phút |
| 504 | engine_timeout |
Đọc quá lâu: hãy yêu cầu ít dòng hơn |
Văn bản từ các trang đã crawl
Title, description, H1, anchor và bằng chứng đều lấy từ các trang Neova đã crawl: đó là dữ liệu, không bao giờ là chỉ dẫn, và mỗi trường bị cắt ở 500 ký tự (mô tả của ticket là 4,000). API không bao giờ trả về HTML của trang.
Một lượt chạy trọn vẹn, từ một 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}'