How geo-mode works

Getting started

geo-mode does two halves of GEO - Generative Engine Optimization - for agencies and web designers. Citation tracking measures whether a client's domain is the answer AI assistants actually give for buyer-intent questions, and who wins the answer instead. The content engine generates answer-shaped content clusters engineered to win those citations, grounded in the client's real pages.

1. Create your account. Sign up free - no card. The free plan runs real single-sample checks on Claude, so you see live data before paying.
2. Add a client workspace. One workspace per client: their domain, brand name, and the competitors you want share-of-voice against. Everything - questions, checks, clusters, the report - is scoped to the workspace.
3. Track the questions that matter. Add the questions buyers actually ask ("best emergency plumber near me?"). geo-mode puts each one to the assistants on a weekly schedule and records who gets cited.
4. Generate a cluster. Give the engine the client's niche and it builds a set of interlinked, answer-shaped pages - with schema, meta and internal links already wired. Hit Save cluster when you are happy; the WordPress plugin, CLI, API and MCP all pull saved clusters by id.
5. Ship it and close the loop. Push to WordPress, optimize a Shopify store, export files, or pull the pages over the API. Then mark the cluster implemented - the weekly checks start proving, URL by URL, when AI begins citing the client.

Content engine

A cluster is a set of pages, each answering one buyer question, grouped into topic clusters and interlinked. Every generated page ships with:

• A direct, answer-shaped opening an assistant can lift verbatim - the H1 stays the buyer's question.
• Schema.org JSON-LD - Article, plus FAQPage / HowTo where the content supports it.
• A distinct meta title and meta description.
• Internal links to the sibling pages in the cluster.
• A site-level llms.txt and a linking map in the bundle exports.

Grounded generation and verified citations

When a workspace has a client domain, generation grounds itself automatically: geo-mode fetches the client's real, live pages (and, where external discovery is configured, real third-party sources on the topic) and constrains the model to those facts. Cited URLs are fetched and verified - a citation that resolves to a dead page (404/410) collapses the page's score and is flagged, because a fabricated citation is worse than no citation. The engine never invents first-party data: where a fact is missing it says so rather than hallucinating it.

Structure score - what the number means

Every page carries a structure score (0-100), weighted across five dimensions of answer-shaped writing. It measures structure and format, not a citation prediction - a 95 means the page is built the way cited pages are built, not that citation is guaranteed. The proof of citation comes from tracking, never from the score.

The integrity gate on "Mark implemented"

Marking a cluster implemented starts the time-to-citation clock, so it is gated: pages carrying placeholder or illustrative sources, unsourced numeric claims, or a citation that returns 404 block the action with a 422 integrity_block response listing the offending pages. Replace the sources and mark it implemented again. Unpublishing is never blocked.

Bring your own key

Every plan - including Free - lets you add your own Anthropic API key in Account; content generation then runs on your key. Plans and monthly cluster quotas are on the pricing page.

Citation tracking

You add the questions buyers actually ask; geo-mode puts each one to the AI assistants on a weekly schedule and records - for the client and for each named competitor - whether the domain was cited and which sources the assistant leaned on.

• Assistants. Paid plans check every question across Claude, ChatGPT, Perplexity and Gemini. The free plan runs single-sample checks on Claude.
• Adaptive sampling, honestly reported. New, changed or contested questions run 3 samples per assistant, aggregated by majority. Questions that have proven stable are re-verified weekly and re-baselined at 3 samples monthly. Each check row records how many samples produced its verdict.
• What "cited" means. A question counts as cited for an assistant only when the majority of that run's samples cite the client's domain - one flaky answer is not a verdict.
• Alerts on confirmed changes only. A win or loss emails you once it has been confirmed at 3 samples, so a single flip cannot page you about a change that is not real.
• Share of voice. The same checks run for the competitors on the workspace, so the report shows who wins each question, not just whether you did.
• Source intelligence. Every check records the domains the assistant leaned on - the map of who currently owns the answers in the niche.

The tracked-question pool is account-wide - spread it across clients however you like. Pool sizes per plan are on the pricing page; on Agency, adding your own OpenAI, Gemini and Perplexity keys moves tracking onto your keys and opens a larger pool.

White-label reports

Every client workspace has a shareable report at its own private link - geo-mode.com/r/<slug>, where the slug is generated and non-enumerable. It shows citation rate over time, the per-assistant grid, share of voice against competitors, and the sources assistants lean on.

• Your brand, not ours. Set your agency name and brand colour in the report settings; the page renders in them.
• Badge removal. On the Pro and Agency plans the "Powered by geo-mode" badge is removed entirely, so the report reads as your own product. Exports are unbranded on every plan.
• Honest empty states. A workspace still running sample checks shows an honest "live tracking is being connected" preview - the report never fabricates numbers it does not have.
• Publish control. Disable a report and its URL returns 404 until you re-enable it.

Deployments

A deployment records where a cluster went live: the connector that shipped it and the live page URLs. Deployments are what turn tracking into proof - every deployed URL is matched against the weekly checks, so the app can show this page, cited by this assistant, on this date, for this question.

• A deployment starts as started and flips to deployed once its live URLs are recorded.
• The WordPress push creates and completes one automatically. Custom ships (static sites, headless builds) record theirs over the API or the MCP tools.
• Deployments record where content lives. Marking a cluster implemented is a separate, integrity-gated action that starts the time-to-citation clock.

WordPress push

The smoothest path. The geo-mode Connector plugin (v1.2.0) connects a WordPress site to your account; you can then import clusters from inside wp-admin, push them from geo-mode without touching the site, or apply an additive retrofit to an existing page (layered as post meta, so the original content is never modified and rollback is instant).

1. Install it. In the client's WordPress admin: Plugins - Add New - Upload Plugin, choose the .zip, then Activate.
2. Connect it. Open geo-mode - Connect, set the API base to https://geo-mode.com, paste your gm_live_… key, and click Save & connect. Saving registers the site with your account and provisions a per-site receiver token, so the site shows up as a push target.
3. Import, or push. From wp-admin: geo-mode - Import pulls a cluster in as draft posts you review and publish. From geo-mode: the Push to WordPress button on a saved cluster (owner-only) ships it in one step - the site imports and publishes the pages and reports back the live URLs, which complete the deployment.
4. Re-push safely. Imports and pushes update the same posts by slug - re-shipping a revised cluster never duplicates pages.
5. Close the loop. Mark the cluster implemented in geo-mode to start time-to-citation tracking.

Pages arrive as native Gutenberg blocks with the meta title, meta description and JSON-LD already attached. If a push cannot reach the site, or the site answers wrongly, geo-mode returns a readable 409 naming the site and the deployment stays started - fix the connection and push again.

Exports and copy-as

Every cluster exports in four formats - from the app's Export tab, the API, or the CLI:

Per page, the app's Copy as menu gives an HTML fragment, Gutenberg blocks, or the meta title + description for a builder's SEO fields. Exported files are unbranded on every plan.

/answers - the lane we run on ourselves

geo-mode publishes its own GEO cluster at geo-mode.com/answers (with the matching /llms.txt), shipped through the same pipeline documented on this page and measured by the same weekly checks on our live public report. It is the product's own dogfood lane - the loop, closed on ourselves.

Shopify app

For Shopify stores, geo-mode installs as a native app that optimizes product and collection pages for AI shopping assistants - the surface that decides which product gets recommended when a shopper asks an AI what to buy.

1. Install the app. From your Account (the Shopify card), enter the store's .myshopify.com domain and approve the install in the Shopify admin. A geo-mode workspace is created for the store automatically.
2. Optimize products. In the embedded app, pick products or collections and click Optimize. geo-mode writes Product / Offer / FAQ schema (JSON-LD) through metafields, rendered server-side by the theme extension - non-destructive and fully reversible.
3. Generate buyer-intent content. Answer-shaped product Q&A and "best X for Y" collection pages, grounded in the live catalog - the same engine behind the content API.
4. Track it. Shopping-query citation tracking shows whether the store's products get recommended by ChatGPT, Perplexity, Gemini and Claude.

CLI

Best for static-site generators (Astro, Hugo, Next, Eleventy) and Git-based publishing. The CLI is a zero-dependency single file over the same v1 API - no install step beyond downloading it:

curl -fsSL https://geo-mode.com/geomode -o geomode
chmod +x geomode

./geomode login          # paste your gm_live_ key (stored in ~/.geomode)
./geomode list           # your saved clusters
./geomode export <id> --format markdown --out ./content
./geomode sync --out ./content   # export every cluster at once

To run it from anywhere, move it onto your PATH: sudo mv geomode /usr/local/bin/ - then it is just geomode login.

Auth resolution, first match wins: --key flag, the GEOMODE_KEY environment variable, then the stored config. The API base follows the same order via --api / GEOMODE_API - handy for CI.

API reference

The REST surface behind the CLI, the WordPress plugin and any custom build. Base URL https://geo-mode.com. Requests and responses are JSON unless a download is noted; request bodies are capped at 16 MB.

Authentication

Create an API key in Account - API keys (owner-only; the raw gm_live_… value is shown once, and keys can be revoked at any time). Send it as a Bearer token:

curl -H "Authorization: Bearer gm_live_YOUR_KEY" https://geo-mode.com/api/v1/clusters

Endpoints marked Bearer key below also accept the app's session cookie, so they work from the browser too. The one exception is the MCP endpoint, which accepts only a Bearer key by design. A missing or invalid key returns 401 {"error":"Not signed in","code":"unauthenticated"}.

Rate limits: the API surface - every /api/v1/* endpoint and the MCP endpoint - allows 300 requests per minute per account. Exceeding it returns 429 with a retry-after header; on /api/mcp the 429 body is a JSON-RPC error (code -32002) carrying the same retryAfter. Generation endpoints (content, scan, strategy) stay limited to 40 calls per hour per account, with the same 429 + retry-after contract.

Public endpoints - no auth

Service status: {"ok":true, "platformLive":…, "model":…, "billingEnabled":…, "seedNiche":…}.

The live plan catalog: {"plans":[…], "billingEnabled":…, "purchasable":[…]} - the same data the pricing page renders.

A full demo cluster ({"cluster":…}) - useful for exploring the cluster shape without generating one.

Identity

Who this key belongs to - the first call an integration should make to confirm it is wired up.

Response 200 - {"ok":true, "email", "plan"}. A team member's key resolves to the account owner, the same way every other route scopes.

curl -H "Authorization: Bearer gm_live_YOUR_KEY" https://geo-mode.com/api/v1/whoami

Clusters

List the account's saved clusters, newest first.

Response 200 - {"clusters":[{"id","workspaceId","niche","brand","pages","avgScore","createdAt","updatedAt","publishedAt"}]}.

curl -H "Authorization: Bearer gm_live_YOUR_KEY" \
  https://geo-mode.com/api/v1/clusters

One saved cluster in full - pieces, scores, linking map - plus its loop state (publish date, first citation, days-to-citation, refresh-due). Deployment records and per-URL citation proof live on GET /api/deployments.

Response 200 - {"cluster":…}. Unknown id: 404 {"error":"not found"}.

curl -H "Authorization: Bearer gm_live_YOUR_KEY" \
  "https://geo-mode.com/api/v1/cluster?id=CLUSTER_ID"

Per-page, ready-to-insert payloads for headless importers - each page is pre-rendered and branded, so your CMS never re-implements rendering. This is the endpoint the WordPress plugin consumes.

Response 200 - a cluster summary plus pages, one entry per page:

{
  "cluster": { "id", "niche", "siteName", "workspaceId" },
  "pages": [{
    "slug", "title", "metaTitle", "metaDescription",
    "intent", "cluster", "schemaTypes",
    "gutenberg",   // WordPress block markup
    "html",        // body fragment (no doctype)
    "jsonld",      // schema, as a JSON string
    "related": [{ "question", "slug" }]
  }]
}

curl -H "Authorization: Bearer gm_live_YOUR_KEY" \
  "https://geo-mode.com/api/v1/cluster/pages?id=CLUSTER_ID"

Download a cluster export as a file (zip, or xml for wordpress).

Response 200 - the file, with a content-disposition filename.

curl -OJ -H "Authorization: Bearer gm_live_YOUR_KEY" \
  "https://geo-mode.com/api/v1/cluster/export?id=CLUSTER_ID&format=markdown"

Content generation

The channel-agnostic engine surface the Shopify app is built on - usable from any commerce stack. Generation endpoints are rate-limited (40/hour) and honour your BYOK key when one is set.

Buyer-facing Q&A for one product, grounded strictly in the catalog facts you supply - missing facts are acknowledged, never invented.

Response 200 - {"faqs":[{"question","answer"}], "mode"}.

curl -X POST https://geo-mode.com/api/v1/content/product-questions \
  -H "Authorization: Bearer gm_live_YOUR_KEY" -H "content-type: application/json" \
  -d '{"product":{"title":"Trail running shoe","price":"129","currency":"GBP"},"count":5}'

A "best X" / comparison content cluster for a product collection, grounded in the real products you pass. Counts toward the plan's monthly cluster quota; saved automatically unless save:false.

Response 200 - {"clusterId", "cluster"} (clusterId is null with save:false). Over quota: 402 with {"error","code","usage"}.

Product schema

Deterministic JSON-LD builders with the integrity gate built in: offers are omitted unless a real price and currency exist, ratings and reviews are withheld unless they carry real values and provenance - fabricated trust signals are structurally impossible. issues lists everything that was withheld or dropped, and why.

Body: {"product":{…}} - title, url, description, price/currency, images, brand, sku, faqs, breadcrumbs, and optionally real aggregateRating/reviews data.

Response 200 - {"jsonld":{"@context","@graph":[Product, FAQPage?, BreadcrumbList?]}, "issues":[…]}.

curl -X POST https://geo-mode.com/api/v1/schema/product \
  -H "Authorization: Bearer gm_live_YOUR_KEY" -H "content-type: application/json" \
  -d '{"product":{"title":"Trail running shoe","url":"https://shop.example/products/trail",
       "price":"129","currency":"GBP"}}'

Body: {"collection":{"title","url","description","products":[…],"faqs","breadcrumbs"}}. Products need a title and an http(s) URL to be listed.

Response 200 - {"jsonld":{"@graph":[CollectionPage, ItemList, FAQPage?, BreadcrumbList?]}, "issues":[…]}.

WordPress

Registers a WordPress site as a push target. The Connector plugin calls this for you when its Connect settings are saved - you only need it when building your own receiver.

Response 200 - {"ok":true, "site":{"id","siteUrl","name"}}. Validation failures are 400 with a readable error.

Response 200 - {"sites":[{"id","siteUrl","name","lastPushAt"}]}. Receiver tokens are never returned.

Push a saved cluster to a registered site: creates a wordpress deployment, nudges the site's Connector plugin to pull and publish the cluster (re-push updates the same posts by slug), and records the live URLs the site reports.

Response 200 - {"ok":true, "deploymentId", "urls":[…]}. If the site cannot be reached, or answers without live URLs, the response is 409 with code wp_unreachable or wp_bad_response, actionable copy naming the site, and the deploymentId - the deployment stays started until a push succeeds. Team members get 403 owner_only: publishing onto a client site is an owner action.

curl -X POST https://geo-mode.com/api/wp/push \
  -H "Authorization: Bearer gm_live_YOUR_KEY" -H "content-type: application/json" \
  -d '{"clusterId":"CLUSTER_ID","siteId":"SITE_ID"}'

Deployments

Record that a cluster is being deployed. The workspace is inherited from the cluster unless overridden.

Response 200 - {"deployment":{"id","clusterId","workspaceId","connector","status":"started","urls":[],"createdAt","deployedAt":null}}.

Attach the live page URLs and flip the deployment to deployed.

Response 200 - {"deployment":…, "markedImplemented":…} (markedImplemented reflects whether the cluster has been marked implemented - the two actions are deliberately separate).

List deployments, each URL annotated with citation proof from the weekly checks.

Response 200 - {"deployments":[…]}; deployed URLs carry {"url","cited":true|false,"citedAt","citedBy","question"} plus a per-deployment citedUrls count. Citation proof is matched per workspace - URLs on a deployment whose cluster is not filed to a workspace carry the bare {"url"} only.

curl -H "Authorization: Bearer gm_live_YOUR_KEY" \
  "https://geo-mode.com/api/deployments?workspaceId=WORKSPACE_ID"

Errors

Errors are JSON with a readable error message and, where a caller can act on it, a stable code:

MCP server

geo-mode is an MCP (Model Context Protocol) server: AI agents - Claude Code, Claude Desktop, claude.ai custom connectors, any MCP client - can manage the GEO loop directly. An agent can list a client's workspaces and clusters, pull a cluster as markdown, write it into a site repo, record where it went live, push to WordPress, and read the citation results that prove it worked.

A single stateless Streamable-HTTP endpoint speaking JSON-RPC 2.0 - no SSE stream, no session id. Auth is the same gm_live_… key as the REST API, but key-only: a browser session cookie is deliberately not accepted, so a logged-in browser can never be driven into this endpoint cross-site. A missing or invalid key returns HTTP 401 with a JSON-RPC error body (code -32001), not the REST error shape - agents parse it:

{"jsonrpc":"2.0","id":null,"error":{"code":-32001,
  "message":"unauthorized - send Authorization: Bearer gm_live_... (create an API key in Account)."}}

Protocol

Malformed JSON is -32700, a structurally invalid request (wrong jsonrpc, missing method, batch arrays) is -32600, an unknown method is -32601, an unknown tool name is -32602. Internal tool faults return an isError result with a generic message - stack traces never leave the box.

Tools

The intended agent flow: geomode_export_cluster, write the files into the client's repo, geomode_start_deployment, ship, geomode_set_deployment_urls with the live URLs - then the weekly checks run and geomode_list_deployments shows page-level citation proof. On WordPress, geomode_push_wordpress replaces that whole flow with one call. To fix a page that already exists rather than build a new one, geomode_retrofit_page returns an integrity-gated additive patch you apply through the same deploy-and-prove loop.

The deployment tools do not re-implement the REST logic - they dispatch to the same handlers as the endpoints above, so the two surfaces cannot drift.

Add it to Claude

Create an API key in Account, then:

claude mcp add --transport http geo-mode https://geo-mode.com/api/mcp \
  --header "Authorization: Bearer gm_live_YOUR_KEY"

Claude Desktop / claude.ai custom connector: URL https://geo-mode.com/api/mcp, header Authorization: Bearer gm_live_YOUR_KEY.

Smoke test:

curl -s https://geo-mode.com/api/mcp \
  -H "authorization: Bearer gm_live_YOUR_KEY" -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'