ChatSights
Developer docs

One raw-data contract for local agents

ChatSights routes managed AI scraper jobs and returns normalized records. Your code or local agent performs every analysis step.

Quickstart

Register the repository's local MCP server, then ask your agent to fetch a prompt from one or more AI surfaces.

claude mcp add chatsights -- node /absolute/path/to/try-chat-sights/mcp/index.mjs --api-url http://localhost:8080 --key cs_live_...

Replace the example path with an absolute path to mcp/index.mjs. Local development uses explicit demo records until provider credentials and dataset IDs are configured on the server.

Fetch contract

The public endpoint accepts a prompt, surface list and locale. It does not accept brands, competitors or analysis settings.

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

Required · up to 4,096 characters

surfaces

Required · one or more catalog keys

country

Provider targeting hint · default US

language

Output-language hint · default en

web_search

Passed through on supported surfaces

Normalized response

Each delivered record preserves the answer, citations and selected provider metadata.

{
  "id": "run_84c1...",
  "provider": "managed_scraper",
  "mode": "live",
  "status": "completed",
  "recordsDelivered": 3,
  "creditsCharged": 3,
  "answers": [{
    "surfaceKey": "chatgpt",
    "answerText": "...",
    "sources": [{
      "title": "...",
      "url": "https://...",
      "position": 1
    }],
    "providerRecordId": "bd_...",
    "providerFields": {
      "web_search_triggered": true
    }
  }]
}

Product boundaries

The contract deliberately keeps data collection separate from interpretation.

ChatSights returns

Answer text
Citations and sources
Provider record ID
Run status and billing

Your agent produces

Rankings
Sentiment
Comparisons
Recommendations and reports

Provider setup

Provider secrets stay in the server environment. Dataset IDs come from each scraper's Configuration panel.

PROVIDER_API_KEY=...
PROVIDER_DATASET_CHATGPT=gd_...
PROVIDER_DATASET_PERPLEXITY=gd_...
PROVIDER_DATASET_GEMINI=gd_...
PROVIDER_DATASET_GOOGLE_AI_OVERVIEW=gd_...
PROVIDER_DATASET_GOOGLE_AI_MODE=gd_...
PROVIDER_DATASET_COPILOT=gd_...

The token and dataset IDs are never returned to the MCP client or included in logs.

Delivery webhooks

Scheduled and async runs emit operational events, not semantic claims about the answer.

job.completed

All requested records delivered

job.partial

Some surfaces failed

job.failed

No records delivered or billed

Credits

One successfully delivered provider record equals one ChatSights credit.

credits = prompts × surfaces successfully delivered

A single prompt requested from three surfaces costs at most three credits. Failed records cost zero.

Ready to inspect the contract?

The playground works in explicit demo mode before provider setup.

Open the playground