Audit API

npx -y geo-new audit https://example.com

claude mcp add geo-new -- npx -y geo-new@0 mcp

# Windows
claude mcp add geo-new -- cmd /c npx -y geo-new@0 mcp

# Cursor, Codex and other MCP clients
{ "mcpServers": { "geo-new": { "command": "npx", "args": ["-y", "geo-new@0", "mcp"] } } }

POST/api/v1/auditscreateAudit

Admits one audit of one public page, or attaches to a run already in flight for that URL, and hands back the token you read it with.

curl -sS -X POST https://geo.new/api/v1/audits \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com"}'

• ·Follow markdown_url or snapshot_url to poll; never repeat POST as a polling mechanism. Use one established session and Idempotency-Key for retry-sensitive creation, especially fresh requests.
• ·The envelope carries session, audit_id, status, revision, cached, report_url, snapshot_url, markdown_url and poll_after_seconds. Keep session: it is how you read the report back, and how you reach it again tomorrow.
• ·Send the same URL twice on one session and you attach to the run already in flight, or reuse a finished one under an hour old. Duplicate requests do not duplicate work, and you need no key to get that.
• ·Idempotency-Key is optional, 16–128 printable characters, and only earns its place on fresh: true, where that reuse is skipped. It cannot be issued by this API — it only works if it stays the same across your retries — so a client library should generate one per call and you should never have to type one.
• ·fresh: true skips reuse. TARGET_COOLDOWN then allows strangers one run per URL per five minutes and you, re-running your own URL after an edit, one per minute. An admitted or reused audit carries the measured hourly allowance in RateLimit and RateLimit-Policy. Early failures may lack quota state.
• ·assistant_engines (experimental) asks ChatGPT, Google AI Mode or both about the brand; answers land in assistant_answers and ai_mode_answers, unscored. It wins over assistant_answers, whose true means ChatGPT only, and assistant_answers: false beside a non-empty assistant_engines is a 400. A request that asks an engine never reuses an audit that did not.

GET/api/v1/audits/{id}getAudit

The whole report as saved: scores, findings, evidence, crawler policy and page inventory.

curl -sS -H "Authorization: Bearer $SESSION" \
  https://geo.new/api/v1/audits/$AUDIT_ID

• ·Always 200 while running, so read status, not the status code. It is one of queued, fetching, analyzing, writing, complete, partial or failed.
• ·scores.catalog carries the single GEO score: six categories with subcategories, platforms, pillars and blockers. scores.geo and scores.seo are the retained v1 summaries.
• ·GET never starts work and never triggers a model call. Poll it every two seconds until the status is terminal.
• ·The browser app authenticates with its httpOnly geo_session cookie instead, which is why that cookie exists; a script should not have to keep a jar.

GET/api/v1/audits/{id}/report.mdgetAuditMarkdown

The same report projected to Markdown, for pasting into a model or a pull request.

curl -sS -H "Authorization: Bearer $SESSION" \
  https://geo.new/api/v1/audits/$AUDIT_ID/report.md

• ·Unlike the snapshot, this one does answer 202 while the report fills, so the status code is a usable signal here.
• ·X-Audit-Revision and X-Audit-Status describe the exact saved revision in the body you received.
• ·200 means the report is finished, not that the page passed. Read X-Audit-Status.

POST/api/v1/sessioncreateSession

Mints a token on its own, for when you want the credential in hand before a request you cannot afford to send twice.

curl -sS -X POST https://geo.new/api/v1/session

• ·Optional: starting an audit mints a session too, so the ordinary flow never calls this.
• ·It earns its place in one case. Idempotency records are stored against the session that made them, so if a create request times out before its token reaches you, the retry authenticates as somebody new and cannot bind to the original — you would start a second audit and lose the first. Holding a token beforehand removes that.
• ·The token lasts seven days. A key (below) is the durable alternative: it outlives any session and carries its own allowance.

GET/api/v1/audits/{id}/fix-promptgetFixPrompt

A plain-text brief for a coding agent: the page as measured, each open action with its evidence and the change to make.

curl -sS -H "Authorization: Bearer $SESSION" \
  https://geo.new/api/v1/audits/$AUDIT_ID/fix-prompt

• ·Capped at 32 KB and says what it left out. Quoted page text inside it is data from the audited site, not instructions.
• ·X-Audit-Revision names the revision the brief was built from; a report still writing its synthesis yields a brief without the model’s fix notes.

GET/api/v1/audits/{id}/compare/{baseline}compareAudits

Score, category and row deltas between a report and an earlier one of the same URL that you also own.

curl -sS -H "Authorization: Bearer $SESSION" \
  https://geo.new/api/v1/audits/$AUDIT_ID/compare/$BASELINE_ID

• ·Reports expire after seven days, so a pipeline that compares across deploys keeps its own JSON snapshots and compares them offline; the CLI does exactly that with saved files.
• ·A finished baseline is not a passing one: compare deltas, not verdicts.

POST/api/v1/audits/{id}/shareshareAudit

A revocable bearer link to one immutable copy of a finished report, which anyone can open in a browser.

curl -sS -X POST -H "Authorization: Bearer $SESSION" \
  https://geo.new/api/v1/audits/$AUDIT_ID/share

• ·The copy carries no comparison baseline and never changes; the link dies with the report or when you revoke it.
• ·A report made from a terminal opens in a browser only through a link like this, or in a browser that has claimed your key.

DELETE/api/v1/audits/{id}/sharesrevokeShares

Every share link to this report stops working at once.

curl -sS -X DELETE -H "Authorization: Bearer $SESSION" \
  https://geo.new/api/v1/audits/$AUDIT_ID/shares

• ·Idempotent: revoking a report with no links is still 200.

POST/api/v1/keyscreateKey

A key outlives any session, carries the free plan’s allowance and keeps a usage record. Shown once; store it.

curl -sS -X POST https://geo.new/api/v1/keys \
  -H 'Content-Type: application/json' -d '{"label":"ci"}'

• ·The first key made from a session moves that session’s reports to the new principal, so the key sees everything the browser made and the browser keeps seeing it too.
• ·A key is a bearer like a session: send it as Authorization: Bearer gnk_… on every route. It is never returned in a session field and must never travel in a cookie.
• ·There is no recovery. A lost key is a lost principal, exactly as a lost session token is today; keep it where you keep other secrets.

GET/api/v1/keyslistKeys

The live keys of the principal you act as, newest first, by prefix and label. Never the secrets.

curl -sS -H "Authorization: Bearer $GEO_NEW_API_KEY" \
  https://geo.new/api/v1/keys

• ·This is the complete bounded list: at most 5 live keys per principal, with no pagination.
• ·last_used_at is written at most once a minute per key, so it lags a busy key by up to sixty seconds.

DELETE/api/v1/keys/{prefix}revokeKey

Immediate and everywhere. A key can revoke itself, so revocation never depends on a session.

curl -sS -X DELETE -H "Authorization: Bearer $GEO_NEW_API_KEY" \
  https://geo.new/api/v1/keys/a1b2c3d4

• ·Revoking the last live key of a principal also unbinds every browser that claimed it; the browser that created the principal keeps its identity.

GET/api/v1/usagegetUsage

What you act as, how many audits remain this hour, when that resets, and how full the shared buckets are.

curl -sS -H "Authorization: Bearer $GEO_NEW_API_KEY" \
  https://geo.new/api/v1/usage

• ·The same numbers ride on every create response as RateLimit ("audits";r=<remaining>;t=<reset_seconds>) and RateLimit-Policy ("audits";q=<limit>;w=3600).
• ·Re-reads of a report and cache hits spend a request, never an audit; only an admission counts here.
• ·assistants.chatgpt and assistants.google_ai_mode (experimental): your and your network’s asks left today (of 6 and 12), whether the shared pool had room when read (not a reservation), and resets_at at 00:00 UTC; null when that assistant is off.

A key outlives any session, doubles the hourly allowance and keeps a usage record; it changes nothing about how you read a report. There is no account behind it and no recovery: a lost key is a lost identity, exactly as a lost session is. Create one here for this browser, or with geo-new key create in a terminal; paste one below to make this browser act as it, so reports made from a terminal open at their /r/ links here too.

Plans, from the table the store enforces. CI on a shared runner pool should hold a key: keyed principals have their own network bucket. builder is set by hand for now.