# Content Copilot API Documentation

## Base URL
POST https://www.contentcopilot.so/api/mcp

## Authentication
Bearer token via Authorization header: "Authorization: Bearer cc_live_your_key_here"

## Setup (Claude Code)
mkdir -p ~/.claude/skills/content-copilot && curl -o ~/.claude/skills/content-copilot/SKILL.md https://www.contentcopilot.so/claude-code-skill.md
export CONTENT_COPILOT_API_KEY=cc_live_your_key_here

## MCP Client Config (Cursor, Windsurf, etc.)
{
  "mcpServers": {
    "content-copilot": {
      "url": "https://www.contentcopilot.so/api/mcp",
      "headers": {
        "Authorization": "Bearer cc_live_your_key_here"
      }
    }
  }
}

## Tools (5 available)

### list_niches
Returns all configured niches with approved discovery counts and whether the user is subscribed.
Parameters: none
Example: {"tool": "list_niches", "params": {}}

### get_viral_ideas
Returns viral video discoveries sorted by most recent. Paginated (20 per page). Supports sorting, filtering by niche, views, viral score, or keyword search.
Parameters:
- nicheId (string, optional): Filter by niche ID
- page (number, optional): Page number (default: 1, 20 per page)
- sort (string, optional): "recent" (default), "views", or "viralScore"
- minViews (number, optional): Minimum view count filter
- minViralScore (number, optional): Minimum viral score (0-100)
- search (string, optional): Keyword search (caption, creator, transcript)
Example: {"tool": "get_viral_ideas", "params": {"page": 1, "sort": "views", "minViews": 100000}}

### search_viral
Search viral content by keyword and optionally filter by niche.
Parameters:
- query (string, optional): Search keyword or phrase
- nicheId (string, optional): Filter by niche ID
- limit (number, optional): Max results (default: 10)
Example: {"tool": "search_viral", "params": {"query": "SaaS marketing"}}

### get_analytics
Returns analytics for connected social accounts — views, likes, comments, engagement rate, and per-platform breakdowns.
Parameters:
- days (number, optional): Lookback days (default: all time)
Example: {"tool": "get_analytics", "params": {"days": 7}}

### generate_script
Generates a video script in the user's brand voice with a shot list. If a viral reel is referenced, uses its FORMAT (hook pattern, pacing) but writes about the given topic. Limited to 300 generations per user per month.
Parameters:
- viralDiscoveryId (string, optional): ID of a viral reel to use as format reference
- topic (string, optional): What the script should be about. Takes priority over the source reel's content.
Example: {"tool": "generate_script", "params": {"viralDiscoveryId": "disc_abc123", "topic": "how to go viral on Instagram"}}

## Rate Limits
- Pro: 5,000 requests/month, Full (20/page) pagination, 300 / month scripts

## Error Codes
- 401: Unauthorized — Missing or invalid API key
- 403: Forbidden — Feature not available on your plan
- 404: Not Found — No social accounts connected or no niches configured
- 429: Too Many Requests — Monthly rate limit exceeded (5,000 requests or 300 scripts)
- 500: Internal Server Error — Unexpected server error