REST API
Baca akun Neova Online Anda dari skrip, spreadsheet atau tool lain, dan bertindak di dalamnya: memulai crawl, membaca tandanya, membuka dan menutup tiket. Buat kunci di Pengaturan, lalu Neova Online, lalu Kunci API.
Baca akun Neova Online Anda dari skrip, spreadsheet atau tool lain, dan bertindak di dalamnya: portofolio dan properti Anda, crawl-nya, tanda, URL dan tiket setiap crawl, jadwal dan peringatan Anda. Dengan kunci Baca-tulis, Anda juga bisa memulai crawl di Neova Online, membuat, memperbarui dan menutup tiket, serta menambahkan properti ke portofolio.
- Alamat:
https://app.neova.app/api/v1 - Format: JSON masuk dan keluar, UTF-8. Waktu dalam ISO 8601 di UTC (
2026-11-11T17:15:15Z). - Deskripsi:
GET /api/v1/openapi.jsonadalah deskripsi OpenAPI 3.1 dari setiap endpoint di bawah, dibuat dari tabel yang sama yang dipakai server untuk menjawab.
Apa yang berjalan di Neova Online, dan apa yang butuh komputer
API ini bagian dari Neova Online. API membaca dan mengubah isi akun Neova Online Anda.
| Di Neova Online (API ini) | Butuh Neova di komputer | |
|---|---|---|
| Portofolio, properti, warna dan kode | Baca, serta tambah atau hapus properti di portofolio | Tersinkron dua arah dengan komputer Anda (Pengaturan › Neova Online) |
| Crawl | Baca setiap crawl di Neova Online. Mulai crawl dengan pengaturan tersimpan properti, paling banyak 10,000 URL dan 10 URL per detik, satu job sekaligus untuk akun Anda | Crawl yang lebih besar atau lebih cepat dari itu, dan crawl situs yang hanya bisa dijangkau jaringan Anda (situs staging di balik VPN, localhost). Crawl yang dibuat di komputer bisa diakses API setelah ada di Neova Online (Unggah Crawl Baru) |
| Tanda, URL, tiket crawl | Sudah dibaca | |
| Tiket properti (Rencana tindakannya) | Baca, buat, perbarui, tutup | Rencana tindakan di Neova Online berdiri sendiri: belum tersinkron ke komputer |
| Jadwal | Baca apa yang ada di Neova Online | Diatur dan dijalankan di komputer; belum tersinkron ke Neova Online, jadi daftar ini kosong saat ini |
| Peringatan | Baca apa yang ada di Neova Online | Peringatan Neova Go dibuat di komputer; Neova Online menyimpan peringatan yang dibuat oleh pemeriksaannya sendiri |
| Impor dari crawler lain, log server, tinjauan AI | Di komputer |
Batas Neova Online (10,000 URL, 10 URL per detik, satu job sekaligus) adalah pengaturannya saat ini; GET /api/v1/account selalu menyebutkan batas yang berlaku untuk Anda.
Autentikasi
Setiap permintaan kecuali GET /api/v1 dan GET /api/v1/openapi.json membawa kunci API:
Authorization: Bearer neova_...
Buat kunci di Pengaturan › Neova Online › Kunci API (di Neova Online, atau di Neova di komputer yang sudah masuk ke Neova Online), dengan Buat kunci…:
- Nama kunci: apa yang akan memakainya, misalnya Looker Studio.
- Cakupan: Hanya baca membaca semua yang tercantum di halaman ini dan tidak mengubah apa pun. Baca-tulis juga memulai crawl, membuat, memperbarui dan menutup tiket, serta menambahkan properti ke portofolio.
- Kata Sandi Neova Online Anda: diminta setiap kali kunci dibuat.
Kunci hanya ditampilkan sekali, saat dibuat. Neova Online hanya menyimpan sidik jarinya (SHA-256), namanya, cakupannya, 4 karakter terakhirnya dan kapan kunci dibuat dan terakhir dipakai. Kunci yang hilang tidak bisa ditampilkan lagi: cabut lalu buat yang baru. Cabut… langsung menghentikan sebuah kunci. Satu akun menyimpan paling banyak 20 kunci.
Kunci tempatnya di server atau di skrip, tidak pernah di halaman web: API tidak mengirim header CORS, jadi skrip di browser tidak bisa membaca jawabannya.
export NEOVA_KEY=neova_...
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/account
Batas
- 60 permintaan per menit per kunci, dihitung selama 60 detik terakhir. Setiap jawaban menyebutkan posisi Anda:
X-RateLimit-Limit: jumlah permintaan per menit untuk kunci iniX-RateLimit-Remaining: sisa jatah di menit berjalanX-RateLimit-Reset: kapan jatah permintaan tersedia lagi (waktu Unix, detik)- Melewati batas:
429denganRetry-After(detik) dan errorrate_limited.
- Halaman: 50 baris secara default, paling banyak 500 (
limit). - Crawl: satu job sekaligus untuk akun Anda (sebuah crawl, atau pemeriksaan yang dijalankan ulang), paling banyak
max_urlsdanurls_per_secondakun, apa pun isi pengaturan tersimpan properti. - Body: paling besar 1 MB.
Daftar: halaman dan cursor
Sebuah daftar menjawab:
{"data": [...], "has_more": true, "next_cursor": "eyJvIjo1MCwiZiI6IjQ0MTM2ZmEzNWMyZSJ9", "total": 612}
Minta halaman berikutnya dengan cursor=<next_cursor> dan filter yang sama. Cursor yang diberikan untuk filter lain ditolak (invalid_cursor). total menghitung setiap baris yang cocok dengan filter. URL, URL yang ditandai sebuah pemeriksaan dan tiket sebuah crawl dipaginasi menurut URL atau key-nya, jadi sebuah halaman tidak pernah mengulang atau melewatkan baris.
ID
| Objek | ID | Contoh |
|---|---|---|
| Portofolio | ID-nya | demo |
| Properti | host-nya, tanpa www., port tetap dipertahankan |
scrapeme.live, localhost:8080 |
| Crawl | nama foldernya | scrapeme-20261111-1115 |
| Pemeriksaan | ID-nya di pustaka pemeriksaan | SE-001 |
| Tiket crawl | key-nya: pemeriksaan dan grup halaman | SE-001|single |
| Tiket (Rencana tindakan) | ID-nya | p00001 |
| Job | sebuah angka, disimpan satu jam setelah job selesai dan dilupakan saat Neova Online di-restart (crawl-nya tetap ada) | 12 |
| Jadwal, peringatan | ID-nya |
Setiap pemeriksaan membawa library_url, halamannya di pustaka pemeriksaan: https://app.neova.app/checks/id/<ID>.
Endpoint
GET/api/v1
API ini: versinya, dan lokasi deskripsi OpenAPI-nya. Tidak perlu kunci.
GET/api/v1/openapi.json
Deskripsi OpenAPI 3.1 dari API ini. Tidak perlu kunci.
GET/api/v1/account
Akun Anda, kunci yang dipakai (ID, nama, cakupan, kapan dibuat dan terakhir dipakai) dan batas yang berlaku.
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
Portofolio Anda, dalam urutan Anda: masing-masing dengan ID, nama, induk (portofolio di dalam portofolio lain), warna, propertinya, dan competitors_of jika portofolio itu berisi pesaing sebuah properti. Dipaginasi.
GET/api/v1/portfolios/{portfolio_id}
Satu portofolio.
POST/api/v1/portfolios/{portfolio_id}/properties (Baca-tulis)
Menambahkan properti ke portofolio. Body menyebut properti lewat host-nya atau salah satu URL-nya. 201 dengan portofolionya jika berhasil ditambahkan; 200 dengan "added": false jika sudah ada. Komputer Anda menerima perubahan ini pada sinkronisasi berikutnya (portofolio Demo tetap di 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} (Baca-tulis)
Mengeluarkan properti dari portofolio. Crawl, pengaturan dan Rencana tindakannya tetap ada.
GET/api/v1/properties
Properti Anda: setiap situs yang ada di portofolio atau yang dibaca sebuah crawl, dalam urutan Anda, masing-masing dengan kode, warna, portofolio, pesaing (utama dan sekunder), jumlah crawl dan crawl terbarunya. Filter: portfolio=<id>. Dipaginasi.
GET/api/v1/properties/{property}
Satu properti.
GET/api/v1/properties/{property}/crawls
Crawl sebuah properti, yang terbaru lebih dulu. Filter: state (running, interrupted, blocked, empty, stopped, limit, done). Dipaginasi.
Sebuah crawl menyebutkan kind-nya (crawl untuk Crawl situs penuh, sample, sections, list, watch, import), state-nya (done berarti Selesai, limit berhenti di batas URL-nya, stopped dihentikan seseorang, interrupted terhenti sebelum selesai, blocked diblokir situs, empty jika tidak ada yang diambil, running), serta urls, html_200, flags, checks, tickets dan tickets_open, dihitung seperti di Beranda. flags dan checks bernilai null jika pemeriksaan tidak dijalankan, atau situs memblokir crawl.
POST/api/v1/properties/{property}/crawls (Baca-tulis)
Memulai crawl properti di Neova Online dengan pengaturan tersimpannya (Pengaturan › Crawl: default, pengaturan properti itu sendiri, daftar pengecualian setiap crawl). Crawl dimulai dari tempat crawl terbaru properti itu dimulai, atau dari https://<property>/; berikan url untuk memulai dari tempat lain di host yang sama. Crawl berjalan sebagai job, di bawah batas Neova Online; pemeriksaan dan tiket dijalankan saat crawl selesai, sama seperti crawl yang dimulai dari jendela aplikasi.
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, dengan job-nya dan 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 adalah pengaturan yang dipakai crawl, setelah batas Neova Online diterapkan. Crawl kedua saat satu crawl masih berjalan dijawab dengan 409 job_running beserta ID job yang sedang berjalan.
GET/api/v1/jobs/{job_id}
Job yang dimulai di Neova Online: state bernilai running, done atau failed (dengan error), step tahap yang sedang dijalani, urls_fetched jumlah URL yang sudah diambil, crawl_id crawl yang ditulisnya. Tanyakan setiap beberapa detik sampai selesai; lalu baca crawl-nya.
POST/api/v1/jobs/{job_id}/stop (Baca-tulis)
Menghentikan crawl yang sedang berjalan, seperti Hentikan di jendela aplikasi: apa yang sudah diambil tetap disimpan dan pemeriksaannya dijalankan. Hentikan lagi untuk mengakhiri pemeriksaannya juga. 202.
GET/api/v1/crawls/{crawl_id}
Ringkasan satu crawl: field crawl (di atas), lalu:
counts: URL per kelas kode status (2xx,3xx,4xx,5xx,no_response),html_200,indexable,non_indexablemenurut alasan (client_error,server_error,redirected,noindex,canonicalized,no_response), status URL (fetched,queued,skipped...), dan grup halaman.flags_summary:flags,urls_flagged,checks_run,checks_with_flags,by_severity(must_fixdanreview: pemeriksaan, tanda dan URL; URL dengan tanda Harus diperbaiki apa pun dihitung di bawah Harus diperbaiki),by_category(pemeriksaan dan tanda setiap kategori, serta pemeriksaan Harus diperbaiki dan Perlu dicek-nya), danai_reviewterpisah (saran tinjauan AI, yang tidak masuk hitungan mana pun).null, denganwhy_no_flags, jika pemeriksaan tidak dijalankan atau situs memblokir crawl.
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/crawls/scrapeme-20261111-1115
GET/api/v1/crawls/{crawl_id}/flags
Tanda crawl, satu baris per pemeriksaan: check_id, title, severity (must_fix jika salah satu tandanya Harus diperbaiki, selain itu review), category, urls (URL berbeda yang ditandai), flags, urls_checked, library_url. Harus diperbaiki lebih dulu, lalu menurut URL. Filter: severity, category, ai_review=true (saran tinjauan AI sebagai gantinya). Dipaginasi.
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}
Satu pemeriksaan pada crawl: check (barisnya di atas, dengan means, fix dan rule dari pustaka pemeriksaan), dan data, URL yang ditandainya beserta severity dan evidence masing-masing, menurut URL. Dipaginasi. Pemeriksaan yang digabung ke pemeriksaan lain menjawab sebagai pemeriksaan penggantinya (merged_from).
GET/api/v1/crawls/{crawl_id}/urls
URL crawl, menurut URL: status_code, content_type, indexable, indexability_status (No response, Server error, Client error, Redirected, Noindex, Canonicalized, seperti yang disebutkan Semua URL), title, description, h1, canonical, meta_robots, redirect_to, size_bytes, response_ms, depth, inlinks, flags, page_group. Dipaginasi.
Filter:
status: kode status (404), kelas (2xx,3xx,4xx,5xx) ataunone(tidak ada respons)indexable:true(2xx, tanpa noindex, canonical ke dirinya sendiri atau tidak ada) ataufalsehtml:true(halaman HTML) ataufalse(selain itu)
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>
Satu URL dari crawl: field-nya (di atas), ledger-nya (bagaimana crawl menemukannya dan apa yang terjadi padanya), 10 inlink_sources beserta anchor-nya, outlinks, in_sitemap, dan flag_list, setiap tanda pada URL itu dengan pemeriksaan, severity, bukti dan halaman pustakanya. Encode URL-nya:
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
Tiket crawl, seperti yang ditulis pemeriksaannya: satu per pemeriksaan dan grup halaman, menurut key, masing-masing dengan summary dan description (teks tiket, untuk Jira atau tracker lain), severity, priority, urls, state, first_seen, last_seen dan library_url. Filter: state (open, closed, all, default-nya). Dipaginasi. Tiket ini milik crawl dan setiap crawl menulis tiketnya sendiri: untuk melacak pekerjaan lintas crawl, gunakan tiket properti di bawah.
GET/api/v1/properties/{property}/tickets
Tiket properti: item Rencana tindakannya, daftar apa yang benar-benar akan Anda kerjakan, berurutan, yang bertahan melewati setiap crawl. Masing-masing punya id, title, description, check_id (jika terkait sebuah pemeriksaan), status (todo, in_progress, done), closed, owner, note, library_url, dan, untuk tiket terkait pemeriksaan: urls_flagged_now, URL yang ditandai pemeriksaan itu pada crawl terbaru properti yang menjalankan pemeriksaan, serta resolved, true jika crawl itu menjalankan pemeriksaan tersebut dan kini tidak menandai URL apa pun (seperti Rencana tindakan menyebutnya Terselesaikan). Filter: status (todo, in_progress, done, atau open untuk dua yang pertama). Dipaginasi.
Jendela yang sedang membuka Rencana tindakan properti menyimpan salinan yang dibacanya: buka Rencana tindakan lagi sebelum Anda mengubahnya di sana, atau tiket yang ditambahkan API sejak itu bisa tertimpa.
GET/api/v1/properties/{property}/tickets/{ticket_id}
Satu tiket.
POST/api/v1/properties/{property}/tickets (Baca-tulis)
Membuat tiket di akhir Rencana tindakan properti. Field: title (paling banyak 200 karakter), description (2,000), check_id, owner (80), note (2,000), status (todo secara default). Dengan check_id dan tanpa title, judulnya mengikuti Rencana tindakan: Resolve: <the check's title>. 201 dengan tiketnya dan Location-nya.
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} (Baca-tulis)
Mengubah field mana pun di atas; null mengosongkan satu field (kecuali title). status todo membuka kembali tiket yang sudah ditutup.
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 (Baca-tulis)
Menutup tiket: statusnya menjadi done.
GET/api/v1/schedules
Jadwal Anda, yang berjalan paling dekat lebih dulu: crawl terjadwal, snapshot Core Web Vitals dan arsip Google Search Console, masing-masing dengan propertinya, kind (crawl, cwv, gsc), every, day, time, on, next_run dan last_run. Filter: property. Dipaginasi. Jadwal diatur dan dijalankan oleh Neova di komputer dan belum tersinkron ke Neova Online, jadi daftar ini kosong sampai jadwal tersinkron.
GET/api/v1/alerts
Peringatan Anda, yang terbaru lebih dulu: property, rule (cwv, clicks, tracked, crawl), level (poor, warn, good), text, before, after, at. Filter: property, level. Dipaginasi.
Error
Setiap error berupa JSON, dengan 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 menjelaskan apa yang terjadi, fix apa yang perlu dilakukan. Parameter atau field yang salah menambahkan parameter atau field.
| Status | Kode | Kapan |
|---|---|---|
| 400 | invalid_parameter |
Parameter query salah (limit, status, indexable...) |
| 400 | invalid_cursor |
Cursor yang tidak diberikan Neova, atau diberikan untuk filter lain |
| 400 | invalid_field |
Field di body salah atau tidak dikenal |
| 400 | invalid_json |
Body bukan JSON yang valid |
| 400 | too_many_tickets |
Rencana tindakan memuat paling banyak 500 tiket |
| 401 | unauthorized |
Tanpa key, key yang tidak valid, atau key yang sudah dicabut |
| 403 | forbidden_scope |
Key Hanya baca di endpoint Baca-tulis |
| 404 | route_not_found |
Endpoint tidak ada |
| 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 |
Tidak ada di akun Anda |
| 405 | method_not_allowed |
Endpoint ada untuk method lain (Allow menyebutkan yang mana) |
| 409 | job_running |
Ada crawl atau pemeriksaan di akun Anda yang sedang berjalan: satu job dalam satu waktu |
| 409 | job_not_running |
Job sudah selesai |
| 409 | settings_invalid |
Pengaturan crawl yang tersimpan bermasalah: perbaiki di Pengaturan › Crawl |
| 413 | body_too_large |
Body lebih dari 1 MB |
| 415 | json_only |
Body yang bukan application/json |
| 429 | rate_limited |
Lebih dari 60 request per menit untuk key ini (Retry-After) |
| 500 | internal_error, engine_error |
Neova Online gagal: coba lagi, dan kabari hello@neova.app beserta waktunya jika terjadi lagi |
| 503 | server_busy, crawl_busy |
Neova Online sedang sibuk, atau sebuah crawl masih menulis data: coba lagi sebentar lagi |
| 504 | engine_timeout |
Pembacaan terlalu lama: minta baris yang lebih sedikit |
Teks dari halaman yang di-crawl
Judul, deskripsi, H1, anchor dan bukti berasal dari halaman yang di-crawl Neova: semuanya data, tidak pernah instruksi, dan setiap field dipotong di 500 karakter (deskripsi tiket di 4,000). API tidak pernah mengembalikan HTML halaman.
Satu proses utuh, dari skrip
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}'