NeovaPlatform SEO Tingkat Lanjut

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.

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

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

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:

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:

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