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.
- Address:
https://app.neova.app/api/v1 - Format: JSON in and out, UTF-8. Times are ISO 8601 in UTC (
2026-11-11T17:15:15Z). - Description:
GET /api/v1/openapi.jsonis the OpenAPI 3.1 description of every endpoint below, made from the same table the server answers from.
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…:
- Key Name: what will use it, for example Looker Studio.
- Scope: Read Only reads everything this page lists and changes nothing. Read-Write also starts crawls, creates, updates and closes tickets, and adds properties to portfolios.
- Your Neova Online Password: asked each time a key is made.
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
- 60 requests a minute per key, counted over the last 60 seconds. Every answer says where you stand:
X-RateLimit-Limit: the requests a minute of this keyX-RateLimit-Remaining: what is left in the current minuteX-RateLimit-Reset: when a request frees up (Unix time, seconds)- Over the limit:
429withRetry-After(seconds) and the errorrate_limited.
- Pages: 50 rows by default, 500 at most (
limit). - Crawls: one job at a time for your account (a crawl, or the checks run again), at most the account's
max_urlsandurls_per_second, whatever the property's saved settings say. - Bodies: 1 MB at most.
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:
counts: URLs by status code class (2xx,3xx,4xx,5xx,no_response),html_200,indexable,non_indexableby reason (client_error,server_error,redirected,noindex,canonicalized,no_response), the URLs' states (fetched,queued,skipped...), the page groups.flags_summary:flags,urls_flagged,checks_run,checks_with_flags,by_severity(must_fixandreview: checks, flags and URLs; a URL with any Must Fix flag counts under Must Fix),by_category(each category's checks, flags, and its Must Fix and Review checks), andai_reviewapart (the AI review's suggestions, which no count includes).null, withwhy_no_flags, when the checks did not run or the site blocked the crawl.
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:
status: a status code (404), a class (2xx,3xx,4xx,5xx) ornone(no response)indexable:true(2xx, no noindex, canonical to itself or none) orfalsehtml:true(HTML pages) orfalse(everything else)
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}'