NeovaNền tảng SEO chuyên sâu

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.

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

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

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:

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:

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