Documentation

ViralClaw API v1

Generate viral content, analyze profiles, and get topic suggestions programmatically.

Authentication

All requests require an API key via the Authorization header:

Authorization: Bearer vc_live_your_api_key_here

API keys are created in the admin panel. Each key has scoped access to specific endpoints.

Rate Limits

Basic
100 requests/day
Pro
1,000 requests/day
Enterprise
10,000 requests/day

Response Format

All responses follow a consistent contract:

Success
{ "ok": true, "data": {...}, "meta": {...} }
Error
{ "ok": false, "error": "message", "retryable": true }

Endpoints

POST/api/v1/generatescope: generate

Generate a viral post for any platform and tone.

Request body
{
  "topic": "why content strategy is dead",
  "platform": "linkedin",
  "tone": "authority",
  "postType": "Caption"
}
Response
{
  "ok": true,
  "data": {
    "content": "Full post body...",
    "hook": "Opening hook line",
    "cta": "Call to action",
    "hashtags": { "core": [...], "discovery": [...], "longTail": [...] },
    "viralScore": 84,
    "hookScore": 91,
    "clarityScore": 80
  },
  "meta": { "tokensUsed": 1100, "latencyMs": 8500 }
}
POST/api/v1/analyzescope: analyze

Analyze a social profile or bio for growth weaknesses.

Request body
{
  "bio": "Founder & CTO | Building AI products | Former security engineer",
  "platform": "linkedin"
}
Response
{
  "ok": true,
  "data": {
    "overallScore": 52,
    "clarityScore": 58,
    "brandConsistencyScore": 45,
    "contentOpportunityScore": 72,
    "niche": "AI/SaaS",
    "weaknesses": ["Bio reads like a resume..."],
    "strengths": ["Clear technical authority..."],
    "viralAngles": ["Behind-the-scenes breakdowns..."]
  }
}
POST/api/v1/improvescope: improve

Get an improved version of any post with specific diff explanations.

Request body
{
  "hook": "I built a product nobody wanted.",
  "content": "Here's what I learned...",
  "platform": "linkedin",
  "tone": "authority"
}
Response
{
  "ok": true,
  "data": {
    "improved": { "hook": "Better hook...", "content": "Better content...", "score": 88 },
    "diff": ["Improvement 1", "Improvement 2", "Improvement 3"]
  }
}
POST/api/v1/topicsscope: topics

Get 3 ranked topic suggestions with confidence signals.

Request body
{
  "platform": "linkedin",
  "tone": "authority",
  "niche": "SaaS growth"
}
Response
{
  "ok": true,
  "data": {
    "topics": [
      { "title": "Why your bio is killing growth", "reason": "Addresses top weakness", "signal": "Fixes positioning" },
      { "title": "The one metric nobody tracks", "reason": "Curiosity gap format", "signal": "High engagement" },
      { "title": "I spent 6 months posting wrong", "reason": "Personal story performs well", "signal": "Save magnet" }
    ]
  }
}
GET/api/v1/feedscope: feed

Get top-performing posts (anonymous, by viral score).

Response
{
  "ok": true,
  "data": {
    "items": [
      { "hook": "Post hook...", "score": 91, "hookScore": 88, "platform": "LINKEDIN", "tone": "AUTHORITY" }
    ],
    "total": 20
  }
}

Error Codes

400Invalid request body
401Missing or invalid API key
403Key revoked or scope denied
429Rate limit exceeded
502AI generation failed (retryable)
500Internal server error

Base URL: https://viralclaw.app