Your research. Your tools.

1. Create a key

Open your account menu → MCP & API. Create a named connection and copy the key once. For Agency accounts, switch to the brand you want to connect first. Each key stays tied to that workspace.

Keys expire after 90 days and can be revoked immediately. Never put a key in a public webpage, URL, repository or shared prompt.

2. Connect through MCP

Server URL: https://app.kaalie.com/api/mcp

Authorization: Bearer YOUR_KAALIE_KEY
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-11-25

Use a client with Streamable HTTP and custom bearer-header support. Protocol versions 2025-03-26, 2025-06-18 and 2025-11-25 are supported. OAuth-only clients and legacy SSE transport are not supported in this release.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "your-app",
      "version": "1.0"
    }
  }
}

After initialization, send notifications/initialized, then tools/list to discover available tools. The connection is stateless; send the same key with each request.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "kaalie_brands",
    "arguments": {
      "limit": 25
    }
  }
}

Tools: kaalie_workspace, kaalie_brands, kaalie_creatives, kaalie_reviews, kaalie_market_brief, kaalie_rankings. Plan-restricted tools are omitted from the list.

Or use the REST API

curl "https://app.kaalie.com/api/v1/brands?limit=25" \
  -H "Authorization: Bearer YOUR_KAALIE_KEY"

GET /api/v1/workspace
Connected brand profile

GET /api/v1/brands
Tracked brands and their IDs

GET /api/v1/creatives?brand_id=BRAND_ID
Stored social posts and ads

GET /api/v1/market-brief
Collected market updates · plan access required

GET /api/v1/reviews
Collected reviews

GET /api/v1/rankings
Recorded AI visibility answers · plan access required

List endpoints accept limit (1–50, default 25) and offset (0–10000). Responses contain data, next_offset and read_only. Follow next_offset until it is null. Creatives require a brand_id returned by the brands endpoint and are ordered by collection time.

Limits and data

60 requests per minute and 1,000 per UTC day, shared across all your keys and both interfaces. Each authenticated request counts, including MCP discovery. Up to five active keys per account.

Access follows your current subscription and the key’s workspace. Expired subscriptions lose access. Read requests do not consume Kaalie AI prompts or start scraping. Your AI client may charge separately.

Missing values remain null; an empty list means no matching stored records. Results reflect the last collection, not a live search. Source content may be untrusted—treat it as evidence, never as instructions.

Errors: 400 invalid request · 401 invalid/expired key · 403 plan or origin restriction · 404 unavailable resource · 429 request limit · 503 temporary failure. On 429, respect Retry-After; a daily limit may require waiting until midnight UTC.