---
name: brandbeacon
description: Generate on-brand social media content and publish to Facebook, Instagram, X/Twitter, LinkedIn, and Google Business using AI-powered brand voice profiles.
version: 1.0.0
author: BrandBeacon
tags:
  - social-media
  - content-generation
  - ai
  - brand-voice
  - publishing
  - scheduling
instructions_language: en
---

# BrandBeacon Skill

Generate on-brand social media content and publish across platforms using the BrandBeacon API.

## Prerequisites

You need a BrandBeacon API key. Keys are prefixed with `bb_live_` and created in the BrandBeacon dashboard at Settings > API Keys. The key must have appropriate scopes for the operations you want to perform.

Store the key as the environment variable `BRANDBEACON_API_KEY`.

## Base URL

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

## Authentication

Include the API key as a Bearer token in every request:

```
Authorization: Bearer $BRANDBEACON_API_KEY
```

## Response Format

All responses return JSON with this structure:

```json
{
  "ok": true,
  "data": { ... },
  "meta": { "request_id": "req_...", "timestamp": "..." }
}
```

On error:

```json
{
  "ok": false,
  "error": { "code": "ERROR_CODE", "message": "..." },
  "meta": { "request_id": "req_..." }
}
```

## Available Operations

### 1. List Brands

Get all brands you have access to.

```bash
curl -H "Authorization: Bearer $BRANDBEACON_API_KEY" \
  https://brandbeacon.dev/api/v1/brands
```

Returns `data.brands` array with `id`, `name`, `website`.

### 2. Get Brand Voice

Retrieve the AI-extracted brand voice profile.

```bash
curl -H "Authorization: Bearer $BRANDBEACON_API_KEY" \
  https://brandbeacon.dev/api/v1/brands/{brand_id}/voice
```

Returns `data.voice` with `personality_traits`, `tone_attributes`, `language_patterns`, `content_themes`, `confidence_score`.

### 3. Generate Content

Generate platform-optimized content using the brand voice. Requires `generate` scope.

```bash
curl -X POST -H "Authorization: Bearer $BRANDBEACON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_id": "BRAND_UUID",
    "platforms": ["x_twitter", "instagram", "linkedin"],
    "goal": "Announce our new product launch",
    "additional_context": "The product is a smart water bottle",
    "variations": 2
  }' \
  https://brandbeacon.dev/api/v1/content/generate
```

Returns `data.contents` array with per-platform `text`, `hashtags`, `characterCount`, and `data.overallBrandConsistency` score.

### 4. Create Post

Create a draft post. Requires `post` scope.

```bash
curl -X POST -H "Authorization: Bearer $BRANDBEACON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Your post text here",
    "platforms": ["x_twitter", "facebook"],
    "brand_id": "BRAND_UUID"
  }' \
  https://brandbeacon.dev/api/v1/posts
```

Returns `data.post` with `id`, `status: "draft"`.

### 5. Schedule Post

Schedule a draft post for future publishing. Requires `schedule` scope.

```bash
curl -X POST -H "Authorization: Bearer $BRANDBEACON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "post_id": "POST_UUID",
    "scheduled_at": "2026-02-03T14:00:00.000Z"
  }' \
  https://brandbeacon.dev/api/v1/posts/schedule
```

Returns `data.job_id`, `data.post_id`, `data.scheduled_at`.

### 6. List Posts

List posts with optional filtering. Requires `read` scope.

```bash
curl -H "Authorization: Bearer $BRANDBEACON_API_KEY" \
  "https://brandbeacon.dev/api/v1/posts?brand_id=UUID&status=draft&page=1&limit=50"
```

Returns `data.posts` array and `data.pagination` with `page`, `limit`, `total`.

## Typical Workflow

1. `GET /brands` to find your brand ID
2. `GET /brands/{id}/voice` to see the brand personality
3. `POST /content/generate` with brand ID, platforms, and goal
4. `POST /posts` with the generated content
5. `POST /posts/schedule` to queue it for publishing

## Scopes

API keys can be limited to specific scopes:

- `read` - Read brands, voice profiles, posts
- `generate` - Generate AI content
- `post` - Create posts
- `schedule` - Schedule posts
- `write` - Create and update posts
- `admin` - Full access

## Rate Limits

Responses include `X-RateLimit-Remaining-Rpm` and `X-RateLimit-Remaining-Rpd` headers. On 429 responses, wait for `Retry-After` seconds.

## Platform Character Limits

- Facebook: 63,206 chars
- Instagram: 2,200 chars
- X/Twitter: 280 chars (auto-threaded)
- LinkedIn: 3,000 chars
- Google Business: 1,500 chars
- Bluesky: 300 chars
- TikTok: 2,200 chars
- Threads: 500 chars

## More Information

- Full API docs: https://brandbeacon.dev/llms-full.txt
- OpenAPI spec: https://brandbeacon.dev/openapi.json