API, SDK and MCP | GeniSights Docs

Authentication

Create a key under Settings, API keys (people who manage the account can do this). It belongs to one workspace, is shown once, and can be revoked at any time. Send it as a bearer token:

curl https://api.genisights.io/v1/visibility?range=week \
  -H "Authorization: Bearer gsk_live_..."

X-API-Key: gsk_live_... also works. Keep keys out of client-side code and public repositories.

Limits and errors

600 requests per hour per key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds).
401: the key is missing, malformed, unknown or revoked.
429: over the hourly limit. Wait for Retry-After seconds.
400: a parameter is invalid; the message says which.

Endpoints

GET /v1/brand

The workspace's brand: name, domain, category, aliases, region and language.

Returns: A brand object.

GET /v1/prompts

The prompts being tracked.

Returns: An array of prompts with text, tag, cadence, market, language and status.

GET /v1/visibility

Visibility score and per-engine breakdown, with a daily trend.

range: The period to cover. One of week, month.

Returns: Today's score, the per-engine breakdown and daily scores per engine.

GET /v1/share-of-voice

Your brand's share of all brand mentions against each competitor.

range: The period to cover. One of week, month.

Returns: Share of voice entries, ranked, with your own brand flagged.

GET /v1/runs

Recent prompt runs, each with whether the brand was mentioned.

limit: How many runs to return, 1 to 100. Default 25.
promptId: Only runs of this prompt.

Returns: An array of runs with engine, status, mentioned, position, sentiment and completion time.

GET /v1/citations

Cited pages with the time each was first cited.

limit: How many pages to return, 1 to 200. Default 50.
since: Only pages first cited on or after this ISO date.

Returns: An array of pages with url, domain, times cited and first_cited_at.

A machine-readable OpenAPI 3 description is at https://api.genisights.io/v1/openapi.json (it needs a key like every other call).

JavaScript SDK

@aeo-geo/sdk is a small, typed client with no dependencies. It is part of this repository’s packages/sdk workspace.

import { GeniSights } from "@aeo-geo/sdk";

const gs = new GeniSights({ apiKey: process.env.GENISIGHTS_API_KEY, baseUrl: "https://api.genisights.io" });
const { visibilityScore, engines } = await gs.visibility({ range: "week" });
const sov = await gs.shareOfVoice({ range: "month" });

Errors are thrown as GeniSightsError with the HTTP status, and retryAfterSeconds on a rate limit.

MCP server

@aeo-geo/mcp-server (in packages/mcp-server) lets an AI assistant that supports the Model Context Protocol, such as Claude Desktop or Cursor, read your data in conversation. It runs on your machine over stdio and offers six read-only tools: get_brand, list_prompts, get_visibility, get_share_of_voice, list_runs and get_citations.

{
  "mcpServers": {
    "genisights": {
      "command": "node",
      "args": ["/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "GENISIGHTS_API_KEY": "gsk_live_...",
        "GENISIGHTS_API_URL": "https://api.genisights.io"
      }
    }
  }
}

The assistant sees your visibility data when you ask it to use these tools, so only connect assistants you are happy to share that data with.

Questions? Contact us.