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 (aggregates blend live and sampled runs together). |
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; cadence is set at creation). |
POST | /api/projects/:projectId/geo/prompts | session or API key | Create a tracked prompt (text, category, engines, cadence). |
POST | /api/projects/:projectId/geo/prompts/:promptId/run | session or API key | Run one prompt across its engines now (1 credit per prompt×engine, quota-checked). |
POST | /api/projects/:projectId/geo/run-all | session or API key | Run all active prompts now (credit + daily quota pre-checked). |
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/gsc | session, org owner/admin only | Disconnect GSC (drops stored metrics). |
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/rows | session or API key | GSC row detail by query or page dimension, aggregated over the window (impressions-weighted CTR/position). |
GET | /api/projects/:projectId/search-analytics/summary | session or API key | Google Search Console summary (clicks, impressions, CTR, position). |
PATCH | /api/projects/:projectId/integrations/gsc | session, org owner/admin only | Update GSC connection settings (site URL). |
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 data sync (day-dimension pull, 3-day re-pull). |
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 (credits pre-consumed, refunded on failure). |
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. |
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 (credit-metered). |
POST | /api/projects/:projectId/agent/chat | session or API key | Send a message to the Growth Agent (credit-metered, refunded on provider failure). |
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, entitlements, seat count. |
GET | /api/org/billing/invoices | session, org owner/admin only | Invoice history from Stripe. |
GET | /api/org/billing/preview-change | session, org owner/admin only | Preview a plan change with line-level proration (30-min freshness). |
GET | /api/org/billing/session-status | session, org owner/admin only | Poll a checkout session's completion status. |
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 | Current-period usage vs plan limits (runs, briefs, keywords, credits). |
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 period end or immediately per body). |
POST | /api/org/billing/change-plan | session, org owner/admin only | Execute a previewed plan change (always_invoice + proration_date). |
POST | /api/org/billing/checkout | session, org owner/admin only | Create a Stripe Checkout session for a plan (seat quantity aware). |
POST | /api/org/billing/portal | session, org owner/admin only | Open a Stripe Billing Portal session (invoices, payment methods). |
POST | /api/org/billing/resume | session, org owner/admin only | Resume a pending cancellation. |
POST | /api/org/billing/topup | session, org owner/admin only | One-off credit top-up checkout. |
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; syncs seat quantity). |
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/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 | Set the account locale ('en' | 'zh') driving UI and transactional mail language. |
POST | /api/account/delete | session cookie | Delete the account (cancels Stripe subscriptions, cascades sole-org data; 409 when blocked by shared orgs). |
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 | /health | public | Liveness probe: service name and the AI engine IDs currently configured. |