REST API
スクリプト、スプレッドシート、その他のツールから、Neova Onlineのアカウントを読み取って操作できます。クロールの開始、フラグの読み取り、チケットの作成とクローズなどです。キーは「設定」、「Neova Online」、「API キー」の順に開いて作成します。
スクリプト、スプレッドシート、その他のツールから、Neova Onlineのアカウントを読み取って操作できます。ポートフォリオとプロパティ、そのクロール、各クロールのフラグ・URL・チケット、スケジュールとアラート。読み書きキーなら、Neova Onlineでのクロールの開始、チケットの作成・更新・クローズ、ポートフォリオへのプロパティの追加もできます。
- アドレス:
https://app.neova.app/api/v1 - 形式:入出力ともJSON、UTF-8。時刻はUTCのISO 8601です (
2026-11-11T17:15:15Z)。 - 仕様:
GET /api/v1/openapi.jsonは、以下のすべてのエンドポイントのOpenAPI 3.1による仕様で、サーバーが応答に使うのと同じ表から作られています。
Neova Onlineで動くもの、パソコンが必要なもの
APIはNeova Onlineの一部です。Neova Onlineのアカウントにあるものを読み取り、変更します。
| Neova Online (このAPI) | パソコン上のNeovaが必要 | |
|---|---|---|
| ポートフォリオ、プロパティ、色、コード | 読み取り、ポートフォリオへのプロパティの追加と削除 | パソコンと双方向に同期 (設定 › Neova Online) |
| クロール | Neova Onlineのすべてのクロールの読み取り。プロパティの保存済み設定でクロールを開始 (最大10,000 URL、毎秒10 URL、アカウントごとに同時に1ジョブ) | それより大きいか速いクロール、そして社内ネットワークからしか届かないサイトのクロール (VPNの内側のステージングサイト、localhost)。パソコンで実行したクロールは、Neova Onlineに入るとAPIから読めます (新しいクロールをアップロード) |
| フラグ、URL、クロールのチケット | 読み込み済み | |
| プロパティのチケット (アクションプラン) | 読み取り、作成、更新、クローズ | Neova Onlineのアクションプランは独立しています。まだパソコンとは同期しません |
| スケジュール | Neova Onlineにあるものの読み取り | パソコンで設定・実行します。まだNeova Onlineと同期しないので、現在このリストは空です |
| アラート | Neova Onlineにあるものの読み取り | Neova Goのアラートはパソコンで出されます。Neova Onlineには、Neova Online自身のチェックで出たアラートがあります |
| ほかのクローラーからの読み込み、サーバーログ、AIレビュー | パソコンで |
Neova Onlineの制限 (10,000 URL、毎秒10 URL、同時に1ジョブ) は現時点の設定です。あなたに適用される制限は、GET /api/v1/account が常に返します。
認証
GET /api/v1 と GET /api/v1/openapi.json 以外のすべてのリクエストには、APIキーが必要です。
Authorization: Bearer neova_...
キーは設定 › Neova Online › API キー (Neova Online、またはNeova Onlineにサインインしたパソコン上のNeova) で、キーを作成…から作ります。
- キー名:何に使うか。例:Looker Studio。
- 範囲:読み取り専用は、このページに載っているものをすべて読み取り、何も変更しません。読み書きは、さらにクロールの開始、チケットの作成・更新・クローズ、ポートフォリオへのプロパティの追加ができます。
- Neova Online のパスワード:キーを作るたびに求められます。
キーが表示されるのは、作ったときの1回だけです。Neova Onlineが保存するのは、キーのフィンガープリント (SHA-256)、名前、範囲、末尾4文字、作成日時と最終使用日時だけです。なくしたキーは再表示できないので、取り消して新しく作ってください。取り消す…でキーはすぐに使えなくなります。1つのアカウントで持てるキーは最大20個です。
キーはサーバーやスクリプトに置くもので、Webページには決して置かないでください。APIはCORSヘッダーを返さないため、ブラウザのスクリプトからは応答を読めません。
export NEOVA_KEY=neova_...
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/account
上限
- キーごとに1分あたり60リクエストで、直近60秒間で数えます。すべての応答に現在の状況が含まれます。
X-RateLimit-Limit:このキーの1分あたりのリクエスト数X-RateLimit-Remaining:現在の1分間の残りX-RateLimit-Reset:次にリクエストが空く時刻 (Unix時間、秒)- 制限を超えると、
Retry-After(秒) 付きの429と、エラーrate_limitedが返ります。
- ページ:既定は50行、最大500行 (
limit)。 - クロール:アカウントごとに同時に1ジョブ (クロール、またはチェック項目の再実行)。プロパティの保存済み設定にかかわらず、アカウントの
max_urlsとurls_per_secondが上限です。 - 本文:最大1 MB。
リスト:ページとカーソル
リストの応答:
{"data": [...], "has_more": true, "next_cursor": "eyJvIjo1MCwiZiI6IjQ0MTM2ZmEzNWMyZSJ9", "total": 612}
次のページは cursor=<next_cursor> と同じフィルターで要求します。別のフィルターで発行されたカーソルは拒否されます (invalid_cursor)。total はフィルターに一致するすべての行を数えます。URL、チェック項目のフラグが立ったURL、クロールのチケットは、URLまたはキーの順にページ分けされるので、行が重複したり抜けたりすることはありません。
ID
| 対象 | ID | 例 |
|---|---|---|
| ポートフォリオ | そのID | demo |
| プロパティ | そのホスト名 (www. は除き、ポートは残す) |
scrapeme.live, localhost:8080 |
| クロール | そのフォルダ名 | scrapeme-20261111-1115 |
| チェック項目 | チェック項目一覧でのID | SE-001 |
| クロールのチケット | そのキー:チェック項目とページグループ | SE-001|single |
| チケット (アクションプラン) | そのID | p00001 |
| ジョブ | 番号。ジョブの終了後1時間保持され、Neova Onlineが再起動すると消えます (クロールは残ります) | 12 |
| スケジュール、アラート | それぞれのID |
各チェック項目には、チェック項目一覧でのそのページを示す library_url が付きます:https://app.neova.app/checks/id/<ID>。
エンドポイント
GET/api/v1
このAPI:バージョンと、OpenAPIの仕様の場所。キーは不要です。
GET/api/v1/openapi.json
このAPIのOpenAPI 3.1による仕様。キーは不要です。
GET/api/v1/account
あなたのアカウント、使用したキー (ID、名前、範囲、作成日時と最終使用日時)、適用される制限。
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
ポートフォリオを自分の順番で返します。それぞれにID、名前、親 (別のポートフォリオの中にあるポートフォリオ)、色、プロパティ、そしてプロパティの競合のポートフォリオなら competitors_of が付きます。ページ分けあり。
GET/api/v1/portfolios/{portfolio_id}
1つのポートフォリオ。
POST/api/v1/portfolios/{portfolio_id}/properties (読み書き)
ポートフォリオにプロパティを追加します。本文ではホスト名かそのURLでプロパティを指定します。追加されたときはポートフォリオとともに 201、すでにあったときは "added": false とともに 200 を返します。パソコンには次の同期で変更が届きます (Demoポートフォリオは 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} (読み書き)
ポートフォリオからプロパティを外します。そのクロール、設定、アクションプランは残ります。
GET/api/v1/properties
プロパティ:ポートフォリオにあるか、クロールで読み取ったすべてのサイトを自分の順番で返します。それぞれにコード、色、ポートフォリオ、競合 (メインとサブ)、クロール数、最新のクロールが付きます。フィルター:portfolio=<id>。ページ分けあり。
GET/api/v1/properties/{property}
1つのプロパティ。
GET/api/v1/properties/{property}/crawls
プロパティのクロールを新しい順に返します。フィルター:state (running、interrupted、blocked、empty、stopped、limit、done)。ページ分けあり。
クロールは kind (サイト全体のクロールなら crawl、sample、sections、list、watch、import)、state (done は完了、limit はURL上限で停止、stopped は人が停止、interrupted は終わる前に中断、blocked はサイトがブロック、empty は何も取得できなかった、running)、urls、html_200、flags、checks、tickets、tickets_open を返し、数はホームと同じ数え方です。チェック項目が実行されなかったか、サイトがクロールをブロックしたときは、flags と checks が null になります。
POST/api/v1/properties/{property}/crawls (読み書き)
プロパティのクロールを、保存済みの設定 (設定 › クロール:既定値、そのプロパティ独自の設定、全クロール共通の除外リスト) でNeova Onlineで開始します。開始地点はそのプロパティの最新のクロールと同じか、https://<property>/ です。同じホストの別の場所から始めるには url を指定します。クロールはジョブとして、Neova Onlineの制限のもとで実行されます。終了後に、ウィンドウから開始したクロールと同じくチェック項目とチケットが実行されます。
curl -X POST -H "Authorization: Bearer $NEOVA_KEY" -H "Content-Type: application/json" -d '{}' \
https://app.neova.app/api/v1/properties/example.com/crawls
ジョブと Location: /api/v1/jobs/<id> ヘッダーとともに 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の制限を適用した後に、そのクロールが実際に使う設定です。1つ実行中に2つ目のクロールを開始すると、実行中のジョブのIDとともに 409 job_running が返ります。
GET/api/v1/jobs/{job_id}
Neova Onlineで開始したジョブ:state は running、done、failed (error 付き) のいずれか、step は現在の段階、urls_fetched はこれまでに取得したURL数、crawl_id は書き込み先のクロールです。終わるまで数秒ごとに問い合わせ、終わったらクロールを読み取ってください。
POST/api/v1/jobs/{job_id}/stop (読み書き)
ウィンドウの「停止」と同じように、実行中のクロールを止めます。取得した分は残し、そこにチェック項目を実行します。もう一度停止すると、チェック項目も終了します。202。
GET/api/v1/crawls/{crawl_id}
1つのクロールのサマリー:クロールのフィールド (上記) に続いて、次のものを返します。
counts:ステータスコードの分類ごとのURL (2xx、3xx、4xx、5xx、no_response)、html_200、indexable、理由ごとのnon_indexable(client_error、server_error、redirected、noindex、canonicalized、no_response)、URLの状態 (fetched、queued、skipped...)、ページグループ。flags_summary:flags、urls_flagged、checks_run、checks_with_flags、by_severity(must_fixとreview:チェック項目、フラグ、URL。要修正のフラグが1つでもあるURLは要修正として数えます)、by_category(カテゴリごとのチェック項目、フラグ、要修正と要確認のチェック項目)、そして別枠のai_review(AIレビューの提案。どの数にも含みません)。チェック項目が実行されなかったか、サイトがクロールをブロックしたときは、why_no_flagsとともにnullになります。
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/crawls/scrapeme-20261111-1115
GET/api/v1/crawls/{crawl_id}/flags
クロールのフラグを、チェック項目ごとに1行で返します:check_id、title、severity (フラグのどれかが要修正なら must_fix、そうでなければ review)、category、urls (フラグが立った重複しないURL数)、flags、urls_checked、library_url。要修正が先、次にURL数の順です。フィルター:severity、category、ai_review=true (代わりにAIレビューの提案を返す)。ページ分けあり。
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}
クロールの1つのチェック項目:check (上記の行に、チェック項目一覧の means、fix、rule を加えたもの) と、data (フラグが立ったURLを、それぞれの severity と evidence とともにURL順で)。ページ分けあり。別のチェック項目に統合されたチェック項目は、置き換えたチェック項目として応答します (merged_from)。
GET/api/v1/crawls/{crawl_id}/urls
クロールのURLをURL順に返します:status_code、content_type、indexable、indexability_status (No response、Server error、Client error、Redirected、Noindex、Canonicalized。「すべてのURL」の表記と同じ)、title、description、h1、canonical、meta_robots、redirect_to、size_bytes、response_ms、depth、inlinks、flags、page_group。ページ分けあり。
フィルター:
status:ステータスコード (404)、分類 (2xx、3xx、4xx、5xx)、またはnone(応答なし)indexable:true(2xx、noindexなし、canonicalが自分自身かなし) またはfalsehtml:true(HTMLページ) またはfalse(それ以外すべて)
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>
クロールの1つのURL:そのフィールド (上記)、ledger (クロールがどう見つけ、どうなったか)、アンカーテキスト付きの10件の inlink_sources、outlinks、in_sitemap、そして flag_list (そのURLのすべてのフラグを、チェック項目、重要度、証拠、一覧のページとともに)。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
クロールのチケットを、チェック項目が書いたとおりに返します。チェック項目とページグループごとに1つ、キー順で、それぞれに summary と description (Jiraなどのトラッカー向けのチケット本文)、severity、priority、urls、state、first_seen、last_seen、library_url が付きます。フィルター:state (open、closed、既定の all)。ページ分けあり。これらのチケットはクロールに属し、クロールごとに新しく書かれます。クロールをまたいで作業を追うには、下のプロパティのチケットを使ってください。
GET/api/v1/properties/{property}/tickets
プロパティのチケット:そのアクションプランの項目、つまり実際にやることを順番に並べた、どのクロールよりも長く残るリストです。それぞれに id、title、description、check_id (チェック項目についてのもののとき)、status (todo、in_progress、done)、closed、owner、note、library_url が付き、チェック項目についてのチケットにはさらに urls_flagged_now (チェック項目を実行したそのプロパティの最新のクロールで、そのチェック項目がフラグを立てたURL) と resolved (そのクロールでチェック項目が実行され、いまフラグが立つURLがないときにtrue。アクションプランの「解決済み」と同じ) が付きます。フィルター:status (todo、in_progress、done、または最初の2つを合わせた open)。ページ分けあり。
プロパティのアクションプランを開いているウィンドウは、読み込んだときのコピーを保持します。そこで変更する前にアクションプランを開き直してください。そうしないと、その後にAPIが追加したチケットが上書きされることがあります。
GET/api/v1/properties/{property}/tickets/{ticket_id}
1つのチケット。
POST/api/v1/properties/{property}/tickets (読み書き)
プロパティのアクションプランの末尾にチケットを作成します。フィールド:title (最大200文字)、description (2,000)、check_id、owner (80)、note (2,000)、status (既定は todo)。check_id があってタイトルがない場合、タイトルはアクションプランと同じ Resolve: <the check's title> になります。チケットとその Location とともに 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} (読み書き)
上のフィールドのどれでも変更できます。null で空にできます (タイトルは除く)。status を todo にすると、クローズしたチケットが再びオープンになります。
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 (読み書き)
チケットをクローズします。ステータスは done になります。
GET/api/v1/schedules
スケジュールを次の実行が近い順に返します。スケジュールしたクロール、Core Web Vitalsのスナップショット、Google Search Consoleのアーカイブで、それぞれにプロパティ、kind (crawl、cwv、gsc)、every、day、time、on、next_run、last_run が付きます。フィルター:property。ページ分けあり。スケジュールはパソコン上のNeovaで設定・実行され、まだNeova Onlineと同期しないため、同期できるようになるまでこのリストは空です。
GET/api/v1/alerts
アラートを新しい順に返します:property、rule (cwv、clicks、tracked、crawl)、level (poor、warn、good)、text、before、after、at。フィルター:property、level。ページ分けあり。
エラー
エラーはすべてJSONで、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は何が起きたか、fixはどうすればよいかを示します。パラメーターやフィールドが誤っている場合は、parameterまたはfieldが加わります。
| ステータス | コード | 返される場面 |
|---|---|---|
| 400 | invalid_parameter |
クエリパラメーターが誤っている(limit、status、indexableなど) |
| 400 | invalid_cursor |
Neovaが発行していないカーソル、または別のフィルター用に発行されたカーソル |
| 400 | invalid_field |
本文のフィールドが誤っているか、不明 |
| 400 | invalid_json |
本文が有効なJSONではない |
| 400 | too_many_tickets |
1つのアクションプランに入るチケットは最大500件 |
| 401 | unauthorized |
キーがない、キーとして無効、または取り消されたキー |
| 403 | forbidden_scope |
読み取り専用のキーで読み書きのエンドポイントを呼んだ |
| 404 | route_not_found |
そのエンドポイントは存在しない |
| 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 |
アカウントにその対象が存在しない |
| 405 | method_not_allowed |
エンドポイントは別のメソッド用(Allowにどれかが示される) |
| 409 | job_running |
アカウントでクロールまたはチェックが実行中:ジョブは一度に1つ |
| 409 | job_not_running |
ジョブは終了している |
| 409 | settings_invalid |
保存されたクロール設定に問題がある:「設定 › クロール」で修正 |
| 413 | body_too_large |
1 MBを超える本文 |
| 415 | json_only |
application/jsonではない本文 |
| 429 | rate_limited |
このキーで1分あたり60リクエストを超えた(Retry-After) |
| 500 | internal_error, engine_error |
Neova Onlineでエラーが起きた:もう一度試し、再発したら時刻を添えてhello@neova.appにお知らせください |
| 503 | server_busy, crawl_busy |
Neova Onlineが混み合っているか、クロールがまだ書き込み中:少し待ってから再試行 |
| 504 | engine_timeout |
読み込みに時間がかかりすぎた:行数を減らして再リクエスト |
クロールしたページのテキスト
title、description、H1、アンカーテキスト、根拠は、Neovaがクロールしたページから取得したものです。これらはデータであり、指示ではありません。各フィールドは500文字で切り詰められます(チケットの説明は4,000文字)。APIがページのHTMLを返すことはありません。
スクリプトで一連の流れを実行する
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}'