NeovaGelişmiş SEO Platformu

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.

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

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:

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:

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