One raw-data contract for local agents

Quickstart

Add the AgentGEO MCP server - it installs from npm on first run - then ask your agent for a GEO analysis or a raw fetch. The eight GEO analysis skills come built in, and everything the MCP server does maps 1:1 onto the REST endpoints documented below.

claude mcp add agentgeo -- npx -y agentgeo-mcp --api-url https://api.agentgeo.org --key ag_live_...

Authentication

Every /v1 endpoint requires a Bearer token, except the public meta endpoints (GET /health, GET /, GET /v1/surfaces, GET /v1/engines). Two credential types resolve to a workspace:

Create a key

The plaintext key is returned exactly once, on creation. List and read responses only ever expose the masked prefix. Keys with "scope": "test" always run in demo mode and charge zero credits.

curl -X POST https://api.agentgeo.org/v1/keys \
  -H "Authorization: Bearer <clerk-session-or-existing-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI pipeline",
    "scope": "live",
    "budget_monthly_credits": 1000
  }'

401 responses

HTTP/1.1 401 Unauthorized

{ "detail": "Missing or malformed Authorization header" }

// or, when a token is present but resolves to nothing:
{ "detail": "Invalid API key or session" }

Self-hosted deployments may also authenticate with a key from the server's API_KEYS environment variable; those callers share the single local workspace and are exempt from hosted plan enforcement.

Credits & plans

One successfully delivered provider record equals one credit. Failed records cost zero. Demo-mode runs cost zero. There is no charge per prompt, only per delivered record.

Plans

An unsubscribed workspace (the free state) has zero included credits and zero schedules: any live run or new schedule is refused before a provider call with a 402 (codes plan_included_credits_exhausted and plan_schedule_limit_reached). This is the paywall - subscribe to run; the free, human-run AI-visibility audit is the only no-cost way to see results and does not use this API. Paid plans never hard-stop at the included amount - overage records are billed at the plan's per-credit rate, and your account spend cap and per-key budgets remain the brakes (the cap defaults to your plan's included credits, 1,000 minimum, until you set one). Your resolved plan, this month's consumption and the current overage estimate are all in GET /v1/usage.

Errors

Every error is a JSON body with a single detail field: a string for 401 / 404 / 422, and a structured object for 402. All four 402 shapes carry a machine-readable code.

HTTP/1.1 402 Payment Required

{
  "detail": {
    "code": "account_spend_cap_exceeded",
    "message": "Account spend cap of 1000 credits/month would be exceeded: 998 used, 3 requested. Raise the cap in settings.",
    "capMonthlyCredits": 1000,
    "creditsUsed": 998,
    "creditsRequested": 3
  }
}

Fetches

The core endpoint. One prompt, one or more surfaces, synchronous delivery of normalized raw records. It does not accept brands, competitors or analysis settings.

curl -X POST https://api.agentgeo.org/v1/fetches \
  -H "Authorization: Bearer ag_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best cold brew subscription",
    "surfaces": ["chatgpt", "perplexity", "gemini"],
    "country": "US",
    "language": "en",
    "web_search": true
  }'

Request fields

Response

The run envelope is camelCase. mode is "demo" when the key scope is test (or, on a self-hosted server only, when the provider is unconfigured) - demo runs are clearly labelled and charge zero. status is completed, partial (some surfaces failed) or failed (nothing delivered, nothing billed).

{
  "id": "run_84c1f2ab91d3",
  "query": "best cold brew subscription",
  "surfaces": ["chatgpt", "perplexity", "gemini"],
  "country": "US",
  "language": "en",
  "provider": "managed_scraper",
  "mode": "live",
  "delivery": "sync",
  "status": "completed",
  "createdAt": "2026-07-17T09:30:00.000Z",
  "completedAt": "2026-07-17T09:30:41.000Z",
  "recordsDelivered": 3,
  "creditsCharged": 3,
  "answers": [{
    "surfaceKey": "chatgpt",
    "status": "delivered",
    "answerText": "...",
    "sources": [{
      "title": "...",
      "url": "https://...",
      "position": 1
    }],
    "fetchedAt": "2026-07-17T09:30:39.000Z",
    "latencyMs": 39400,
    "providerRecordId": "s_abc123...",
    "providerFields": {
      "web_search_triggered": true
    }
  }]
}

Built-in GEO skills

The eight GEO analysis workflows - prompt-set, visibility, share-of-voice, citations, sentiment, competitors, monitor and report - ship built into the MCP server and are served by this API. Your agent lists them, loads the one that matches the ask, and runs every analysis step locally on fetch output. Skill reads are free: they contact no AI provider and spend no credits.

{
  "object": "skill_list",
  "count": 8,
  "pipeline": "geo-prompt-set builds the prompt library every other skill consumes; geo-visibility, geo-share-of-voice, geo-citations and geo-sentiment each analyze one dimension; geo-competitors joins them into one comparison; geo-monitor tracks runs over time; geo-report synthesizes everything into an executive report.",
  "skills": [{
    "name": "geo-visibility",
    "description": "Measure whether and how prominently a brand appears in AI answers across engines...",
    "version": "0.1.0"
  }]
}

Over MCP the same delivery is the list_geo_skills and get_geo_skill tools, and the eight skills are also exposed as MCP prompts (Claude Code renders them as /mcp__agentgeo__geo-report-style slash commands). The server prefers the live copy from this API and falls back to the copy bundled in the npm package, so workflows stay fresh without reinstalling and keep working offline. The skills themselves are open source: github.com/gumlau/agentgeo-skills.

Runs

Immutable fetch history. Every run - API, playground or scheduled - lands here with the same envelope.

Query parameters

The list returns summaries - the run envelope with answers stripped, plus origin (api or schedule) and scheduleId. Fetch a single run by ID to get the full record set back. Unknown IDs return 404 "Run not found".

curl "https://api.agentgeo.org/v1/runs?limit=50" \
  -H "Authorization: Bearer ag_live_..."

Schedules

Repeated raw fetches on a fixed cadence. A schedule re-runs the same prompt and its results land in run history; it never watches for semantic changes.

Create fields

New schedules start active with nextRunAt one cadence interval from creation. PATCH accepts any subset of the create fields plus status ("active" | "paused"); only supplied fields change, and changing cadence recomputes nextRunAt from now. Each envelope carries a runsThisMonth count. DELETE responds with { "object": "schedule", "id": "...", "deleted": true }.

curl -X POST https://api.agentgeo.org/v1/schedules \
  -H "Authorization: Bearer ag_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily cold brew check",
    "query": "best cold brew subscription",
    "surfaces": ["chatgpt", "perplexity"],
    "cadence": "daily"
  }'

API keys

Managed keys for programmatic access. Creation is shown in the Authentication section - the plaintext secret appears once and is never retrievable again.

Create fields

Listing returns active keys only - masked prefix, never the secret or its hash. Revoking is a soft delete: the key stops authenticating immediately and disappears from the list. Unknown IDs return 404 "Key not found".

{
  "object": "api_key_list",
  "keys": [{
    "id": "key_1f2e3d4c5b",
    "name": "CI pipeline",
    "prefix": "ag_live_9f2…8c1d",
    "scope": "live",
    "budgetMonthlyCredits": 1000,
    "createdAt": "2026-07-17T09:00:00.000Z",
    "lastUsed": "2026-07-17T09:30:00.000Z"
  }]
}

Usage

The operational credit ledger: records, not conclusions. Your resolved plan, this month's live-credit consumption, a dense day-by-day series and the newest ledger entries.

Query parameters

The plan block reflects your resolved plan: overageCredits is max(0, creditsUsed − includedCredits), overageEstimatedUsd multiplies that by the plan's overage rate (0 when the plan has none), and includedRemaining counts down to zero. On committed-use plans includedCredits, includedRemaining and overagePerCredit are null. daily is zero-filled and ascending; ledger holds the 50 newest events. Only mode: "live" events count toward creditsUsed.

curl "https://api.agentgeo.org/v1/usage?days=30" \
  -H "Authorization: Bearer ag_live_..."

Providers

Upstream connection readiness per surface, computed from the deployment's provider configuration. When nothing is configured, runs fall back to clearly-labelled demo records.

{
  "object": "provider_status",
  "provider": "managed_scraper",
  "configured": true,
  "demoFallback": false,
  "surfacesConfigured": 6,
  "surfaces": [
    { "key": "chatgpt", "access": "managed_ai_scraper", "datasetConfigured": true },
    { "key": "perplexity", "access": "managed_ai_scraper", "datasetConfigured": true }
  ]
}

Self-hosters configure the provider token, per-surface dataset IDs and the Google AI Overview SERP zone in the server environment (second tab). Secrets, dataset IDs and zone names are never returned by the API or included in logs - this endpoint only exposes booleans.

Settings

Workspace name, default country and spend cap. Settings are key/value rows - anything you have not set falls back to its default.

PATCH fields (snake_case in, camelCase out)

Both GET and PATCH return the full settings envelope, including the resolved planId.

{
  "object": "workspace_settings",
  "workspaceId": "user_2h9k...",
  "workspaceName": "My workspace",
  "defaultCountry": "US",
  "spendCapEnabled": true,
  "spendCapMonthlyCredits": 5000,
  "authEnabled": true,
  "planId": "growth",
  "plan": { "name": "Growth", "includedCredits": 5000 }
}

Meta & discovery

Public endpoints - no Authorization header required. Everything else in this reference sits behind the Bearer gate.

{
  "object": "surface_list",
  "provider": "managed_scraper",
  "count": 6,
  "engines": [{
    "key": "chatgpt",
    "provider": "managed_scraper",
    "access": "managed_ai_scraper",
    "configured": true,
    "credits_per_delivered_record": 1
  }]
}

Six surfaces are supported: chatgpt, perplexity, gemini, google_ai_overview, google_ai_mode and copilot. Each catalog entry reports whether its upstream dataset is configured and confirms the flat rate: one credit per delivered record.

Product boundaries

The contract deliberately keeps data collection separate from interpretation.