API Route Inventory
Every public REST endpoint, generated from the running route table and annotated with auth and scope.
Generated from createApp() — the same route table the API server runs. Internal platform/admin/webhook endpoints are excluded.
Base URL: https://app.aieo.ee/api · Auth: Authorization: Bearer aieo_... (API key) or the dashboard session cookie.
Mutating calls (POST/PATCH/DELETE) with an API key require the write scope; read-only keys get 403. API keys always act on their own organization; the x-org-id header is a session-auth feature for dashboard users with multiple memberships and does not switch an API key's org.
Hand-written request/response examples for core workflows will be added in the next documentation phase; this inventory is the complete, generated surface.
AI Visibility (GEO)
| Method | Path | Auth | Description |
|---|---|---|---|
DELETE | /api/projects/:projectId/geo/prompts/:promptId | session or API key | Delete a tracked prompt. |
GET | /api/projects/:projectId/geo/citations | session or API key | Which domains AI engines cite for the tracked prompts. |
GET | /api/projects/:projectId/geo/engines | session or API key | Per-engine visibility breakdown (finished runs of the current method only; legacy sampled runs are excluded). |
GET | /api/projects/:projectId/geo/executions/active | session or API key | GEO runs still on their way: queued, waiting for the DeepSeek off-peak window, sending, collecting. |
GET | /api/projects/:projectId/geo/prompts | session or API key | Tracked prompt list with per-prompt stats. |
GET | /api/projects/:projectId/geo/runs | session or API key | GEO run history (per prompt×engine×day). |
GET | /api/projects/:projectId/geo/runs/:runId | session or API key | One GEO run detail: raw answer, mentions, citations. |
GET | /api/projects/:projectId/geo/series | session or API key | Daily visibility time series for charts. |
GET | /api/projects/:projectId/geo/sov | session or API key | Share of voice by brand across AI answers. |
GET | /api/projects/:projectId/geo/summary | session or API key | AI visibility summary: mention rate, citation rate over a lookback window (?days). |
PATCH | /api/projects/:projectId/geo/prompts/:promptId | session or API key | Update a prompt (text, engines, active). |
POST | /api/projects/:projectId/geo/prompts | session or API key | Create a tracked prompt (text, category, engines). GEO runs only when started. |
POST | /api/projects/:projectId/geo/prompts/:promptId/run | session or API key | Run one prompt on its engines as one run request. Requires idempotencyKey and the priceVersion from a preview. |
POST | /api/projects/:projectId/geo/run-all | session or API key | Run every active prompt on its engines as one run request (at most 50 runs). Requires idempotencyKey and the priceVersion from the preview; optional DeepSeek policy. |
POST | /api/projects/:projectId/geo/run-all/preview | session or API key | About and at-most price of running every active prompt, with the priceVersion to confirm. |
POST | /api/projects/:projectId/geo/run-requests | session or API key | Create a GEO run request: items (≤ 50, each promptId, engine, optional policy) with an idempotencyKey. Accepted as a whole (every run's maximum held in one transaction) or rejected; same key + same items replays. A new request must send the priceVersion from its preview (400 when missing, 409 price_changed when stale). |
POST | /api/projects/:projectId/geo/run-requests/preview | session or API key | Price a selection before running it: typical and maximum usage units (1 unit = $0.0001) and engines without a verified price. No hold, no vendor call. |
SEO Intelligence
| Method | Path | Auth | Description |
|---|---|---|---|
DELETE | /api/projects/:projectId/seo/keywords/:keywordId | session or API key | Remove a tracked keyword. |
GET | /api/projects/:projectId/seo/backlink-gap | session or API key | Backlinks competitors have and the project lacks. |
GET | /api/projects/:projectId/seo/backlinks | session or API key | Backlink profile summary and top links. |
GET | /api/projects/:projectId/seo/competitor-discovery | session or API key | Discover competitors sharing SERPs from stored snapshots (overlap score). |
GET | /api/projects/:projectId/seo/competitor-discovery/:domain/keywords | session or API key | Co-occurrence keyword drill-down for one discovered competitor. |
GET | /api/projects/:projectId/seo/competitors | session or API key | Competitor matrix: overlap and position comparison. |
GET | /api/projects/:projectId/seo/competitors/missing | session or API key | Keywords competitors rank for and the project does not (?brandId). |
GET | /api/projects/:projectId/seo/distribution | session or API key | Cumulative position buckets (top3, top10, top20, top100). |
GET | /api/projects/:projectId/seo/domain-overview | session or API key | Aggregated view of the project's tracked keywords: rank summary, estimated traffic, top pages, SERP features, stored backlinks, competitor matrix. |
GET | /api/projects/:projectId/seo/intersection | session or API key | Keywords all selected competitors (2-4) hold top-20 for in the last 10 days, with each competitor's position. |
GET | /api/projects/:projectId/seo/keyword-gap | session or API key | Keyword gap vs selected competitors. |
GET | /api/projects/:projectId/seo/keywords | session or API key | Tracked keyword table with positions, volume, difficulty, intent. |
GET | /api/projects/:projectId/seo/serp | session or API key | Live SERP lookup for one keyword (calls the provider on demand). |
GET | /api/projects/:projectId/seo/serp-features | session or API key | SERP feature stats over the last 7 days (demo-mode heuristic flags only; real feature detection not wired in). |
GET | /api/projects/:projectId/seo/summary | session or API key | SEO headline metrics (avg position, tracked keywords, estimated traffic). |
POST | /api/projects/:projectId/competitors | session or API key | Add a competitor brand/domain to the project. |
POST | /api/projects/:projectId/seo/keywords | session or API key | Add tracked keywords (plan-limited). |
POST | /api/projects/:projectId/seo/refresh | session or API key | Queue a rank-check refresh for the project. |
POST | /api/projects/:projectId/seo/research | session or API key | Keyword research for a seed term (DataForSEO when configured). |
Search Console & Integrations
| Method | Path | Auth | Description |
|---|---|---|---|
DELETE | /api/projects/:projectId/integrations/bing | session, org owner/admin only | Disconnect Bing Webmaster. Synced Bing search data is deleted; AI Performance imports are kept. |
DELETE | /api/projects/:projectId/integrations/bing-ai/imports/:importId | session cookie | Delete one import (admin, or the member who uploaded it). |
DELETE | /api/projects/:projectId/integrations/gsc | session, org owner/admin only | Disconnect GSC. Stored data is kept; reconnecting the same site reuses it, a different site replaces it. |
GET | /api/projects/:projectId/integrations/bing | session or API key | Bing Webmaster connection status for the project: site, per-step sync state, pending site pick. |
GET | /api/projects/:projectId/integrations/bing-ai/compare | session or API key | Compare two imports a (before) and b (after) when canCompare allows. Overview: totals. Queries: aligned by query text with common/one-sided counts, paged; flagged when a period is estimated or the spans differ. Topics are never compared. |
GET | /api/projects/:projectId/integrations/bing-ai/imports | session or API key | List the project's AI Performance imports (no rows), the latest import per kind and the reminder switch. |
GET | /api/projects/:projectId/integrations/bing-ai/imports/:importId | session or API key | One import, by kind. Overview: daily citations and cited pages, totals, 28-day comparison, zero run, read-time differences. Queries: import-wide summary plus the first page of rows (search is refused here — use POST …/rows). Topics: all rows. |
GET | /api/projects/:projectId/integrations/bing/auth-url | session, org owner/admin only | Start Bing Webmaster OAuth (one-time state URL, webmaster.read). Refused for impersonated sessions. |
GET | /api/projects/:projectId/integrations/bing/crawl-stats | session or API key | Bing's daily crawl counters (pages crawled, in index, inbound links, status-code counts) for the newest days=7..180 it served. |
GET | /api/projects/:projectId/integrations/gsc | session or API key | GSC connection status for the project. |
GET | /api/projects/:projectId/integrations/gsc/auth-url | session, org owner/admin only | Start GSC OAuth (one-time state URL). |
GET | /api/projects/:projectId/search-analytics/insights | session or API key | GSC insights: type=striking|cannibalization|ctr|decay|brand, days=28|90. Returns a state; rows only when the period's imported data is complete. |
GET | /api/projects/:projectId/search-analytics/rows | session or API key | GSC row detail by query or page dimension, aggregated over the window (impressions-weighted CTR/position); returns the period and any missing days. |
GET | /api/projects/:projectId/search-analytics/summary | session or API key | Google Search Console summary (clicks, impressions, CTR, position) over a window that ends on the newest imported day; returns the period and any missing days. |
PATCH | /api/projects/:projectId/integrations/bing | session, org owner/admin only | Switch the connected Bing site among the account's verified sites; the previous site's synced data is removed. 409 if the connection changed meanwhile. |
PATCH | /api/projects/:projectId/integrations/bing-ai/settings | session cookie | Switch the stale-import reminder on or off (owner/admin). |
PATCH | /api/projects/:projectId/integrations/gsc | session, org owner/admin only | Switch the connected GSC site; the previous site's stored data is removed and a fresh 90-day history import starts. |
POST | /api/projects/:projectId/integrations/bing-ai/imports | session cookie | Upload Bing AI Performance CSV exports (multipart files[] + meta): the overview, grounding queries or topic portfolio. Queries and topics need the range chosen in Bing per file (meta.periods / meta.period). Per-file results, host check by file name with a signed confirmation, 30 files per project per UTC day. |
POST | /api/projects/:projectId/integrations/bing-ai/imports/:importId/rows | session or API key | One page of grounding queries for an import. The search term goes in the JSON body (search, limit ≤ 200, offset, sort) so it never lands in URL access logs; the import-wide summary is not affected by the search. |
POST | /api/projects/:projectId/integrations/bing/confirm | session, org owner/admin only | Confirm the Bing site after OAuth when no verified site matched the project domain. |
POST | /api/projects/:projectId/integrations/bing/sync | session or API key | Trigger a Bing sync of everything Bing currently serves; returns mode=busy while a sync runs. |
POST | /api/projects/:projectId/integrations/gsc/backfill/retry | session, org owner/admin only | Restart a GSC history import that stopped after repeated failures. |
POST | /api/projects/:projectId/integrations/gsc/confirm | session, org owner/admin only | Confirm site selection after OAuth (pending_token flow). |
POST | /api/projects/:projectId/integrations/gsc/sync | session or API key | Trigger a GSC sync of the last 16 days (re-pulls the latest 4, fills missing days); returns mode=busy while an import runs. |
Content Gaps & Briefs
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /api/projects/:projectId/content/briefs | session or API key | List generated content briefs. |
GET | /api/projects/:projectId/content/briefs/:briefId | session or API key | One content brief (outline, entities, FAQ). |
GET | /api/projects/:projectId/content/gaps | session or API key | Content gaps: keywords competitors rank top-10 for and the project does not. |
POST | /api/projects/:projectId/content/gaps/:gapId/brief | session or API key | Generate a content brief for a gap (metered: holds its maximum, settles at actual token cost). |
POST | /api/projects/:projectId/content/recompute-gaps | session or API key | Recompute content gaps from current rankings. |
Technical Audit
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /api/projects/:projectId/audit/latest | session or API key | Latest audit run with scored issues. |
POST | /api/projects/:projectId/audit | session or API key | Queue a technical SEO site audit (crawler, maxPages). |
Growth Agent & Recommendations
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /api/projects/:projectId/agent/conversations | session or API key | List Growth Agent conversations. |
GET | /api/projects/:projectId/agent/conversations/:conversationId/messages | session or API key | Messages of one conversation. |
GET | /api/projects/:projectId/recommendations | session or API key | Prioritized growth recommendations for the project. |
GET | /api/projects/:projectId/recommendations/:recId/review | session or API key | Before/after for a page task: the Google after-window and the audit recheck. |
PATCH | /api/projects/:projectId/recommendations/:recId | session or API key | Update recommendation status (done/dismissed). |
POST | /api/projects/:projectId/agent/analyze | session or API key | Run the full diagnostic analysis (metered at actual token cost; requestKey makes a retry harmless). |
POST | /api/projects/:projectId/agent/chat | session or API key | Send a message to the Growth Agent (metered at actual token cost). |
POST | /api/projects/:projectId/agent/conversations | session or API key | Create a Growth Agent conversation. |
Organization, Keys & Billing
| Method | Path | Auth | Description |
|---|---|---|---|
DELETE | /api/org/keys/:keyId | session, org owner/admin only | Revoke an API key — owner/admin only. |
GET | /api/org | session or API key | Active organization profile: plan, eligibility, usage balance by source, usage packs, member count. |
GET | /api/org/billing/checkout-status | session, org owner/admin only | Return-page poll: whether a checkout slot's payment has landed in our records. |
GET | /api/org/billing/invoices | session, org owner/admin only | Payments with Dodo's invoice link, newest first. |
GET | /api/org/invitations | session, org owner/admin only | List pending member invitations — owner/admin only. |
GET | /api/org/keys | session or API key | List the org's API keys (masked). |
GET | /api/org/usage | session or API key | Activity counts of the last 30 days by kind (not money — see the balance on GET /api/org). |
PATCH | /api/org | session, org owner/admin only | Update organization settings (name etc.) — owner/admin sessions only. |
POST | /api/org/billing/cancel | session, org owner/admin only | Cancel the subscription at the end of the billing period (with a churn-reason survey). |
POST | /api/org/billing/checkout | session, org owner/admin only | Open a Dodo hosted checkout for the $10 monthly plan (tax extra); requires the start-immediately consent. |
POST | /api/org/billing/portal | session, org owner/admin only | Open the Dodo customer portal (payment method, invoices, tax details). |
POST | /api/org/billing/resume | session, org owner/admin only | Resume a pending cancellation. |
POST | /api/org/billing/topup | session, org owner/admin only | Usage-pack checkout: quantity 1–50 packs of $10 (tax extra), valid 365 days from payment (subscribers only); requires the start-immediately consent. |
POST | /api/org/keys | session, org owner/admin only | Create an API key (optional read+write scope) — owner/admin only. |
POST | /api/org/leave | session cookie | Leave the organization (refuses last owner). |
POST | /api/org/transfer-ownership | session, org owner/admin only | Transfer org ownership atomically (org lock + role swap). |
Projects & Overview
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /api/projects | session or API key | List projects (websites) in the active org. |
GET | /api/projects/:projectId/overview | session or API key | Dashboard overview: Growth Score inputs, trend highlights. |
GET | /api/projects/:projectId/overview/report | session or API key | White-label HTML growth report for the project. |
POST | /api/projects | session or API key | Create a project (domain, name) — plan-limited. |
Account & Notifications
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /api/account/export | session cookie | Export the account's personal data (GDPR-style JSON export). |
GET | /api/account/preferences | session cookie | Read the account preferences: locale and the weekly-digest opt-out. |
GET | /api/notifications | session only (no API keys) | List in-app notifications for the current user (API keys rejected). |
GET | /api/notifications/unread-count | session only (no API keys) | Unread notification count. |
PATCH | /api/account/preferences | session cookie | Update account preferences: locale ('en' | 'zh', drives UI and transactional mail language) and/or digestOptOut (weekly growth digest opt-out). |
POST | /api/account/delete | session cookie | Delete the account (cancels the Dodo subscription of sole-owned orgs first, cascades their data; 409 when blocked by shared orgs, 502 when Dodo cannot confirm the cancellation). |
POST | /api/notifications/mark-read | session only (no API keys) | Mark notifications read (by ids or all). |
Free Tools
| Method | Path | Auth | Description |
|---|---|---|---|
POST | /api/tools/robots | session or API key | Free tool: fetch and parse a site's robots.txt. |
POST | /api/tools/schema | session or API key | Free tool: extract structured data (schema.org) from a URL. |
POST | /api/tools/serp | session or API key | Free tool: live SERP check for a query (DataForSEO or mock pool). |
POST | /api/tools/sitemap | session or API key | Free tool: fetch and summarize a site's sitemap. |
Meta
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /api/projects/:projectId/ai-readiness/latest | session or API key | Latest AI readiness check and the latest finished report (scores, verdicts, fix steps). |
GET | /api/projects/:projectId/ai-readiness/runs | session or API key | AI readiness history, newest first (cursor pagination; score deltas only within one caliber). |
GET | /api/projects/:projectId/ai-readiness/runs/:runId | session or API key | One AI readiness check with its report, or report=pruned after retention. |
GET | /api/projects/:projectId/page-priorities | session or API key | Priority pages: Google decay merged by URL key, filtered by the newest finished audit. Page-level AI rules are reported unavailable. |
GET | /health | public | Liveness probe: service name and the AI engine IDs currently configured. |
PATCH | /api/projects/:projectId/rank-settings | session, org owner/admin only | Automatic rank checks of a project: rankCadence daily|weekly|off and rankDepth 10|20|50|100 (org admins). |
POST | /api/projects/:projectId/ai-readiness/runs | session or API key | Start a free AI readiness check of the project's primary domain (reuses a live check or one finished in the last 10 minutes; 20 per organization per UTC day). |
POST | /api/projects/:projectId/page-priorities/tasks | session or API key | Add a priority page as a task; the server freezes the baseline. One unfinished task per page. |