Build with CiteFit

Generate a key

1. 1Go to Dashboard → Account → API Keys.
2. 2Click New API key, give it a label, and copy the full key immediately — it is shown only once.
3. 3You may hold up to 10 active keys per account. Revoke unused keys to stay within the limit.

Using the key

Pass the key as a Bearer token in every request:

Authorization: Bearer bp_<your-key>

Requests without a valid key receive 401 Unauthorized.

Base URL

https://www.citefit.com

Brands

curl https://www.citefit.com/api/brands \
  -H "Authorization: Bearer bp_<your-key>"

Scans

# Trigger a scan
curl -X POST https://www.citefit.com/api/run-scan \
  -H "Authorization: Bearer bp_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"brand_id": "<uuid>"}'

# → {"job_id": "f9e8d7c6-...", "status": "pending"}

# Poll for completion
curl https://www.citefit.com/api/scan-status/f9e8d7c6-... \
  -H "Authorization: Bearer bp_<your-key>"

# → {"status": "running", "progress": {"current": 4, "total": 12, "step": "chatgpt"}}

status progresses: pending → running → complete or error. The endpoint honours If-None-Match / ETag for efficient polling.

Visibility & insights

Plan limits

Exceeding limits returns 429 with a descriptive error message.

Connect a client

Add CiteFit to your MCP client config (Claude Desktop, Cursor, Continue, etc.):

// mcp-config.json
{
  "mcpServers": {
    "citefit": {
      "url": "https://www.citefit.com/api/mcp",
      "headers": {
        "Authorization": "Bearer bp_<your-key>"
      }
    }
  }
}

The server advertises its capabilities during the initialize handshake and lists its tools via tools/list. Machine-readable metadata is available at /.well-known/mcp/server-card.json.

SSE connection limits

The GET /api/mcp endpoint accepts up to 2 concurrent SSE connections per API key. Exceeding this returns 429 with Retry-After: 60. The server sends a keep-alive ping every 25 seconds and releases the connection slot automatically on client disconnect.

List all brands tracked by the authenticated user.

// request
{"name": "list_brands", "arguments": {}}

// response text (JSON)
[
  {
    "id": "a1b2c3d4-...",
    "name": "Acme Corp",
    "domain": "acme.com",
    "competitors": ["Globex"],
    "created_at": "2025-03-01T12:00:00Z"
  }
]

Get a single brand including all its prompts.

Get daily visibility snapshots (mention rate, average position) for a brand. Returns up to 90 days × 3 platforms by default.

// response text sample
[
  {
    "date": "2025-03-15",
    "platform": "chatgpt",
    "mention_rate": 0.62,
    "avg_position": 2.1,
    "total_prompts": 8,
    "mentioned_count": 5,
    "scan_count": 1
  }
]

Most recent scan results for a brand across all platforms.

AI-generated recommendations for improving brand visibility.

Unseen visibility alerts for a brand.

Trigger a manual brand scan. Runs asynchronously — poll the returned poll_url to track progress. The same plan limits as the REST API apply.

// response text
{
  "job_id": "f9e8d7c6-...",
  "status": "pending",
  "poll_url": "/api/scan-status/f9e8d7c6-..."
}

HTTP status codes

JSON-RPC error codes (MCP)

cURL — list brands

curl https://www.citefit.com/api/brands \
  -H "Authorization: Bearer bp_<your-key>"

Python — MCP client

import httpx, json

API_KEY = "bp_<your-key>"
BASE    = "https://www.citefit.com/api/mcp"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def rpc(method, params=None, *, id=1):
    r = httpx.post(BASE, headers=HEADERS, json={
        "jsonrpc": "2.0", "id": id, "method": method, "params": params or {}
    })
    r.raise_for_status()
    return r.json()

# Handshake
rpc("initialize", {
    "protocolVersion": "2025-03-26",
    "clientInfo": {"name": "my-script", "version": "1.0.0"},
    "capabilities": {},
})

# Fetch brands
result = rpc("tools/call", {"name": "list_brands", "arguments": {}}, id=2)
brands = json.loads(result["result"]["content"][0]["text"])

# Visibility for the first brand
vis = rpc("tools/call", {
    "name": "get_visibility",
    "arguments": {"brand_id": brands[0]["id"], "platform": "chatgpt"},
}, id=3)
print(json.loads(vis["result"]["content"][0]["text"]))

TypeScript — trigger scan and poll

const API_KEY = "bp_<your-key>";
const MCP_URL = "https://www.citefit.com/api/mcp";

async function rpc(method: string, params = {}, id = 1) {
  const res = await fetch(MCP_URL, {
    method: "POST",
    headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ jsonrpc: "2.0", id, method, params }),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

// Handshake
await rpc("initialize", {
  protocolVersion: "2025-03-26",
  clientInfo: { name: "my-agent", version: "1.0.0" },
  capabilities: {},
});

// Trigger a scan
const { result } = await rpc("tools/call", {
  name: "trigger_scan",
  arguments: { brand_id: "<uuid>" },
}, 2);

const { job_id, poll_url } = JSON.parse(result.content[0].text);

// Poll until done
while (true) {
  const r = await fetch(`https://www.citefit.com${poll_url}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  const job = await r.json();
  if (job.status === "complete" || job.status === "error") { console.log(job); break; }
  await new Promise((res) => setTimeout(res, 3_000));
}