Developers — Creahunt API and MCP connector

Getting started

Authentication and base URL

Every request carries an org-scoped key as a bearer token. Keys look like ch_live_… and are shown once, at creation — Creahunt stores only a SHA-256 hash, so a lost key is revoked and replaced, never recovered.

Base URL

https://creahunt.com/api/v1

Every request

curl -s https://creahunt.com/api/v1/me \
  -H "Authorization: Bearer ch_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

A key is scoped to one workspace. It reads that workspace's data and nothing else — ids from another workspace answer 404, never 403.
v1 is read-only. There are no write endpoints, and the keys carry no write scope. Starting a discovery run, editing a collection or contacting a creator stays in the app.
Nothing here spends Tokens. The creator endpoint reads the analytics you have already paid for; it never triggers a new analysis.
Responses are JSON with Cache-Control: no-store. Treat them as workspace data.

Reference

Endpoints

Five reads. Set CREAHUNT_KEY in your shell and the examples below run as-is.

GET/api/v1/me

Who the key belongs to. The cheapest way to check a key works.

Request

curl -s https://creahunt.com/api/v1/me \
  -H "Authorization: Bearer $CREAHUNT_KEY"

Response (trimmed)

{
  "org": { "id": "acme-org" },
  "key": { "id": "0f2c…", "label": "CI bot" },
  "plan": { "tier": "agency" },
  "api": { "version": "v1", "readOnly": true,
           "rateLimit": { "limit": 60, "windowSeconds": 60 } }
}

GET/api/v1/discoveries

Your discovery runs, newest first. Filter with ?status= (completed, running, stopped, failed, draft); page with ?limit= (1–100, default 25) and the ?cursor= you get back.

Request

curl -s "https://creahunt.com/api/v1/discoveries?status=completed&limit=2" \
  -H "Authorization: Bearer $CREAHUNT_KEY"

Response (trimmed)

{
  "data": [
    {
      "id": "8f1b…",
      "title": "Cold-plunge creators, UK",
      "status": "completed",
      "createdAt": "2026-09-14T10:02:11.000Z",
      "updatedAt": "2026-09-14T10:41:52.000Z",
      "brief": "UK creators posting cold plunge and sauna recovery…",
      "platforms": ["instagram", "tiktok"],
      "topScore": 4.6,
      "counts": { "candidates": 212, "strong": 18, "eliminated": 64 },
      "url": "/discover-pro-v2?report=8f1b…"
    }
  ],
  "nextCursor": "eyJvIjoyfQ"
}

GET/api/v1/discoveries/{id}

One run in full: the brief, the parsed criteria, per-band counts and every scored creator. An id from another workspace answers 404 — the API never confirms it exists.

Request

curl -s https://creahunt.com/api/v1/discoveries/8f1b… \
  -H "Authorization: Bearer $CREAHUNT_KEY"

Response (trimmed)

{
  "id": "8f1b…",
  "title": "Cold-plunge creators, UK",
  "status": "completed",
  "brief": "UK creators posting cold plunge and sauna recovery…",
  "criteria": {
    "description": "Fitness and recovery creators in the UK…",
    "requirements": ["Films own cold-plunge sessions", "UK-based"],
    "hashtags": ["coldplunge", "saunaculture"],
    "platforms": ["instagram", "tiktok"],
    "recency": "90d",
    "followerBands": ["micro", "mid"],
    "matchPrecision": "exact"
  },
  "counts": { "candidates": 212, "scored": 96, "match": 18,
              "borderline": 31, "filtered": 47, "eliminated": 64 },
  "creators": [
    {
      "handle": "frostandfire",
      "platform": "instagram",
      "displayName": "Frost & Fire",
      "followers": 84200,
      "score": 4.6,
      "band": "match",
      "headline": "Weekly plunge-and-sauna recovery films",
      "rationale": "Eight of the last twelve posts are original cold-plunge…",
      "campaignFit": { "score": 5, "verdict": "fit",
                       "reasons": ["Films outdoors in the UK"] },
      "profileUrl": "https://www.instagram.com/frostandfire/"
    }
  ]
}

GET/api/v1/collection

Every creator saved to your collection, newest first, including your private notes and labels.

Request

curl -s https://creahunt.com/api/v1/collection \
  -H "Authorization: Bearer $CREAHUNT_KEY"

Response (trimmed)

{
  "data": [
    {
      "creatorId": "instagram:frostandfire",
      "handle": "frostandfire",
      "platform": "instagram",
      "displayName": "Frost & Fire",
      "followers": 84200,
      "score": 4.6,
      "headline": "Weekly plunge-and-sauna recovery films",
      "profileUrl": "https://www.instagram.com/frostandfire/",
      "note": "Ask about Q1 availability",
      "label": "shortlist",
      "savedAt": "2026-09-15T08:12:44.000Z"
    }
  ],
  "count": 1
}

GET/api/v1/creators/{platform}/{handle}

The analytics your workspace has already computed for a creator: audience, engagement, content mix, brand value. Cache-only — it never starts a paid analysis, so a creator you have not analysed yet answers 404.

Request

curl -s https://creahunt.com/api/v1/creators/instagram/frostandfire \
  -H "Authorization: Bearer $CREAHUNT_KEY"

Response (trimmed)

{
  "platform": "instagram",
  "handle": "frostandfire",
  "analytics": {
    "handle": "frostandfire",
    "assembledAt": "2026-09-16T09:00:00.000Z",
    "provider": { "state": "measured" },
    "overview": { "followers": { "value": 84200, "source": "measured" } },
    "audience":  { "countries": [{ "code": "GB", "share": 0.61 }] },
    "content":   { "formats": [{ "format": "reel", "share": 0.72 }] }
  }
}

// Not analysed yet:
{ "error": "not_analyzed",
  "message": "No cached analytics for this creator.",
  "hint": "Analyze the creator in the app first." }

Operating it

Rate limits and errors

60 requests per minute, per key. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Window; a refusal is a 429 with Retry-After. Need more? Create a second key, or talk to us about Enterprise.

Errors always look the same, so you can branch on error and show message:

Error shape

{ "error": "unauthorized",
  "message": "Send a live API key as `Authorization: Bearer ch_live_…`." }

401 unauthorized — missing, malformed, unknown or revoked key.
404 not_found — no such record in this workspace.
404 not_analyzed — the creator has no cached analytics yet.
404 unknown_route — no such endpoint.
429 rate_limited — over 60 requests in a minute.
400 bad_platform — platform must be instagram, tiktok or youtube.

Agents

MCP connector

The same data, exposed to Claude and ChatGPT over the Model Context Protocol. Streamable HTTP, one endpoint, authenticated with the same key.

Endpoint

https://creahunt.com/api/mcp/mcp

Authorization: Bearer ch_live_…

Claude: Settings → Connectors → Add custom connector. Paste the URL, add the Authorization header with your key, connect.

ChatGPT: Settings → Connectors → Create. Paste the URL, choose custom authentication, use the Authorization header with your key, save.

Five read-only tools come back:

list_discoveries — your runs, with counts and status.
get_discovery — one run in full, every scored creator.
get_collection — your saved shortlist.
get_creator — cached analytics for one creator.
search_content — full-text search across indexed creator posts.

Check it from the terminal

curl -s -X POST https://creahunt.com/api/mcp/mcp \
  -H "Authorization: Bearer $CREAHUNT_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'