# BrandBeacon API Reference

> Complete API documentation for AI agents and LLMs.

Base URL: `https://brandbeacon.dev/api/v1`

## Authentication

All API requests require a Bearer token. API keys are prefixed with `bb_live_` and created via the dashboard or the API Keys endpoint (session auth only).

```
Authorization: Bearer bb_live_your_key_here
```

Session-based authentication (browser cookies) is also supported for web dashboard integrations.

## Response Format

All responses follow a consistent envelope:

### Success Response
```json
{
  "ok": true,
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-02T00:00:00.000Z",
    "auth_method": "api_key",
    "rate_limit": {
      "remaining_rpm": 59,
      "remaining_rpd": 999,
      "reset_at": "2026-02-02T00:01:00.000Z"
    }
  }
}
```

### Error Response
```json
{
  "ok": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-02T00:00:00.000Z"
  }
}
```

### Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| UNAUTHORIZED | 401 | Invalid or missing authentication |
| FORBIDDEN | 403 | Missing required scope or brand access |
| SESSION_REQUIRED | 403 | Endpoint requires web session (not API key) |
| NOT_FOUND | 404 | Resource not found |
| VALIDATION_ERROR | 400 | Invalid request body |
| RATE_LIMITED | 429 | Rate limit exceeded (check Retry-After header) |
| AGENT_LIMIT_EXCEEDED | 429 | Daily plan billing limit reached |
| GENERATION_FAILED | 500 | AI content generation failed |
| INTERNAL_ERROR | 500 | Server error |

### Rate Limit Headers

All responses include rate limit headers:
- `X-Request-Id` - Unique request identifier
- `X-RateLimit-Remaining-Rpm` - Remaining requests this minute
- `X-RateLimit-Remaining-Rpd` - Remaining requests today
- `X-RateLimit-Reset` - ISO timestamp when the minute window resets
- `Retry-After` - Seconds to wait (only on 429 responses)

---

## Endpoints

### GET /brands

List all brands accessible to the authenticated user.

**Required scope:** `read`

**Response:**
```json
{
  "ok": true,
  "data": {
    "brands": [
      {
        "id": "uuid",
        "name": "My Brand",
        "website": "https://example.com",
        "user_id": "uuid",
        "created_at": "2026-01-01T00:00:00.000Z"
      }
    ]
  }
}
```

---

### GET /brands/:id

Get a single brand by ID.

**Required scope:** `read`

**Path parameters:**
- `id` (string, required) - Brand UUID

**Response:**
```json
{
  "ok": true,
  "data": {
    "brand": {
      "id": "uuid",
      "name": "My Brand",
      "website": "https://example.com",
      "user_id": "uuid",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  }
}
```

---

### GET /brands/:id/voice

Get the extracted brand voice profile for a brand.

**Required scope:** `read`

**Path parameters:**
- `id` (string, required) - Brand UUID

**Response:**
```json
{
  "ok": true,
  "data": {
    "voice": {
      "brand_id": "uuid",
      "personality_traits": ["friendly", "professional", "innovative"],
      "tone_attributes": {
        "formality": 0.7,
        "energy": 0.6,
        "warmth": 0.8
      },
      "language_patterns": {
        "vocabulary_level": "accessible",
        "sentence_structure": "varied",
        "signature_phrases": ["Let's build something great"]
      },
      "content_themes": [
        {
          "theme": "innovation",
          "keywords": ["cutting-edge", "future", "breakthrough"]
        }
      ],
      "confidence_score": 0.85,
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  }
}
```

---

### POST /content/generate

Generate AI-powered social media content using the brand's voice profile.

**Required scope:** `generate`

**Request body:**
```json
{
  "brand_id": "uuid",
  "platforms": ["facebook", "instagram", "x_twitter", "linkedin", "google_business", "bluesky", "tiktok", "threads"],
  "goal": "Announce our new product launch",
  "content_type": "social_post",
  "additional_context": "The product is a smart water bottle that tracks hydration",
  "variations": 2
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| brand_id | string | yes | Brand UUID to generate content for |
| platforms | string[] | yes | Target platforms. Values: `facebook`, `instagram`, `x_twitter`, `linkedin`, `google_business`, `bluesky`, `tiktok`, `threads` |
| goal | string | yes | What the content should achieve |
| content_type | string | no | Default: `social_post` |
| additional_context | string | no | Extra context for the AI |
| variations | number | no | Number of variations to generate (default: 1) |

**Response:**
```json
{
  "ok": true,
  "data": {
    "contents": [
      {
        "platform": "x_twitter",
        "text": "Staying hydrated just got smarter...",
        "hashtags": ["#SmartHydration", "#Innovation"],
        "characterCount": 180
      },
      {
        "platform": "instagram",
        "text": "Meet the future of hydration...",
        "hashtags": ["#SmartWaterBottle", "#HealthTech"],
        "characterCount": 1200
      }
    ],
    "overallBrandConsistency": 0.92
  }
}
```

**Daily generation limits by plan:**
- Free: 5 generations/day
- Starter: 50 generations/day
- Growth: 200 generations/day
- Enterprise: 1,000 generations/day

---

### POST /posts

Create a new post (draft status).

**Required scope:** `post`

**Request body:**
```json
{
  "content": "Check out our latest product!",
  "platforms": ["facebook", "x_twitter"],
  "brand_id": "uuid",
  "image_url": "https://example.com/image.png"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| content | string | yes | Post content text |
| platforms | string[] | yes | Target platforms |
| brand_id | string | no | Associated brand UUID |
| image_url | string | no | Image URL to attach |

**Response:**
```json
{
  "ok": true,
  "data": {
    "post": {
      "id": "uuid",
      "content": "Check out our latest product!",
      "platforms": ["facebook", "x_twitter"],
      "brand_id": "uuid",
      "image_url": "https://example.com/image.png",
      "status": "draft",
      "source": "api",
      "created_at": "2026-02-02T00:00:00.000Z"
    }
  }
}
```

---

### GET /posts

List posts with filtering and pagination.

**Required scope:** `read`

**Query parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| brand_id | string | Filter by brand |
| status | string | Filter by status: `draft`, `scheduled`, `published`, `failed` |
| page | number | Page number (default: 1) |
| limit | number | Items per page (default: 50, max: 100) |

**Response:**
```json
{
  "ok": true,
  "data": {
    "posts": [ ... ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 123
    }
  }
}
```

---

### POST /posts/schedule

Schedule a post for future publishing.

**Required scope:** `schedule`

**Request body:**
```json
{
  "post_id": "uuid",
  "scheduled_at": "2026-02-03T14:00:00.000Z"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| post_id | string | yes | Post UUID to schedule |
| scheduled_at | string | yes | ISO 8601 datetime (must be in the future) |

**Response:**
```json
{
  "ok": true,
  "data": {
    "job_id": "job_abc123",
    "post_id": "uuid",
    "scheduled_at": "2026-02-03T14:00:00.000Z"
  }
}
```

---

### POST /api-keys

Create a new API key. **Requires web session authentication** (not API key auth).

**Request body:**
```json
{
  "name": "My Agent Key",
  "scopes": ["read", "generate", "post", "schedule"],
  "brand_ids": ["uuid-1", "uuid-2"],
  "agent_type": "moltbot",
  "rate_limit_rpm": 60,
  "rate_limit_rpd": 1000,
  "expires_at": "2027-01-01T00:00:00.000Z"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | yes | Human-readable key name |
| scopes | string[] | no | Allowed scopes (default: `["read"]`). Values: `read`, `write`, `generate`, `post`, `schedule`, `admin` |
| brand_ids | string[] | no | Restrict key to specific brands (null = all brands) |
| agent_type | string | no | Identifier for the agent using this key |
| rate_limit_rpm | number | no | Requests per minute (default: 60) |
| rate_limit_rpd | number | no | Requests per day (default: 1000) |
| expires_at | string | no | ISO 8601 expiration date (null = no expiry) |

**Response (201):**
```json
{
  "ok": true,
  "data": {
    "id": "uuid",
    "name": "My Agent Key",
    "key_prefix": "bb_live_abcd",
    "key": "bb_live_abcdefghijklmnopqrstuvwxyz1234567890ab",
    "scopes": ["read", "generate", "post", "schedule"],
    "brand_ids": ["uuid-1", "uuid-2"],
    "agent_type": "moltbot",
    "rate_limit_rpm": 60,
    "rate_limit_rpd": 1000,
    "expires_at": "2027-01-01T00:00:00.000Z",
    "created_at": "2026-02-02T00:00:00.000Z"
  }
}
```

The `key` field is returned only once at creation time and is never stored or retrievable again.

---

### GET /api-keys

List all active (non-revoked) API keys for the authenticated user.

**Response:**
```json
{
  "ok": true,
  "data": {
    "keys": [
      {
        "id": "uuid",
        "name": "My Agent Key",
        "key_prefix": "bb_live_abcd",
        "scopes": ["read", "generate"],
        "brand_ids": null,
        "agent_type": "moltbot",
        "rate_limit_rpm": 60,
        "rate_limit_rpd": 1000,
        "last_used_at": "2026-02-01T00:00:00.000Z",
        "expires_at": null,
        "revoked_at": null,
        "created_at": "2026-01-01T00:00:00.000Z"
      }
    ]
  }
}
```

---

### DELETE /api-keys

Revoke an API key.

**Request body:**
```json
{
  "key_id": "uuid"
}
```

**Response:**
```json
{
  "ok": true,
  "data": {
    "revoked": true,
    "key_id": "uuid"
  }
}
```

---

## Typical Agent Workflow

A typical AI agent integration follows this pattern:

1. **List brands** - `GET /brands` to find available brands
2. **Get brand voice** - `GET /brands/:id/voice` to understand the brand's personality
3. **Generate content** - `POST /content/generate` with the brand ID, target platforms, and goal
4. **Create post** - `POST /posts` with the generated content
5. **Schedule post** - `POST /posts/schedule` to queue it for publishing

## Platform Character Limits

When generating content, the AI respects these platform limits:
- Facebook: 63,206 characters
- Instagram: 2,200 characters
- X/Twitter: 280 characters (auto-splits into threads for longer content)
- LinkedIn: 3,000 characters
- Google Business: 1,500 characters
- Bluesky: 300 characters
- TikTok: 2,200 characters
- Threads: 500 characters