# creators-mcp API Creator-outreach infrastructure: define a campaign once, and background workers continuously match creators, send personalized emails from your AgentMail inbox, classify replies, negotiate within your brief, and hand interested creators to you to close. - **Base URL**: `https:///api` - **Auth**: `Authorization: Bearer cmk_...` — create keys in the dashboard (Settings → API keys). Keys work for both REST and MCP. - **Rate limit**: 120 requests/minute per credential. Over-limit requests get `429` with a `retry-after` header. - **Errors**: JSON `{ type, message }` with meaningful status codes (`400` validation, `401` bad key, `402` discovery budget spent, `403` plan required, `404` not yours, `429` rate limited, `503` scraping upstream unavailable). ## The model The product is a funnel: **find → analyze → outreach**. **Find**: `/discovery/search` searches the shared creator pool first (free) and the platforms live (TikTok/Instagram/YouTube via scraping) when the pool is thin — every live hit is indexed, so the pool grows with every search. `/discovery/videos` finds matching content and the creators behind it; `/discovery/trends` serves trending hashtags (by industry + country), regional trending feeds, and trending shorts from a shared cache (free). **Analyze**: `/creators/:id/enrich` refreshes a profile and hunts the collab email (platform field → bio regex → link-in-bio scrape → AI extraction). `/creators/:id/analysis` builds a report card — engagement score, avg views, posting cadence, sponsored-content share, comment sentiment (growth plan+). Live calls are metered by **monthly discovery credits** (see `/account`); pool reads are free. **Outreach**: a **campaign** is a structured brief (product, deal type, budget + walk-away ceiling, target creator count, niches/platforms, sender name). Activating it starts continuous automated outreach — there is nothing to poll or drive. A **contact** is one creator inside one campaign, moving through a state machine (`queued → awaiting_reply → negotiating → handoff/escalated → agreed/declined/no_response/...`). Contacts in `handoff`/`escalated` are waiting on a human. Sends are asynchronous and paced by plan caps and per-creator cooldowns; the automation never makes a final commitment to a creator. ## Endpoints | Method | Path | Purpose | | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/creators/search` | Search the creator pool (niche, platform, followers, freshness, reply rate). Emails are never exposed. | | `GET` | `/discovery/search` | Unified search: pool + live platform search (`mode=db\|live\|hybrid`, `platforms`, `follower_min`/`follower_max`). Returns ranked candidates + adjacent-search suggestions. | | `GET` | `/discovery/videos` | Live content search: matching videos/reels/shorts + the creators behind them (`recency`, `sort`, `platforms`, `limit`). | | `GET` | `/discovery/suggestions` | Adjacent-search suggestions for a keyword. | | `GET` | `/discovery/trends` | Trending hashtags (`industry`, `country`), regional feeds, trending shorts — from the shared cache, free. | | `GET` | `/creators/:id` | Full creator record: profile + outreach insights + analysis. | | `POST` | `/creators/:id/enrich` | Profile refresh + email hunt (bio → link-in-bio → AI). ~1–3 credits; `force` re-scrapes even when fresh. | | `POST` | `/creators/:id/analysis` | Build the report card (growth+); `include_audience` adds TikTok audience geo (scale, 26 credits); `force` bypasses the ~7-day cache. | | `GET` | `/creators/:id/lookalikes` | Similar creators seeded from this one (growth+). | | `POST` | `/campaigns/:id/creators` | Pin specific creators into a campaign (safety rails still apply). | | `POST` | `/campaigns` | Create a campaign from a complete brief (starts as `draft`). | | `GET` | `/campaigns` | List campaigns with per-state contact counts; filter with `?status=draft\|active\|paused\|fulfilled\|expired`. | | `GET` | `/campaigns/:id` | One campaign. | | `PATCH` | `/campaigns/:id` | Change status: `active`, `paused`, `expired`. | | `GET` | `/campaigns/:id/preview` | Dry run: who would be contacted next (+ optional sample email). Sends nothing. | | `GET` | `/campaigns/:id/stats` | Funnel: sends, replies, reply rate, handoffs, agreed. | | `GET` | `/handoffs` | Contacts waiting on you (interested creators, terms in range); `include_escalated=false` hides escalated threads. | | `GET` | `/contacts/:id` | Full email thread + deal context. | | `POST` | `/contacts/:id/reply` | Send a human reply into the thread (same inbox, unified thread). | | `POST` | `/contacts/:id/status` | Record the outcome: `agreed` (requires `rate_cents`), `declined`, `lost`. | | `GET` | `/account` | Plan, remaining send budget + discovery credits, outreach inbox. | ### Typical flow 1. `GET /discovery/search?q=skincare&platforms=tiktok` — find creators (pool + live); chase the returned suggestions for adjacent niches. 2. `POST /creators/:id/enrich` on shortlisted candidates without an email; `POST /creators/:id/analysis` to vet the promising ones. 3. `POST /campaigns` with the full brief → campaign `draft`. 4. `GET /campaigns/:id/preview` — sanity-check the match list; optionally `POST /campaigns/:id/creators` to pin your hand-picked finds. 5. `PATCH /campaigns/:id {"status":"active"}` — outreach starts. 6. Poll `GET /handoffs` (or watch the dashboard): reply via `POST /contacts/:id/reply`, close via `POST /contacts/:id/status`. Agreed terms feed creator insights (reply rates, typical rates, deal types) that improve future matching for everyone. On the scale plan, campaigns auto-hunt: when the pool runs dry for a brief's targeting, a background job searches the platforms and enriches matches automatically. ### Discovery credits Live scrape calls debit a monthly per-plan credit budget (1 credit ≈ 1 upstream call): starter 500, growth 5,000, scale 25,000. Pool searches and trend reads are free. `402` means the month's budget is spent. Plan gates: analysis + lookalikes need growth+; audience demographics + auto-hunt need scale. ## MCP The same surface is exposed as an MCP server at `/api/mcp` (streamable HTTP). Tools map 1:1 onto the routes above (`discover_creators`, `search_creators`, `search_videos`, `get_trends`, `get_search_suggestions`, `enrich_creator`, `analyze_creator`, `find_lookalikes`, `get_creator`, `add_creators_to_campaign`, `create_campaign`, `campaign_preview`, `set_campaign_status`, `list_campaigns`, `campaign_stats`, `list_handoffs`, `get_thread`, `send_reply`, `set_contact_status`, `get_account`). Two ways to authenticate: - **API key** (CLI/IDE clients): `claude mcp add --transport http creators https:///api/mcp --header "Authorization: Bearer cmk_..."` - **OAuth** (browser clients): add `https:///api/mcp` as a Claude custom connector and sign in with one click — discovery, dynamic client registration, and PKCE are handled automatically. The dashboard's Settings page generates ready-to-paste config for Claude, Claude Code, Cursor, and VS Code.