API Documentation

BrandEngine is an AI-powered brand management platform that helps you create, schedule, and publish on-brand content across 10+ social media platforms. This guide covers the REST API and key concepts.

Quick start

1. Sign up at /signup and create your organization
2. Create a brand in the Brand Studio with your DNA (colors, voice, audience)
3. Connect social accounts via the Integrations page
4. Generate your first piece of content via the API or dashboard

Base URL

https://brandengine.utilizebot.cloud/api/v1

All endpoints are prefixed with /api/v1. Responses are JSON.

JWT tokens (session auth)

Login returns an access_token and refresh_token:

POST /auth/login
Content-Type: application/json

{
  "email": "you@company.com",
  "password": "your-password"
}

// Response
{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer"
}

Include the access token on all subsequent requests:

Authorization: Bearer eyJ...

API keys (external integrations)

For server-to-server integrations, generate an API key from Settings > API Keys. Pass it via headers:

X-API-Key-ID: your_key_id
X-API-Key-Secret: your_key_secret

Or as a bearer token:

Authorization: Bearer key_id:key_secret

API keys support scoped permissions: publish, status, manage_brands, manage_accounts, oauth_initiate.

List brands

GET /brands

Returns all brands for your organization.

Create a brand

POST /brands
{
  "name": "Acme Corp",
  "tagline": "Innovation at scale",
  "industry": "SaaS",
  "voice_tone": "professional, confident",
  "voice_keywords": ["innovation", "scale", "efficiency"],
  "primary_color": "#6366f1",
  "secondary_color": "#06b6d4",
  "target_audience": {
    "role": "Tech founders",
    "age_range": "25-45",
    "interests": ["startups", "growth"]
  }
}

Update a brand

PUT /brands/{brand_id}
// Same fields as create (all optional)

Generate content

POST /content/generate
{
  "brand_id": "uuid",
  "content_type": "social_post",
  "platform": "linkedin",
  "topic": "Our Q2 product launch",
  "additional_instructions": "Mention the new AI features",
  "tone_override": "excited"
}

Content types: social_post, blog, email, ad_copy, caption.

List content

GET /content?brand_id=uuid&status=draft&platform=linkedin&page=1&per_page=20

Bulk upload (CSV)

POST /content/bulk-upload
Content-Type: multipart/form-data
file: your.csv

CSV columns: platform, post_at, text, image_url, tags, brand_slug

Create a campaign with AI Agent

POST /campaigns/plan
{
  "brand_id": "uuid",
  "brief": "Q2 product launch campaign focusing on AI features",
  "start_date": "2026-05-01",
  "end_date": "2026-05-31",
  "platforms": ["linkedin", "twitter", "instagram"],
  "posts_per_week": {
    "linkedin": 3,
    "twitter": 5,
    "instagram": 2
  }
}

This triggers the AI Campaign Agent which streams its plan via SSE. The agent analyzes your brand DNA, competitors, and generates a full content plan.

List campaigns

GET /campaigns?brand_id=uuid

A/B testing

POST /ab-tests
{
  "content_id": "uuid",
  "strategies": ["formal", "casual", "question_led"]
}

Strategies: formal, casual, question_led, stat_led, story_led.

Publish content (external API)

POST /external/publish
X-API-Key-ID: your_key_id
X-API-Key-Secret: your_key_secret

{
  "brand_slug": "acme-corp",
  "platform": "linkedin",
  "text": "Excited to announce our new AI features!",
  "image_url": "https://..."
}

Automation schedules

Automation schedules run on a cron and generate + publish content automatically. Configure frequency, time windows, approval requirements, and image strategy from the dashboard or via POST /automation/schedules.

Reschedule content

PATCH /content/{id}/schedule
{ "scheduled_at": "2026-05-15T14:00:00Z" }

List inbox items

GET /inbox?platform=linkedin&sentiment=negative&is_read=false&page=1&per_page=20

Reply to an item

POST /inbox/{id}/reply
{ "reply_text": "Thanks for the feedback! We're looking into it." }

AI draft reply

POST /inbox/{id}/ai-draft
// Returns a brand-voice-matched reply suggestion

Mark / flag / assign

PATCH /inbox/{id}/read
PATCH /inbox/{id}/archive
PATCH /inbox/{id}/flag
PATCH /inbox/{id}/assign  { "user_id": "uuid" }

Create a webhook

POST /webhooks
{
  "url": "https://your-server.com/webhook",
  "events": ["post.published", "post.failed"],
  "description": "Production webhook"
}

Events: post.published, post.failed, post.scheduled, content.created, inbox.received, campaign.planned, approval.requested, approval.decided.

Every delivery includes an X-BrandEngine-Signature header with an HMAC-SHA256 signature. Verify it against your webhook secret.

List deliveries

GET /webhooks/{id}/deliveries

Create a short link

POST /short-links
{
  "target_url": "https://acme.com/blog/launch",
  "brand_id": "uuid",
  "auto_utm": {
    "utm_source": "linkedin",
    "utm_medium": "social",
    "utm_campaign": "q2-launch"
  }
}

Click analytics

GET /short-links/{id}/stats

Returns clicks by day, country, and referrer platform.

BrandEngine uses a provider architecture. Each social platform is a Python class that implements the PlatformProvider abstract base class.

Provider interface

from app.providers.social.base import PlatformProvider, PostContent, PublishResult

class MyPlatformProvider(PlatformProvider):
    platform_name = "myplatform"

    async def publish(self, content: PostContent, credentials: dict) -> PublishResult:
        # Implement publishing logic
        ...

    async def fetch_engagement(self, post_id: str, credentials: dict) -> EngagementMetrics:
        # Fetch likes, shares, comments
        ...

    async def fetch_inbox(self, credentials: dict, since: datetime) -> list[InboxItem]:
        # Pull comments/mentions
        ...

    async def reply(self, item_id: str, text: str, credentials: dict) -> str:
        # Send a reply
        ...

    def get_capabilities(self) -> ProviderCapabilities:
        return ProviderCapabilities(
            supports_images=True,
            supports_video=False,
            supports_stories=False,
            max_text_length=5000,
            rate_limit_per_hour=100,
        )

Registration

Add your provider file to backend/app/providers/social/ and call register(MyPlatformProvider) in the package init.

Plans

GET /billing/plans

Returns all available plans with limits and features.

Tiers

Feature gates

Endpoints gated by tier return 403 with: {"code": "feature_not_available", "feature": "...", "upgrade_required": true}