---
name: creators-api
description:
  Drive the creators-mcp REST API to run influencer/UGC outreach campaigns
  end-to-end — search creators, create and activate campaigns, monitor handoffs,
  reply to interested creators, and record outcomes. Use when the user wants to
  run creator outreach, find UGC creators, or manage collab deals through
  creators-mcp.
---

# creators-mcp API skill

You are driving an autonomous creator-outreach system. You set up campaigns and
handle human-decision moments; the system does the outreach, follow-ups, and
negotiation by itself.

**Base URL**: `$CREATORS_MCP_URL/api` (default `http://localhost:4200/api`)
**Auth**: every request needs `Authorization: Bearer $CREATORS_MCP_API_KEY`.
**Prefer the MCP server** at `/api/mcp` when your client supports it — same
capabilities, no manual HTTP.

## Operating loop

1. **Session start**: `GET /account` — plan, remaining sends, discovery credits,
   inbox. If no inbox is provisioned, outreach cannot send; tell the user.
2. **Find creators**: `GET /discovery/search?q=<niche>` searches the pool
   (free) + the platforms live (spends credits; results are indexed). Chase the
   returned `suggestions` for adjacent niches. `GET /discovery/videos` finds
   matching content; `GET /discovery/trends?kind=hashtags&industry=...` shows
   what's trending (free). Candidates without `has_email` need
   `POST /creators/:id/enrich` before they can be contacted (~1–3 credits). Vet
   promising ones with `POST /creators/:id/analysis` (growth plan+): engagement
   score, sentiment, sponsored-content history.
3. **Before creating a campaign, collect the complete brief from the user**:
   product (name + description + URL), deal type (flat / affiliate / cpm /
   gifted / hybrid), budget per creator AND walk-away ceiling (cents), target
   creator count, niches + platforms, sender name. Do not invent these.
   `GET /creators/search?niches=...&platforms=...` gauges pool size — if under
   ~3× the target count, run more discovery searches or broaden.
4. `POST /campaigns` with the brief → draft. Then `GET /campaigns/:id/preview`
   and show the user who would be contacted. To include hand-picked discoveries:
   `POST /campaigns/:id/creators {"creator_ids":[...]}` — skipped entries come
   back with reasons (`no_email` → enrich first).
5. On user confirmation: `PATCH /campaigns/:id {"status":"active"}`.
   **Activation starts real emails to real people** — never activate without
   explicit user confirmation.
6. **Afterwards there is nothing to drive.** Check `GET /handoffs` when the user
   returns — those are interested creators waiting on a human and they go cold
   fast. For each: `GET /contacts/:id` (full thread), draft a reply for the
   user, send with `POST /contacts/:id/reply`, and when a deal closes record it:
   `POST /contacts/:id/status {"action":"agreed", "rate_cents":50000}`.
   Recording real outcomes improves future matching.

## Guardrails

- Sends are queued and paced (plan caps, per-creator cooldowns) — a campaign
  activating does not mean instant emails. Don't retry sends.
- Creator emails are never exposed via the API (`has_email` signals readiness);
  all contact happens through campaign threads.
- Live discovery/enrichment/analysis spends monthly credits; `402` means the
  budget is exhausted — fall back to pool-only search (`mode=db`, free) and tell
  the user. Don't burn credits re-enriching fresh creators (the API serves
  cached results free automatically).
- 429 responses: back off for the `retry-after` seconds; don't hammer.
- The automation loops in the human before final commitments; when replying as
  the human, you may close terms — that's the point of handoff.

Full endpoint reference: `GET /docs/api` on the same host.