# ViralSky Public API (v1)

**Gate:** Max (Stripe) or AppSumo T3 only.  
**Base URL:** `https://viralsky.ai` (or your deploy origin)  
**Auth:** `Authorization: Bearer vs_…`  
**Create keys:** Dashboard → Account → API & automation → `/settings/api`

Scheduler / publish endpoints are **out of scope for v1** (Meta App Review).

After deploying schema changes run:

```bash
npx prisma db push
npx prisma generate
```

## Endpoints

### `GET /api/v1/credits`

Returns credit balance.

```json
{
  "credits": 4800,
  "monthlyLimit": 5000,
  "tier": "max",
  "tierDisplayName": "AppSumo T3",
  "source": "appsumo"
}
```

### `POST /api/v1/generate/thread`

**Cost:** 2 credits

```json
{
  "topic": "How I grew to 10K followers",
  "outputFormat": "linkedin",
  "writingStyle": "viral",
  "emojiLevel": 1,
  "aiProvider": "claude",
  "language": "en",
  "cta": { "type": "link", "text": "Join free", "url": "https://example.com" },
  "sources": [
    {
      "kind": "web",
      "title": "Example article",
      "url": "https://example.com/article",
      "content": "Facts the model may use..."
    }
  ]
}
```

`outputFormat`: `twitter` | `linkedin` | `facebook` | `threads`

`sources` (optional): up to 8 ground-truth items (`web` | `url` | `document` | `note`). When present, the model may only use facts from these sources.

### `POST /api/v1/generate/ideas`

**Cost:** 1 credit (0 on cross-user niche cache hit)

```json
{ "niche": "AI SaaS founders", "language": "en" }
```

### `POST /api/v1/generate/news`

**Cost:** 2 credits

```json
{
  "topic": "OpenAI launches new model",
  "outputType": "linkedin",
  "isCustomTopic": true
}
```

### `POST /api/v1/generate/image`

**Cost:** 5 (`nano-banana-2`) or 10 (`nano-banana-pro`)

```json
{
  "prompt": "Minimal flat illustration of a rocket launching",
  "model": "nano-banana-2",
  "size": "square"
}
```

## Headers

| Header | Required | Notes |
|--------|----------|--------|
| `Authorization` | yes | `Bearer vs_…` |
| `Content-Type` | POST | `application/json` |
| `Idempotency-Key` | no | Max 128 chars; successful responses replayed for 24h |

## Rate limiting

60 requests / API key / rolling minute. Responses include `X-RateLimit-*` and `429` + `Retry-After` when exceeded.

## Errors

| Status | Code / flags |
|--------|----------------|
| 401 | `INVALID_API_KEY` |
| 403 | `TIER_TOO_LOW`, `INSUFFICIENT_SCOPE`, `requiresSubscription`, `noCredits` |
| 429 | `RATE_LIMITED` |

## Outbound webhooks

Register HTTPS URLs at `/settings/api`. On successful API generation ViralSky POSTs:

```json
{
  "type": "content.generated",
  "generatedAt": "2026-08-11T12:00:00.000Z",
  "generationType": "thread",
  "generationId": "…",
  "data": { }
}
```

Headers:

- `X-ViralSky-Event: content.generated`
- `X-ViralSky-Timestamp: <unix seconds>`
- `X-ViralSky-Signature: sha256=<hex>`

Verify: `HMAC-SHA256(secret, "${timestamp}.${rawBody}")`.

## Make.com

Use **HTTP → Make a request** (no native partner app in v1):

1. Create API key at `/settings/api`
2. POST to `/api/v1/generate/thread` with Bearer auth
3. Set `Idempotency-Key` to the Make execution id
4. Or: Catch Hook URL + outbound webhook for `content.generated`

## MCP (hosted)

**Endpoint:** `POST/GET https://viralsky.ai/api/mcp` (Streamable HTTP)  
**Auth:** same Bearer `vs_…` as REST  
**Gate / credits / rate limits:** identical to `/api/v1/*`

Tools: `generate_thread`, `generate_ideas`, `generate_news`, `generate_image`, `get_credits`.

### Cursor

```json
{
  "mcpServers": {
    "viralsky": {
      "url": "https://viralsky.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer vs_YOUR_KEY"
      }
    }
  }
}
```

### Claude Desktop (stdio → remote)

```json
{
  "mcpServers": {
    "viralsky": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://viralsky.ai/api/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer vs_YOUR_KEY"
      }
    }
  }
}
```

Full notes (including optional local stdio): `mcp/README.md`.

## Env / deploy notes

No new required env vars for the REST API or hosted MCP (uses existing `DATABASE_URL`, AI keys, `NEXTAUTH_URL`).

Optional: none for API keys (hashed at rest with SHA-256).

Deploy checklist:

1. `npx prisma db push` — adds `ApiKey`, `ApiIdempotencyRecord`, `OutboundWebhook`
2. `npx prisma generate`
3. Redeploy Next.js app (ships `/api/mcp`)
4. (Optional) `cd mcp && npm install` only if you still run the local stdio wrapper