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, 계정당 한 번에 작업 하나 그보다 크거나 빠른 크롤링, 그리고 내 네트워크에서만 닿는 사이트(VPN 뒤의 스테이징 사이트, localhost)의 크롤링. 컴퓨터에서 만든 크롤링은 Neova Online에 올라가면(새 크롤링 업로드) API에서 볼 수 있습니다
플래그, URL, 크롤링 티켓 읽기 완료
속성의 티켓(실행 계획) 읽기, 만들기, 업데이트, 닫기 Neova Online의 실행 계획은 독립적입니다. 아직 컴퓨터와 동기화되지 않습니다
예약 Neova Online에 있는 것 읽기 컴퓨터에서 설정하고 실행합니다. 아직 Neova Online과 동기화되지 않으므로 지금은 이 목록이 비어 있습니다
알림 Neova Online에 있는 것 읽기 Neova Go의 알림은 컴퓨터에서 생깁니다. Neova Online에는 자체 점검이 만든 알림이 있습니다
다른 크롤러에서 가져오기, 서버 로그, AI 검토 컴퓨터에서

Neova Online의 한도(URL 10,000개, 초당 URL 10개, 한 번에 작업 하나)는 현재 설정값입니다. GET /api/v1/account가 언제나 사용자에게 적용되는 한도를 알려 줍니다.

인증

GET /api/v1과 GET /api/v1/openapi.json을 제외한 모든 요청에는 API 키가 있어야 합니다.

Authorization: Bearer neova_...

설정 › Neova Online › API 키(Neova Online에서, 또는 Neova Online에 로그인한 컴퓨터의 Neova에서)에서 키 만들기…로 키를 만드세요.

키는 만들 때 한 번만 보여 줍니다. Neova Online은 키의 지문(SHA-256), 이름, 범위, 마지막 4자, 만든 시각과 마지막 사용 시각만 보관합니다. 잃어버린 키는 다시 볼 수 없으니 폐기하고 새로 만드세요. 폐기…는 키를 즉시 중지합니다. 계정당 키는 최대 20개입니다.

키는 서버나 스크립트에 두고, 웹 페이지에는 절대 두지 마세요. 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}

포트폴리오 하나.

POST/api/v1/portfolios/{portfolio_id}/properties (읽기 및 쓰기)

포트폴리오에 속성을 추가합니다. 본문에서 속성을 호스트나 그 URL로 지정합니다. 추가되면 포트폴리오와 함께 201, 이미 있었으면 "added": false와 함께 200. 컴퓨터는 다음 동기화 때 변경을 받습니다(데모 포트폴리오는 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}

속성 하나.

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

202, 작업 정보와 Location: /api/v1/jobs/<id> 헤더:

{"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의 한도를 적용한 뒤 크롤링이 실제로 쓰는 값입니다. 크롤링이 실행 중일 때 두 번째 크롤링을 요청하면 실행 중인 작업의 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}

크롤링 하나의 요약: 크롤링 필드(위 참고), 그다음:

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

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

크롤링의 플래그, 점검당 한 행: 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}

크롤링의 점검 하나: 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>

크롤링의 URL 하나: 필드(위 참고), ledger(크롤링이 이 URL을 어떻게 찾았고 어떻게 처리했는지), 앵커가 포함된 inlink_sources 10개, 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

점검이 쓴 그대로의 크롤링 티켓: 점검과 페이지 그룹마다 하나씩, 키 순. 각각 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, 또는 앞의 둘을 뜻하는 open). 페이지로 나뉩니다.

속성의 실행 계획을 열어 둔 창은 읽어 온 사본을 그대로 가지고 있습니다. 그 창에서 바꾸기 전에 실행 계획을 다시 여세요. 그러지 않으면 그사이 API가 추가한 티켓을 덮어쓸 수 있습니다.

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

티켓 하나.

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. 페이지로 나뉩니다.

오류

모든 오류는 HTTP 상태와 함께 JSON으로 옵니다.

{"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 실행 계획에는 티켓을 최대 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 계정에서 크롤링이나 점검이 실행 중임: 작업은 한 번에 하나씩
409 job_not_running 작업이 이미 끝남
409 settings_invalid 저장된 크롤링 설정에 문제가 있음: 설정 › 크롤링에서 고치세요
413 body_too_large 본문이 1 MB를 넘음
415 json_only 본문이 application/json이 아님
429 rate_limited 이 키로 분당 60회를 넘는 요청(Retry-After)
500 internal_error, engine_error Neova Online에서 오류가 남: 다시 시도하고, 또 일어나면 시각과 함께 hello@neova.app으로 알려 주세요
503 server_busy, crawl_busy Neova Online이 바쁘거나 크롤링이 아직 쓰는 중: 잠시 후 다시 시도하세요
504 engine_timeout 읽기가 너무 오래 걸림: 더 적은 행을 요청하세요

크롤링한 페이지의 텍스트

타이틀, 디스크립션, 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}'