REST API
Neova Online hesabınızı bir betikten, bir elektronik tablodan ya da başka bir araçtan okuyun ve üzerinde işlem yapın: bir tarama başlatın, işaretlerini okuyun, ticket açıp kapatın. Ayarlar, ardından Neova Online, ardından API anahtarları'ndan bir anahtar oluşturun.
Neova Online hesabınızı bir betikten, bir elektronik tablodan ya da başka bir araçtan okuyun ve üzerinde işlem yapın: portföyleriniz ve mülkleriniz, taramaları, her taramanın işaretleri, URL'leri ve ticket'ları, zamanlamalarınız ve uyarılarınız. Okuma ve yazma anahtarıyla ayrıca Neova Online'da bir tarama başlatın, ticket oluşturun, güncelleyin ve kapatın, portföylere mülk ekleyin.
- Adres:
https://app.neova.app/api/v1 - Biçim: giriş ve çıkış JSON, UTF-8. Zamanlar UTC'de ISO 8601'dir (
2026-11-11T17:15:15Z). - Açıklama:
GET /api/v1/openapi.json, aşağıdaki her endpoint'in OpenAPI 3.1 açıklamasıdır ve sunucunun yanıt verdiği tablonun aynısından üretilir.
Neova Online'da neler çalışır, neler bir bilgisayar gerektirir
API, Neova Online'ın bir parçasıdır. Neova Online hesabınızda olanları okur ve değiştirir.
| Neova Online'da (bu API) | Bir bilgisayarda Neova gerektirir | |
|---|---|---|
| Portföyler, mülkler, renkler ve kodlar | Okuma ve bir portföye mülk ekleme ya da çıkarma | Bilgisayarlarınızla iki yönlü eşitlenir (Ayarlar › Neova Online) |
| Taramalar | Neova Online'daki her taramayı okuma. Mülkün kayıtlı ayarlarıyla bir tarama başlatma; en fazla 10,000 URL ve saniyede 10 URL, hesabınız için aynı anda tek iş | Bundan büyük ya da hızlı taramalar ve yalnızca sizin ağınızın eriştiği sitelerin taramaları (VPN arkasındaki bir staging sitesi, localhost). Bir bilgisayarda yapılan tarama, Neova Online'a girdiğinde API'ye ulaşır (Yeni Taramaları Yükle) |
| İşaretler, URL'ler, tarama ticket'ları | Okundu | |
| Bir mülkün ticket'ları (Eylem planı) | Okuma, oluşturma, güncelleme, kapatma | Neova Online'daki Eylem planı kendine aittir: henüz bir bilgisayarla eşitlenmez |
| Zamanlamalar | Neova Online'da olanları okuma | Bir bilgisayarda kurulur ve çalışır; henüz Neova Online ile eşitlenmez, bu yüzden bu liste bugün boş |
| Uyarılar | Neova Online'da olanları okuma | Neova Go'nun uyarıları bir bilgisayarda oluşur; Neova Online kendi kontrollerinin oluşturduklarını tutar |
| Diğer crawler'lardan içe aktarmalar, sunucu logları, yapay zeka incelemesi | Bir bilgisayarda |
Neova Online'ın sınırları (10,000 URL, saniyede 10 URL, aynı anda tek iş) bugünkü ayarlarıdır; GET /api/v1/account size uygulananları her zaman söyler.
Kimlik doğrulama
GET /api/v1 ve GET /api/v1/openapi.json dışındaki her istek bir API anahtarı taşır:
Authorization: Bearer neova_...
Ayarlar › Neova Online › API anahtarları'nda (Neova Online'da ya da Neova Online'a oturum açmış bir bilgisayardaki Neova'da) Anahtar oluştur… ile bir anahtar oluşturun:
- Anahtar adı: onu neyin kullanacağı, örneğin Looker Studio.
- Kapsam: Salt okunur bu sayfanın listelediği her şeyi okur ve hiçbir şeyi değiştirmez. Okuma ve yazma ayrıca tarama başlatır, ticket oluşturur, günceller ve kapatır ve portföylere mülk ekler.
- Neova Online Parolanız: her anahtar oluşturulduğunda sorulur.
Anahtar yalnızca bir kez, oluşturulduğunda gösterilir. Neova Online yalnızca parmak izini (SHA-256), adını, kapsamını, son 4 karakterini ve ne zaman oluşturulup en son kullanıldığını saklar. Kaybolan bir anahtar yeniden gösterilemez: iptal edin ve yenisini oluşturun. İptal et… bir anahtarı anında durdurur. Bir hesapta en fazla 20 anahtar olur.
Anahtarın yeri bir sunucu ya da betiktir, asla bir web sayfası değil: API hiçbir CORS başlığı göndermez, bu yüzden bir tarayıcının betiği yanıtlarını okuyamaz.
export NEOVA_KEY=neova_...
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/account
Sınırlar
- Anahtar başına dakikada 60 istek, son 60 saniye üzerinden sayılır. Her yanıt nerede olduğunuzu söyler:
X-RateLimit-Limit: bu anahtarın dakikalık istek sayısıX-RateLimit-Remaining: geçerli dakikada kalanX-RateLimit-Reset: bir isteğin ne zaman serbest kalacağı (Unix zamanı, saniye)- Sınırın üstünde:
Retry-After(saniye) verate_limitedhatasıyla429.
- Sayfalar: varsayılan 50 satır, en fazla 500 (
limit). - Taramalar: hesabınız için aynı anda tek iş (bir tarama ya da yeniden çalıştırılan kontroller), mülkün kayıtlı ayarları ne derse desin en fazla hesabın
max_urlsveurls_per_seconddeğerleri. - Gövdeler: en fazla 1 MB.
Listeler: sayfalar ve imleçler
Bir liste şöyle yanıt verir:
{"data": [...], "has_more": true, "next_cursor": "eyJvIjo1MCwiZiI6IjQ0MTM2ZmEzNWMyZSJ9", "total": 612}
Sonraki sayfayı cursor=<next_cursor> ve aynı filtrelerle isteyin. Başka filtreler için verilmiş bir imleç reddedilir (invalid_cursor). total, filtrelerle eşleşen her satırı sayar. URL'ler, bir kontrolün işaretlediği URL'ler ve bir taramanın ticket'ları URL'lerine ya da anahtarlarına göre sayfalanır, böylece bir sayfa asla bir satırı tekrarlamaz ya da atlamaz.
Kimlikler
| Nesne | ID | Örnek |
|---|---|---|
| Portföy | kimliği | demo |
| Mülk | host'u; www. atılır, port korunur |
scrapeme.live, localhost:8080 |
| Tara | klasör adı | scrapeme-20261111-1115 |
| Kontrol | kontrol kütüphanesindeki kimliği | SE-001 |
| Tarama ticket'ı | anahtarı: kontrol ve sayfa grubu | SE-001|single |
| Ticket (Eylem planı) | kimliği | p00001 |
| İş | bir sayı; iş bittikten sonra bir saat saklanır ve Neova Online yeniden başladığında unutulur (tarama kalır) | 12 |
| Zamanlama, uyarı | kimlikleri |
Her kontrol, kontrol kütüphanesindeki sayfası olan library_url'yi taşır: https://app.neova.app/checks/id/<ID>.
Endpoint'ler
GET/api/v1
Bu API: sürümü ve OpenAPI açıklamasının nerede olduğu. Anahtar gerekmez.
GET/api/v1/openapi.json
Bu API'nin OpenAPI 3.1 açıklaması. Anahtar gerekmez.
GET/api/v1/account
Hesabınız, kullanılan anahtar (kimliği, adı, kapsamı, ne zaman oluşturulup en son kullanıldığı) ve uygulanan sınırlar.
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
Portföyleriniz, sizin sıranızla: her biri kimliği, adı, üst portföyü (başka bir portföyün içindeki portföy), rengi, mülkleri ve bir mülkün rakiplerini tutuyorsa competitors_of ile. Sayfalı.
GET/api/v1/portfolios/{portfolio_id}
Tek bir portföy.
POST/api/v1/portfolios/{portfolio_id}/properties (Okuma ve yazma)
Bir portföye mülk ekler. Gövde onu host'uyla ya da ona ait bir URL'yle belirtir. Eklendiyse portföyle birlikte 201; zaten oradaysa "added": false ile 200. Bilgisayarlarınız değişikliği bir sonraki eşitlemede alır (Demo portföyü Neova Online'da kalır).
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} (Okuma ve yazma)
Bir mülkü portföyden çıkarır. Taramaları, ayarları ve Eylem planı kalır.
GET/api/v1/properties
Mülkleriniz: bir portföyün tuttuğu ya da bir taramanın okuduğu her site, sizin sıranızla; her biri kodu, rengi, portföyleri, rakipleri (birincil ve ikincil), tarama sayısı ve son taramasıyla. Filtre: portfolio=<id>. Sayfalı.
GET/api/v1/properties/{property}
Tek bir mülk.
GET/api/v1/properties/{property}/crawls
Bir mülkün taramaları, en yenisi önce. Filtre: state (running, interrupted, blocked, empty, stopped, limit, done). Sayfalı.
Bir tarama şunları söyler: kind (Tüm site taraması için crawl, sample, sections, list, watch, import), state (done Tamamlandı demek, limit URL sınırında durdu, stopped bir kişi tarafından durduruldu, interrupted bitmeden kesildi, blocked site tarafından engellendi, empty hiçbir şey alınamadığında, running), urls, html_200, flags, checks, tickets ve tickets_open; Ana sayfa nasıl sayıyorsa öyle sayılır. Kontroller çalışmadığında ya da site taramayı engellediğinde flags ve checks null olur.
POST/api/v1/properties/{property}/crawls (Okuma ve yazma)
Mülkün bir taramasını kayıtlı ayarlarıyla Neova Online'da başlatır (Ayarlar › Tarama: varsayılanlar, mülkün kendi ayarları, her taramanın hariç tutma listesi). Mülkün son taramasının başladığı yerden ya da https://<property>/ adresinden başlar; aynı host'ta başka bir yerden başlamak için url verin. Tarama, Neova Online'ın sınırları altında bir iş olarak çalışır; kontroller ve ticket'lar, pencereden başlatılan bir taramada olduğu gibi tarama bitince çalışır.
curl -X POST -H "Authorization: Bearer $NEOVA_KEY" -H "Content-Type: application/json" -d '{}' \
https://app.neova.app/api/v1/properties/example.com/crawls
İş ve bir Location: /api/v1/jobs/<id> başlığıyla 202:
{"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'ın sınırları uygulandıktan sonra taramanın kullandığı ayarlardır. Biri çalışırken ikinci bir tarama, çalışan işin kimliğiyle 409 job_running yanıtı verir.
GET/api/v1/jobs/{job_id}
Neova Online'da başlatılan bir iş: state running, done ya da failed (error ile) olur, step bulunduğu aşama, urls_fetched şimdiye kadar alınan URL'ler, crawl_id yazdığı tarama. Bitene kadar birkaç saniyede bir sorun; ardından taramayı okuyun.
POST/api/v1/jobs/{job_id}/stop (Okuma ve yazma)
Pencerede Durdur'un yaptığı gibi çalışan bir taramayı durdurur: aldıklarını saklar ve kontrollerini onlar üzerinde çalıştırır. Kontrolleri de bitirmek için yeniden durdurun. 202.
GET/api/v1/crawls/{crawl_id}
Bir taramanın özeti: taramanın alanları (yukarıda), ardından:
counts: durum kodu sınıfına göre URL'ler (2xx,3xx,4xx,5xx,no_response),html_200,indexable, nedene görenon_indexable(client_error,server_error,redirected,noindex,canonicalized,no_response), URL'lerin durumları (fetched,queued,skipped...), sayfa grupları.flags_summary:flags,urls_flagged,checks_run,checks_with_flags,by_severity(must_fixvereview: kontroller, işaretler ve URL'ler; herhangi bir Düzeltilmeli işareti olan URL Düzeltilmeli altında sayılır),by_category(her kategorinin kontrolleri, işaretleri ve Düzeltilmeli ve İncelenmeli kontrolleri) ve ayrıcaai_review(yapay zeka incelemesinin önerileri; hiçbir sayıma dahil değildir). Kontroller çalışmadığında ya da site taramayı engellediğindewhy_no_flagsile birliktenull.
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/crawls/scrapeme-20261111-1115
GET/api/v1/crawls/{crawl_id}/flags
Taramanın işaretleri, kontrol başına bir satır: check_id, title, severity (işaretlerinden herhangi biri Düzeltilmeli ise must_fix, değilse review), category, urls (işaretlenen farklı URL'ler), flags, urls_checked, library_url. Önce Düzeltilmeli, sonra URL sayısına göre. Filtreler: severity, category, ai_review=true (bunun yerine yapay zeka incelemesinin önerileri). Sayfalı.
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}
Taramadaki tek bir kontrol: check (yukarıdaki satırı, kontrol kütüphanesinden means, fix ve rule ile) ve data, işaretlediği URL'ler, her birinin severity ve evidence değeriyle, URL'ye göre. Sayfalı. Başka bir kontrolle birleştirilmiş bir kontrol, onun yerini alan kontrol olarak yanıt verir (merged_from).
GET/api/v1/crawls/{crawl_id}/urls
Taramanın URL'leri, URL'ye göre: status_code, content_type, indexable, indexability_status (No response, Server error, Client error, Redirected, Noindex, Canonicalized, Tüm URL'ler'in dediği gibi), title, description, h1, canonical, meta_robots, redirect_to, size_bytes, response_ms, depth, inlinks, flags, page_group. Sayfalı.
Filtreler:
status: bir durum kodu (404), bir sınıf (2xx,3xx,4xx,5xx) ya danone(yanıt yok)indexable:true(2xx, noindex yok, canonical kendisine ya da yok) veyafalsehtml:true(HTML sayfaları) veyafalse(diğer her şey)
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>
Taramanın tek bir URL'si: alanları (yukarıda), ledger (taramanın onu nasıl bulduğu ve akıbeti), anchor'larıyla 10 inlink_sources, outlinks, in_sitemap ve flag_list, üzerindeki her işaret kontrolü, önem derecesi, kanıtı ve kütüphane sayfasıyla. URL'yi kodlayın:
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
Taramanın ticket'ları, kontrollerinin yazdığı haliyle: kontrol ve sayfa grubu başına bir tane, anahtara göre; her biri summary ve description (ticket'ın Jira ya da başka bir takip aracı için metni), severity, priority, urls, state, first_seen, last_seen ve library_url ile. Filtre: state (open, closed, all, varsayılan). Sayfalı. Bu ticket'lar taramaya aittir ve her tarama kendininkini yazar: işi taramalar boyunca takip etmek için aşağıdaki mülk ticket'larını kullanın.
GET/api/v1/properties/{property}/tickets
Mülkün ticket'ları: Eylem planının öğeleri, gerçekten yapacaklarınızın sıralı listesi; her taramadan uzun yaşar. Her birinde id, title, description, check_id (bir kontrolle ilgiliyse), status (todo, in_progress, done), closed, owner, note, library_url ve bir kontrolle ilgili ticket için: urls_flagged_now, kontrolün mülkün kontrolleri çalışmış son taramasında işaretlediği URL'ler, ve resolved, o tarama kontrolü çalıştırdıysa ve kontrol artık hiçbir URL'yi işaretlemiyorsa true (Eylem planının Çözüldü demesi gibi). Filtre: status (todo, in_progress, done ya da ilk ikisi için open). Sayfalı.
Mülkün Eylem planı açık olan bir pencere okuduğu kopyayı tutar: orada değişiklik yapmadan önce Eylem planını yeniden açın, yoksa API'nin o arada eklediği bir ticket'ın üzerine yazılabilir.
GET/api/v1/properties/{property}/tickets/{ticket_id}
Tek bir ticket.
POST/api/v1/properties/{property}/tickets (Okuma ve yazma)
Mülkün Eylem planının sonuna bir ticket ekler. Alanlar: title (en fazla 200 karakter), description (2,000), check_id, owner (80), note (2,000), status (varsayılan todo). check_id verilip başlık verilmezse başlık Eylem planının kendi başlığıdır: Resolve: <the check's title>. Ticket ve Location ile 201.
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} (Okuma ve yazma)
Yukarıdaki alanlardan herhangi birini değiştirir; null birini boşaltır (başlık hariç). status todo, kapalı bir ticket'ı yeniden açar.
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 (Okuma ve yazma)
Ticket'ı kapatır: durumu done olur.
GET/api/v1/schedules
Zamanlamalarınız, sıradaki çalıştırma önce: zamanlanmış taramalar, Core Web Vitals anlık görüntüleri ve Google Search Console arşivleri; her biri mülkü, kind (crawl, cwv, gsc), every, day, time, on, next_run ve last_run ile. Filtre: property. Sayfalı. Zamanlamalar bir bilgisayardaki Neova tarafından kurulur ve çalıştırılır ve henüz Neova Online ile eşitlenmez, bu yüzden bu liste eşitlenene kadar boştur.
GET/api/v1/alerts
Uyarılarınız, en yenisi önce: property, rule (cwv, clicks, tracked, crawl), level (poor, warn, good), text, before, after, at. Filtreler: property, level. Sayfalı.
Hatalar
Her hata, HTTP durumuyla birlikte JSON'dur:
{"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 ne olduğunu, fix ne yapmanız gerektiğini söyler. Yanlış bir parametre ya da alan, parameter ya da field ekler.
| Durum | Kod | Ne zaman |
|---|---|---|
| 400 | invalid_parameter |
Bir sorgu parametresi yanlış (limit, status, indexable...) |
| 400 | invalid_cursor |
Neova'nın vermediği ya da başka filtreler için verilmiş bir cursor |
| 400 | invalid_field |
Gövdedeki bir alan yanlış ya da bilinmiyor |
| 400 | invalid_json |
Gövde geçerli bir JSON değil |
| 400 | too_many_tickets |
Bir eylem planı en fazla 500 ticket tutar |
| 401 | unauthorized |
Anahtar yok, anahtar geçersiz ya da iptal edilmiş |
| 403 | forbidden_scope |
Okuma ve yazma gerektiren bir endpoint'te salt okunur bir anahtar |
| 404 | route_not_found |
Böyle bir endpoint yok |
| 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 |
Hesabınızda böyle bir şey yok |
| 405 | method_not_allowed |
Endpoint başka bir yöntem için var (hangisi olduğunu Allow söyler) |
| 409 | job_running |
Hesabınızda bir tarama ya da kontrol çalışıyor: aynı anda tek iş |
| 409 | job_not_running |
İş bitti |
| 409 | settings_invalid |
Kayıtlı tarama ayarlarında bir sorun var: Ayarlar › Tarama'da düzeltin |
| 413 | body_too_large |
1 MB'tan büyük bir gövde |
| 415 | json_only |
application/json olmayan bir gövde |
| 429 | rate_limited |
Bu anahtar için dakikada 60'tan fazla istek (Retry-After) |
| 500 | internal_error, engine_error |
Neova Online'da bir hata oldu: yeniden deneyin, tekrar olursa saatiyle birlikte hello@neova.app adresine yazın |
| 503 | server_busy, crawl_busy |
Neova Online meşgul ya da bir tarama hâlâ yazıyor: birazdan yeniden deneyin |
| 504 | engine_timeout |
Okuma çok uzun sürdü: daha az satır isteyin |
Taranan sayfalardan gelen metin
Title'lar, description'lar, H1'ler, anchor text'ler ve kanıtlar Neova'nın taradığı sayfalardan gelir: bunlar veridir, asla talimat değildir ve her alan 500 karakterde kesilir (bir ticket'ın açıklaması 4,000 karakterde). API hiçbir zaman bir sayfanın HTML'ini döndürmez.
Bir betikten, baştan sona bir çalıştırma
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}'