PollyX API

Authentication

All API requests must include an API key in the Authorization header as a Bearer token.

Authorization: Bearer px_live_your_api_key_here

You can create and manage API keys in your account settings. API keys start with px_live_.

Creates a new sentiment report. Report generation is asynchronous - you will receive a poll_url to check progress and retrieve results when done.

Request body

Response 202 Accepted

{
  "report_id": "rpt_abc123xyz",
  "status": "generating",
  "poll_url": "/api/v1/reports/rpt_abc123xyz"
}

Poll the status of a report. Returns status: "generating" while the report is still being processed, and the full report content once status: "completed".

Response 200 OK

{
  "report_id": "rpt_abc123xyz",
  "status": "completed",
  "sentiment_score": 7.4,
  "content": {
    "executive_summary": "Acme Corp enjoys strong positive sentiment...",
    "sentiment_score": 7.4,
    "platform_breakdown": [...],
    "positive_themes": [...],
    "negative_themes": [...],
    "competitor_comparison": [...],
    "trending_topics": [...],
    "crisis_alerts": [],
    "recommendations": [...],
    "improvement_plan": [...],
    "analytics_disclaimer": "Every score, percentage, ranking and breakdown..."
  },
  "created_at": "2026-05-22T08:00:00.000Z",
  "updated_at": "2026-05-22T08:02:15.000Z"
}

Note: verbatim post text from platforms whose terms restrict redistribution (X, Instagram, TikTok) is not included in API payloads - each source row links to the original post instead. Scores, themes, summaries and all other analysis are unaffected.

Full curl example

Step 1 - create the report:

curl -X POST https://pollyx.org/api/v1/reports \
  -H "Authorization: Bearer px_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Corp",
    "industry": "SaaS",
    "location": "United States",
    "website": "https://acmecorp.com",
    "what_to_know": "Focus on customer support sentiment",
    "competitors": ["Rival Corp", "Other Inc"],
    "language": "en"
  }'

Step 2 - poll until complete (typically a few minutes):

curl https://pollyx.org/api/v1/reports/rpt_abc123xyz \
  -H "Authorization: Bearer px_live_your_key_here"

Completion webhook

Part of the API plan: without it a request carrying a callback returns 402. Pass callback_url when creating a report and PollyX POSTs to it when generation finishes - on success and on failure - instead of you polling for ~15 minutes. The payload is deliberately a pointer without report data, so you fetch the result with your own key; that also means the webhook needs no signature verification.

{
  "status": "completed",
  "sentiment_score": 6.4,
  "report_id": "rpt_abc123xyz",
  "poll_url": "/api/v1/reports/rpt_abc123xyz"
}

Failures send {"status": "failed", "error": "generation_failed" | "insufficient_data"}. Failed paid reports follow the standard policy: one free retry, then an automatic refund.

AI Visibility checks

The second product, on the same key and the same 1-credit billing. A check asks the major AI assistants twelve buyer questions about a brand and reports how each one describes it, which rivals it names instead, and which pages it read to decide. Generation takes up to 50 minutes.

Body: brand (required), industry, market, competitors (up to 3) and callback_url. Set market where you can - it is woven into all twelve questions, so the assistants answer about that market rather than a bigger neighbour. Returns 202 with a check_id.

Compact by default: overall score, summary, share of voice, cited domains and per-engine scores. Add ?include_full=true for the complete content, including every page each assistant consulted.

Lists your checks, newest first. Optional ?limit= (default 20, max 50).

curl -X POST https://pollyx.org/api/v1/ai-visibility \
  -H "Authorization: Bearer px_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "Tesco",
    "industry": "supermarkets",
    "market": "Ireland",
    "competitors": ["Dunnes Stores", "Aldi"]
  }'

MCP server (AI agents)

PollyX speaks the Model Context Protocol, so Claude, ChatGPT or any MCP-compatible agent can order and read both products directly. Point your client at the endpoint below with your API key - the server exposes six tools: create_report (1 credit), get_report, list_reports, create_ai_visibility_check (1 credit), get_ai_visibility_check and list_ai_visibility_checks.

{
  "mcpServers": {
    "pollyx": {
      "type": "http",
      "url": "https://pollyx.org/api/mcp",
      "headers": { "Authorization": "Bearer px_live_your_key_here" }
    }
  }
}

Billing and rate limits are identical to the REST API. Generation is asynchronous: create_report returns a report id immediately and your agent polls it with get_report.