API Documentation

curl -H "X-API-Key: ct_live_abc123..." "<your-base-url>/api-posts?keyword=AI+tools"

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4832
X-RateLimit-Reset: 2026-04-05T00:00:00.000Z

{
  "data": [
    {
      "url": "https://reddit.com/r/SaaS/comments/abc123",
      "title": "Looking for community monitoring tools",
      "body": "We need something to track brand mentions across Reddit and HN...",
      "author": "startup_founder",
      "source": "reddit",
      "kind": "p",
      "posted_at": "2026-04-03T14:22:00Z",
      "ai_score": 8.5,
      "ai_reason": "Direct buying intent for community monitoring tools.",
      "intent": "buying",
      "urgency": "high",
      "buying_stage": "evaluating",
      "action_type": "engage",
      "suggested_play": "Share a case study showing how CT solves this use case.",
      "competitor_named": "Brandwatch",
      "buying_signals": ["budget_mentioned", "timeline_given"],
      "engagement_status": null,
      "subreddit": "SaaS"
    }
  ],
  "meta": {
    "total": 142,
    "returned": 50,
    "limit": 50,
    "offset": 0,
    "keyword": "community monitoring",
    "filters_applied": {}
  }
}

curl -H "X-API-Key: ct_live_your_key_here" "<your-base-url>/api-intelligence"

{
  "error": {
    "code": "MISSING_QUERY_ID",
    "message": "The query_id parameter is required."
  },
  "queries": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "primary_brand": "YourBrand",
      "competitor_brands": ["Competitor A", "Competitor B"],
      "communities": ["reddit", "hackernews", "producthunt"]
    }
  ]
}

{
  "data": {
    "snapshot_date": "2026-04-03",
    "time_range": "30d",
    "range_days": 30,
    "ai_summary": "YourBrand leads with 42% SOV across tracked communities...",
    "brands": {
      "YourBrand": { "mentions": 84, "sov_pct": 42.0 },
      "Competitor A": { "mentions": 62, "sov_pct": 31.0 }
    },
    "by_community": {
      "reddit": { "YourBrand": 35, "Competitor A": 28 },
      "hackernews": { "YourBrand": 22, "Competitor A": 12 }
    }
  },
  "query": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "primary_brand": "YourBrand",
    "competitor_brands": ["Competitor A", "Competitor B"],
    "communities": ["reddit", "hackernews", "producthunt"],
    "range_days": 30
  },
  "meta": {
    "snapshots_returned": 1,
    "latest_snapshot_date": "2026-04-03"
  }
}

{
  "data": [
    {
      "snapshot_date": "2026-04-03",
      "time_range": "30d",
      "range_days": 30,
      "ai_summary": "...",
      "brands": { ... },
      "by_community": { ... }
    },
    {
      "snapshot_date": "2026-03-27",
      "time_range": "30d",
      "range_days": 30,
      "ai_summary": "...",
      "brands": { ... },
      "by_community": { ... }
    }
  ],
  "query": { ... },
  "meta": {
    "snapshots_returned": 2,
    "from": "2026-03-01",
    "to": "2026-04-03"
  }
}

curl -H "X-API-Key: ct_live_your_key_here" \
  "<your-base-url>/api-intelligence?query_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890"

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of what went wrong."
  }
}

import requests

BASE_URL = "<your-base-url>"  # Your CommunityTracker API base URL
API_KEY = "ct_live_your_key_here"

HEADERS = {"X-API-Key": API_KEY}


def get_posts(keyword, source=None, min_score=None, limit=50):
    """Fetch community posts for a keyword."""
    params = {"keyword": keyword, "limit": limit}
    if source:
        params["source"] = source
    if min_score is not None:
        params["min_score"] = min_score

    resp = requests.get(f"{BASE_URL}/api-posts", headers=HEADERS, params=params)
    resp.raise_for_status()

    # Check rate limits
    remaining = resp.headers.get("X-RateLimit-Remaining")
    print(f"Requests remaining today: {remaining}")

    return resp.json()


def get_sov(query_id, from_date=None, to_date=None):
    """Fetch SOV snapshots for an intelligence query."""
    params = {"query_id": query_id}
    if from_date:
        params["from"] = from_date
    if to_date:
        params["to"] = to_date

    resp = requests.get(f"{BASE_URL}/api-intelligence", headers=HEADERS, params=params)
    resp.raise_for_status()
    return resp.json()


def list_queries():
    """List your active intelligence queries and their IDs."""
    resp = requests.get(f"{BASE_URL}/api-intelligence", headers=HEADERS)
    return resp.json().get("queries", [])


# Usage
posts = get_posts("AI tools", source="reddit", min_score=7)
for post in posts["data"]:
    print(f'[{post["ai_score"]}] {post["title"]} -- {post["url"]}')

queries = list_queries()
if queries:
    sov = get_sov(queries[0]["id"])
    print(sov["data"]["ai_summary"])