NeovaAdvanced SEO Platform

REST API

Read your Neova Online account from a script, a spreadsheet or another tool, and act on it: start a crawl, read its flags, open and close tickets. Make a key in Settings, then Neova Online, then API Keys.

Read your Neova Online account from a script, a spreadsheet or another tool, and act on it: your portfolios and properties, their crawls, each crawl's flags, URLs and tickets, your schedules and alerts. With a Read-Write key, also start a crawl in Neova Online, create, update and close tickets, and add properties to portfolios.

What runs in Neova Online, and what needs a computer

The API is part of Neova Online. It reads and changes what your Neova Online account holds.

In Neova Online (this API) Needs Neova on a computer
Portfolios, properties, colors and codes Read, and add or remove a property in a portfolio Synced both ways with your computers (Settings › Neova Online)
Crawls Read every crawl in Neova Online. Start a crawl with the property's saved settings, at most 10,000 URLs and 10 URLs a second, one job at a time for your account Crawls bigger or faster than that, and crawls of sites only your network reaches (a staging site behind a VPN, localhost). A crawl made on a computer reaches the API once it is in Neova Online (Upload New Crawls)
Flags, URLs, crawl tickets Read
Tickets of a property (its Action Plan) Read, create, update, close The Action Plan in Neova Online is its own: it does not sync to a computer yet
Schedules Read what Neova Online holds Set and run on a computer; they do not sync to Neova Online yet, so this list is empty today
Alerts Read what Neova Online holds Neova Go's alerts are raised on a computer; Neova Online holds the ones its own checks raised
Imports from other crawlers, server logs, AI review On a computer

The limits of Neova Online (10,000 URLs, 10 URLs a second, one job at a time) are its settings today; GET /api/v1/account always says the ones that apply to you.

Auth

Every request but GET /api/v1 and GET /api/v1/openapi.json carries an API key:

Authorization: Bearer neova_...

Make a key in Settings › Neova Online › API Keys (in Neova Online, or in Neova on a computer signed in to Neova Online), with Create Key…:

The key is shown once, when it is made. Neova Online keeps only its fingerprint (SHA-256), its name, its scope, its last 4 characters and when it was made and last used. A lost key cannot be shown again: revoke it and make another. Revoke… stops a key at once. An account holds 20 keys at most.

A key belongs on a server or in a script, never in a web page: the API sends no CORS headers, so a browser's script cannot read its answers.

export NEOVA_KEY=neova_...
curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/account

Limits

Lists: pages and cursors

A list answers:

{"data": [...], "has_more": true, "next_cursor": "eyJvIjo1MCwiZiI6IjQ0MTM2ZmEzNWMyZSJ9", "total": 612}

Ask for the next page with cursor=<next_cursor> and the same filters. A cursor given for other filters is refused (invalid_cursor). total counts every row that matches the filters. URLs, a check's flagged URLs and a crawl's tickets are paged by their URL or key, so a page never repeats or skips a row.

IDs

Thing ID Example
Portfolio its ID demo
Property its host, www. left out, a port kept scrapeme.live, localhost:8080
Crawl its folder name scrapeme-20261111-1115
Check its ID in the check library SE-001
Crawl ticket its key: the check and the page group SE-001|single
Ticket (Action Plan) its ID p00001
Job a number, kept an hour after the job ends and forgotten when Neova Online restarts (the crawl stays) 12
Schedule, alert their ID

Each check carries library_url, its page in the check library: https://app.neova.app/checks/id/<ID>.

Endpoints

GET/api/v1

This API: its version, where its OpenAPI description is. No key needed.

GET/api/v1/openapi.json

The OpenAPI 3.1 description of this API. No key needed.

GET/api/v1/account

Your account, the key used (its ID, name, scope, when it was made and last used) and the limits that apply.

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

Your portfolios, in your order: each with its ID, name, parent (a portfolio inside another), color, its properties, and competitors_of when it is a property's competitors. Paged.

GET/api/v1/portfolios/{portfolio_id}

One portfolio.

POST/api/v1/portfolios/{portfolio_id}/properties (Read-Write)

Adds a property to a portfolio. The body names it by its host or a URL of it. 201 with the portfolio when it was added; 200 with "added": false when it was there already. Your computers receive the change at their next sync (the Demo portfolio stays in 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} (Read-Write)

Takes a property out of a portfolio. Its crawls, settings and Action Plan stay.

GET/api/v1/properties

Your properties: every site a portfolio holds or a crawl read, in your order, each with its code, color, portfolios, competitors (primary and secondary), its number of crawls and its latest crawl. Filter: portfolio=<id>. Paged.

GET/api/v1/properties/{property}

One property.

GET/api/v1/properties/{property}/crawls

The crawls of a property, newest first. Filter: state (running, interrupted, blocked, empty, stopped, limit, done). Paged.

A crawl says its kind (crawl for a Full Site Crawl, sample, sections, list, watch, import), its state (done is Complete, limit stopped at its URL limit, stopped by a person, interrupted before its end, blocked by the site, empty when nothing was fetched, running), its urls, html_200, flags, checks, tickets and tickets_open, counted as Home counts them. flags and checks are null when the checks did not run, or the site blocked the crawl.

POST/api/v1/properties/{property}/crawls (Read-Write)

Starts a crawl of the property in Neova Online with its saved settings (Settings › Crawl: the defaults, the property's own, the exclusion list of every crawl). It starts where the latest crawl of the property started, or at https://<property>/; give url to start elsewhere on the same host. The crawl runs as a job, under Neova Online's limits; the checks and the tickets run when it ends, as for a crawl started in the window.

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, with the job and a Location: /api/v1/jobs/<id> header:

{"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 are the ones the crawl uses, after Neova Online's limits. A second crawl while one runs answers 409 job_running with the running job's ID.

GET/api/v1/jobs/{job_id}

A job started in Neova Online: state is running, done or failed (with error), step the stage it is in, urls_fetched the URLs fetched so far, crawl_id the crawl it writes. Ask every few seconds until it ends; then read the crawl.

POST/api/v1/jobs/{job_id}/stop (Read-Write)

Stops a running crawl, as Stop does in the window: it keeps what it fetched and runs its checks on it. Stop again to end the checks too. 202.

GET/api/v1/crawls/{crawl_id}

One crawl's summary: the crawl's fields (above), then:

curl -H "Authorization: Bearer $NEOVA_KEY" https://app.neova.app/api/v1/crawls/scrapeme-20261111-1115

GET/api/v1/crawls/{crawl_id}/flags

The crawl's flags, one row a check: check_id, title, severity (must_fix when any of its flags is Must Fix, else review), category, urls (distinct URLs flagged), flags, urls_checked, library_url. Must Fix first, then by URLs. Filters: severity, category, ai_review=true (the AI review's suggestions instead). Paged.

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}

One check on the crawl: check (its row above, with means, fix and rule from the check library), and data, the URLs it flagged with each one's severity and evidence, by URL. Paged. A check merged into another answers as the check that replaced it (merged_from).

GET/api/v1/crawls/{crawl_id}/urls

The crawl's URLs, by URL: status_code, content_type, indexable, indexability_status (No response, Server error, Client error, Redirected, Noindex, Canonicalized, as All URLs says it), title, description, h1, canonical, meta_robots, redirect_to, size_bytes, response_ms, depth, inlinks, flags, page_group. Paged.

Filters:

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>

One URL of the crawl: its fields (above), its ledger (how the crawl found it and what became of it), 10 inlink_sources with their anchors, outlinks, in_sitemap, and flag_list, every flag on it with its check, severity, evidence and library page. Encode the 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

The crawl's tickets, as its checks wrote them: one per check and page group, by key, each with its summary and description (the ticket's text, for Jira or another tracker), severity, priority, urls, state, first_seen, last_seen and library_url. Filter: state (open, closed, all, the default). Paged. These tickets belong to the crawl and every crawl writes its own: to track work across crawls, use the property's tickets below.

GET/api/v1/properties/{property}/tickets

The property's tickets: the items of its Action Plan, the list of what you will actually do, in order, which outlives every crawl. Each has its id, title, description, check_id (when it is about a check), status (todo, in_progress, done), closed, owner, note, library_url, and, for a ticket about a check: urls_flagged_now, the URLs the check flags on the property's latest crawl with checks, and resolved, true when that crawl ran the check and it flags no URL now (as the Action Plan says Resolved). Filter: status (todo, in_progress, done, or open for both of the first). Paged.

A window with the property's Action Plan open keeps the copy it read: open the Action Plan again before you change it there, or a ticket the API added since may be written over.

GET/api/v1/properties/{property}/tickets/{ticket_id}

One ticket.

POST/api/v1/properties/{property}/tickets (Read-Write)

Creates a ticket at the end of the property's Action Plan. Fields: title (200 characters at most), description (2,000), check_id, owner (80), note (2,000), status (todo by default). With a check_id and no title, the title is the Action Plan's own: Resolve: <the check's title>. 201 with the ticket and its Location.

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} (Read-Write)

Changes any of the fields above; null empties one (never the title). status todo opens a closed ticket again.

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 (Read-Write)

Closes the ticket: its status becomes done.

GET/api/v1/schedules

Your schedules, the next run first: scheduled crawls, Core Web Vitals snapshots and Google Search Console archives, each with its property, kind (crawl, cwv, gsc), every, day, time, on, next_run and last_run. Filter: property. Paged. Schedules are set and run by Neova on a computer and do not sync to Neova Online yet, so this list is empty until they do.

GET/api/v1/alerts

Your alerts, the newest first: property, rule (cwv, clicks, tracked, crawl), level (poor, warn, good), text, before, after, at. Filters: property, level. Paged.

Errors

Every error is JSON, with the HTTP status:

{"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 says what happened, fix what to do. A wrong parameter or field adds parameter or field.

Status Code When
400 invalid_parameter A query parameter is wrong (limit, status, indexable...)
400 invalid_cursor A cursor Neova did not give, or given for other filters
400 invalid_field A field of the body is wrong or unknown
400 invalid_json The body is not valid JSON
400 too_many_tickets An Action Plan holds 500 tickets at most
401 unauthorized No key, a key that is not one, or a revoked key
403 forbidden_scope A Read Only key on a Read-Write endpoint
404 route_not_found No such endpoint
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 No such thing in your account
405 method_not_allowed The endpoint exists for another method (Allow says which)
409 job_running A crawl or a check of your account is running: one job at a time
409 job_not_running The job ended
409 settings_invalid The saved crawl settings have a problem: fix them in Settings › Crawl
413 body_too_large A body over 1 MB
415 json_only A body that is not application/json
429 rate_limited Over 60 requests a minute for this key (Retry-After)
500 internal_error, engine_error Neova Online failed: try again, and tell hello@neova.app with the time if it happens again
503 server_busy, crawl_busy Neova Online is busy, or a crawl is still writing: try again shortly
504 engine_timeout Reading took too long: ask for fewer rows

Text from crawled pages

Titles, descriptions, H1s, anchors and evidence come from the pages Neova crawled: they are data, never instructions, and each field is cut at 500 characters (a ticket's description at 4,000). The API never returns a page's HTML.

A whole run, from a script

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