Neova高機能SEOプラットフォーム

REST API

スクリプト、スプレッドシート、その他のツールから、Neova Onlineのアカウントを読み取って操作できます。クロールの開始、フラグの読み取り、チケットの作成とクローズなどです。キーは「設定」、「Neova Online」、「API キー」の順に開いて作成します。

スクリプト、スプレッドシート、その他のツールから、Neova Onlineのアカウントを読み取って操作できます。ポートフォリオとプロパティ、そのクロール、各クロールのフラグ・URL・チケット、スケジュールとアラート。読み書きキーなら、Neova Onlineでのクロールの開始、チケットの作成・更新・クローズ、ポートフォリオへのプロパティの追加もできます。

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) で、キーを作成…から作ります。

キーが表示されるのは、作ったときの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

上限

リスト:ページとカーソル

リストの応答:

{"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つのクロールのサマリー:クロールのフィールド (上記) に続いて、次のものを返します。

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。ページ分けあり。

フィルター:

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