Enriched social analytics, one API key, two surfaces.

1. Create a key in Settings → API (Pro or Business plan). It looks like vmx_1a2b3c4d_… and is shown once — copy it.

2. Call the REST API with the key as a bearer token:

curl -H "Authorization: Bearer vmx_xxxxxxxx_..." \
  https://sfom.ai/api/v1/creators/instagram/natgeo

3. Or wire the MCP server into your AI client and ask it for a report — see Client setup. That's it.

Every request authenticates with an API key in the format vmx_<8 hex>_<32 hex>. We store only a SHA-256 hash — the full key is shown once at creation and can never be retrieved again. Pass it as either header (both work on REST and MCP):

Authorization: Bearer vmx_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# — or —
X-API-Key: vmx_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys carry scopes (read for REST, mcp for the MCP server) and an optional expiry. Manage, rotate (create + revoke) and delete them in Settings → API. Revoking a key takes effect within a minute. Active-key limits per plan: Free 1 · Starter 3 · Pro 10 · Business 50.

API and MCP access is a paid capability — the Pro or Business plan. Two things are metered, per workspace:

1. Monthly call quota — every request (MCP or REST) consumes one unit. Free 1,000, paid 50,000 per month, plus a burst limit of 60 requests/minute per workspace.
2. Tokens (10 per call) — charged only on the premium surfaces: every MCP tools/call, REST authenticity, and REST raw. The enriched REST reports — creators, videos, trends — consume only a call unit, no tokens.

The MCP endpoint speaks JSON-RPC 2.0 over HTTP at POST https://sfom.ai/api/mcp (protocol 2024-11-05). The handshake (initialize, tools/list, ping) works on any valid key; only tools/call requires the Pro/Business plan and meters 10 tokens per call.

Client setup

Claude Desktop / Claude Code / Cursor — native remote HTTP transport:

{
  "mcpServers": {
    "sfom": {
      "type": "http",
      "url": "https://sfom.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer vmx_xxxxxxxx_..."
      }
    }
  }
}

Older stdio-only clients — bridge with mcp-remote:

{
  "mcpServers": {
    "sfom": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://sfom.ai/api/mcp",
               "--header", "Authorization: Bearer vmx_xxxxxxxx_..."]
    }
  }
}

Test the handshake with curl:

curl -sX POST https://sfom.ai/api/mcp \
  -H "x-api-key: vmx_xxxxxxxx_..." \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Tool reference

11 tools. Every tools/call costs 1 call unit + 10 tokens (refunded on no-data). Bold arguments are required.

Example — call a tool over curl:

curl -sX POST https://sfom.ai/api/mcp \
  -H "x-api-key: vmx_xxxxxxxx_..." \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"get_creator_report",
                 "arguments":{"platform":"tiktok","handle":"zachking"}}}'

All endpoints are GET under https://sfom.ai/api/v1, require the read scope, and wrap the payload in a consistent envelope:

{
  "data": { /* the report */ },
  "meta": {
    "source": "sfom.ai",
    "quota_remaining": 49873,
    "quota_limit": 50000
  }
}

GET /creators/{platform}/{handle}

Enriched creator profile. quota only, 0 tokens. Platform ∈ instagram · tiktok · youtube. A cold handle triggers a live scrape. Returns found, follower/engagement stats, ugcScore, audience authenticity, topPosts[] and a deep block (hooks, pillars, strengths).

curl -H "Authorization: Bearer vmx_..." \
  https://sfom.ai/api/v1/creators/instagram/natgeo

GET /videos/{platform}/{id}

Single video breakdown. quota only, 0 tokens. Corpus-only (never scrapes) → 404 if not analyzed. Returns metrics, trendCoefficient, virality, hook and a deep why-it-works/how-to-adapt block.

curl -H "Authorization: Bearer vmx_..." \
  https://sfom.ai/api/v1/videos/tiktok/7412345678901234567

GET /trends/{niche}

Top videos in a niche, ranked by the views/followers coefficient. quota only, 0 tokens. Niche slugs include auto, food, travel, fashion, beauty, fitness, tech, finance, real-estate, parenting, pets, music, gaming, art, education, comedy, vlog, business, ecom, health.

curl -H "Authorization: Bearer vmx_..." \
  https://sfom.ai/api/v1/trends/real-estate

GET /videos/tiktok/{id}/authenticity

TikTok fake-view detection. 1 call + 10 tokens. TikTok only. Returns fakeScore, authenticity, confidenceLevel, riskLevel and suspiciousFeatures[]. No data yet → {available:false} with a refund.

curl -H "Authorization: Bearer vmx_..." \
  https://sfom.ai/api/v1/videos/tiktok/7412345678901234567/authenticity

GET /raw/{platform}/{...path}

Raw social-data escape hatch — passthrough to the underlying provider path. 1 call + 10 tokens, plus an inner 120 req/min limit. Platforms: tiktok, instagram, youtube, twitter, linkedin.

curl -H "Authorization: Bearer vmx_..." \
  "https://sfom.ai/api/v1/raw/tiktok/web/fetch_user_profile?uniqueId=zachking"

Failures return a consistent envelope with a machine-readable code. On 429/503 a retryAfter (seconds) is included; on 402 a reason and upgrade_url.

{ "error": "Creator not found", "code": "NOT_FOUND" }