Developer Documentation

BriefBop API Reference

Integrate AI-powered creative intelligence into your advertising workflows. Everything you need to proof, generate, and manage creative assets programmatically.

Base URL: https://api.briefbop.com/v1

Last updated: March 6, 2026

Getting Started

The BriefBop API gives you programmatic access to AI-powered creative proofing, content generation, asset management, and brand intelligence. Follow the steps below to make your first API call.

Quick Start

Create a BriefBop account at app.briefbop.com and accept the EULA during registration
Navigate to Settings → API Keys to generate your key
Include your API key in the Authorization header
Make your first request to the proof endpoint

Base URL

All API requests should be made to:

https://api.briefbop.com/v1

Authentication

All API requests require authentication via a Bearer token. Include your API key in the Authorization header of every request. Note: users must accept the End User License Agreement (EULA) during registration before API keys can be issued.

curl -X GET https://api.briefbop.com/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Security Note: Never expose your API key in client-side code or public repositories. Use environment variables and server-side requests to keep your key secure.

AI Proofing API

Submit creative assets for multi-model AI-powered proofing. The proofing pipeline runs 3 AI models in parallel: Claude Opus (copy/grammar, brand compliance, regulatory, brief compliance), GPT-4o (visual composition, format specs, accessibility), and Gemini Pro (cultural sensitivity). Each finding is tagged with the AI model that produced it.

POST/api/ai/proof

Request Body

{
  "asset_id": "asset_abc123",
  "brand_profile_id": "brand_xyz789",
  "briefText": "Launch campaign for summer collection targeting millennials...",
  "dimensions": [
    "brand_compliance",
    "copy_quality",
    "accessibility",
    "legal",
    "visual_consistency",
    "format_specs",
    "cultural_sensitivity",
    "brief_compliance"
  ],
  "options": {
    "severity_threshold": "warning",
    "include_suggestions": true,
    "language": "en-US"
  }
}

Note: The brief_compliance dimension is automatically added as the 8th proofing dimension when a creative brief is attached via the briefText field. Findings include a sourceModel field indicating which AI model (Claude Opus, GPT-4o, or Gemini Pro) produced the finding.

Response200 OK

{
  "id": "proof_def456",
  "status": "completed",
  "asset_id": "asset_abc123",
  "overall_score": 87,
  "modelsUsed": ["claude-opus", "gpt-4o", "gemini-pro"],
  "dimensions": {
    "brand_compliance": {
      "score": 92,
      "findings": [
        {
          "severity": "warning",
          "message": "Secondary color #FF6B35 deviates from brand palette by 12%",
          "suggestion": "Consider using #FF5722 for closer brand alignment",
          "sourceModel": "claude-opus",
          "location": { "x": 240, "y": 180, "width": 120, "height": 40 }
        }
      ]
    },
    "copy_quality": {
      "score": 85,
      "findings": [
        {
          "severity": "info",
          "message": "Headline readability score is 64 (target: 70+)",
          "suggestion": "Shorten headline to 8 words or fewer for better impact",
          "sourceModel": "claude-opus"
        }
      ]
    },
    "accessibility": { "score": 78, "findings": [...] },
    "legal": { "score": 95, "findings": [] },
    "visual_consistency": { "score": 90, "findings": [...] },
    "format_specs": { "score": 88, "findings": [...] },
    "cultural_sensitivity": { "score": 96, "findings": [...] },
    "brief_compliance": { "score": 82, "findings": [...] }
  },
  "created_at": "2026-03-06T10:30:00Z",
  "completed_at": "2026-03-06T10:30:04Z"
}

Parameters

Parameter	Type	Required	Description
asset_id	string	Yes	The ID of the asset to proof
brand_profile_id	string	No	Brand profile for compliance checks
briefText	string	No	Creative brief text; when provided, brief_compliance is auto-added as a proofing dimension
dimensions	string[]	No	Proofing dimensions to evaluate (defaults to all). Available: brand_compliance, copy_quality, accessibility, legal, visual_consistency, format_specs, cultural_sensitivity, brief_compliance
options	object	No	Additional proofing configuration

AI Generation API

Generate creative content using AI including ad copy, image variations, and format adaptations. Copy generation uses Claude Sonnet (primary) or GPT-4o-mini (budget). Image generation uses GPT Image 1. Variation generation uses Claude Sonnet. All generated content is automatically aligned with your brand profile when specified.

Copy Generation

POST/api/ai/generate

{
  "type": "copy",
  "brand_profile_id": "brand_xyz789",
  "parameters": {
    "format": "social_ad",
    "platform": "instagram",
    "tone": "conversational",
    "product": "Summer Running Shoe Collection",
    "target_audience": "Active millennials, ages 25-35",
    "key_messages": [
      "Ultra-lightweight design",
      "Eco-friendly materials",
      "Limited edition colorways"
    ],
    "variants": 3
  }
}

Response200 OK

{
  "id": "gen_copy_001",
  "type": "copy",
  "model": "claude-sonnet",
  "variants": [
    {
      "headline": "Run Lighter. Tread Lighter.",
      "body": "Our new summer collection is built for speed and sustainability.",
      "cta": "Shop the Drop"
    },
    {
      "headline": "Less Weight. Less Waste. More Miles.",
      "body": "Eco-crafted kicks for runners who care about the finish line and the planet.",
      "cta": "Explore Now"
    },
    {
      "headline": "Your Lightest Run Starts Here",
      "body": "Limited edition colorways, unlimited performance. Made with recycled materials.",
      "cta": "Get Yours"
    }
  ],
  "created_at": "2026-03-06T11:00:00Z"
}

Image Generation

POST/api/ai/generate

{
  "type": "image",
  "brand_profile_id": "brand_xyz789",
  "parameters": {
    "prompt": "Minimalist product shot of running shoes on a gradient background",
    "style": "photorealistic",
    "dimensions": { "width": 1080, "height": 1080 },
    "color_palette": ["#1E40AF", "#FF5722", "#F8FAFC"],
    "variants": 2
  }
}

Variation Generation

Generate creative variations of existing content using Claude Sonnet.

Format Adaptation

Automatically adapt existing assets to new formats, sizes, and platforms.

POST/api/ai/generate

{
  "type": "format_adaptation",
  "source_asset_id": "asset_abc123",
  "parameters": {
    "target_formats": [
      { "platform": "instagram_story", "width": 1080, "height": 1920 },
      { "platform": "facebook_feed", "width": 1200, "height": 628 },
      { "platform": "twitter_post", "width": 1200, "height": 675 }
    ],
    "preserve_key_elements": true,
    "auto_reflow_text": true
  }
}

Assets API

Upload, manage, and organize your creative assets. Supports images, videos, PDFs, and design files up to 500MB per upload.

Upload Asset

POST/api/assets/upload

curl -X POST https://api.briefbop.com/v1/assets/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@creative_banner.png" \
  -F "project_id=proj_abc123" \
  -F "name=Summer Campaign Hero Banner" \
  -F "tags=summer,hero,banner"

List Assets

GET/api/assets?project_id=proj_abc123&page=1&limit=20

{
  "data": [
    {
      "id": "asset_abc123",
      "name": "Summer Campaign Hero Banner",
      "type": "image/png",
      "size": 2450000,
      "dimensions": { "width": 1920, "height": 1080 },
      "tags": ["summer", "hero", "banner"],
      "version": 3,
      "project_id": "proj_abc123",
      "created_at": "2025-01-10T08:00:00Z",
      "updated_at": "2025-01-14T15:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47,
    "total_pages": 3
  }
}

Get Asset

GET/api/assets/:asset_id

Returns the full asset object including metadata, version history, and proof results.

Delete Asset

DELETE/api/assets/:asset_id

curl -X DELETE https://api.briefbop.com/v1/assets/asset_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response: 204 No Content

Projects API

Organize assets and campaigns into projects. Projects act as top-level containers for all your creative work.

Create Project

POST/api/projects

{
  "name": "Summer 2025 Campaign",
  "description": "Cross-platform advertising campaign for summer collection launch",
  "brand_profile_id": "brand_xyz789",
  "team_members": ["user_001", "user_002", "user_003"],
  "settings": {
    "auto_proof": true,
    "proof_dimensions": ["brand_compliance", "copy_quality", "accessibility"],
    "approval_required": true
  }
}

List Projects

GET/api/projects?status=active&page=1&limit=10

Update Project

PATCH/api/projects/:project_id

Delete Project

DELETE/api/projects/:project_id

Deleting a project moves all associated assets to the organization's archive. This action can be reversed within 30 days.

Brand Profiles API

Manage brand guidelines that power AI proofing and generation. Brand profiles include visual identity, voice and tone rules, messaging frameworks, and compliance requirements. Supports brand hierarchy with flagship and sub-brand relationships. Brand image analysis uses Claude Opus (voice/tone) and GPT-4o (color detection) in parallel. The RAG pipeline processes uploaded brand assets through content extraction, chunking, OpenAI embeddings, and Pinecone vector storage for intelligent brand context retrieval.

Create Brand Profile

POST/api/brand-profiles

{
  "name": "Acme Corp - Primary Brand",
  "hierarchyLevel": 0,
  "learningStatus": "idle",
  "visual_identity": {
    "primary_colors": ["#1E40AF", "#3B82F6"],
    "secondary_colors": ["#FF5722", "#FF8A65"],
    "fonts": {
      "heading": "Inter Bold",
      "body": "Inter Regular",
      "accent": "Space Grotesk"
    },
    "logo_urls": {
      "primary": "https://assets.acme.com/logo-primary.svg",
      "icon": "https://assets.acme.com/logo-icon.svg"
    },
    "minimum_logo_clearspace": "20px"
  },
  "voice_and_tone": {
    "personality": ["confident", "approachable", "innovative"],
    "writing_style": "Active voice, short sentences, avoid jargon",
    "vocabulary": {
      "preferred": ["empower", "streamline", "elevate"],
      "avoided": ["cheap", "basic", "synergy"]
    }
  },
  "compliance": {
    "required_disclaimers": ["Terms apply. See acme.com/terms"],
    "restricted_claims": ["guaranteed", "best in class", "#1"],
    "regulatory_frameworks": ["FTC", "GDPR"]
  }
}

Create Sub-Brand

POST/api/brand-profiles

{
  "name": "Acme Sport - Sub-Brand",
  "hierarchyLevel": 1,
  "parentBrandId": "brand_xyz789",
  "inheritColors": true,
  "inheritFonts": true,
  "inheritVoice": false,
  "inheritTone": true,
  "learningStatus": "idle",
  "visual_identity": {
    "primary_colors": [],
    "secondary_colors": ["#10B981", "#34D399"]
  },
  "voice_and_tone": {
    "personality": ["energetic", "bold", "youthful"],
    "writing_style": "Short, punchy sentences. Heavy use of action verbs."
  }
}

Brand Hierarchy Parameters

Parameter	Type	Description
hierarchyLevel	number	0 = flagship brand, 1 = sub-brand
parentBrandId	string	ID of the parent flagship brand (required for sub-brands)
inheritColors	boolean	Inherit color palette from parent brand
inheritFonts	boolean	Inherit font selections from parent brand
inheritVoice	boolean	Inherit voice guidelines from parent brand
inheritTone	boolean	Inherit tone guidelines from parent brand
learningStatus	string	RAG pipeline status: idle, learning, completed, or failed

List Brand Profiles

GET/api/brand-profiles

List Sub-Brands of a Flagship

GET/api/brand-profiles/:profile_id/sub-brands

Returns all sub-brands associated with the specified flagship brand profile.

List Brand Profiles with Hierarchy

GET/api/brand-profiles?include=hierarchy

Returns all brand profiles with their hierarchy relationships, including nested sub-brands under each flagship.

Update Brand Profile

PATCH/api/brand-profiles/:profile_id

Delete Brand Profile

DELETE/api/brand-profiles/:profile_id

Brand profiles referenced by active projects cannot be deleted. Reassign or archive projects first.

RAG Pipeline: When brand assets (PDFs, style guides, etc.) are uploaded to a brand profile, they are processed through a RAG pipeline: content extraction, chunking, OpenAI embeddings generation, and Pinecone vector storage. The learningStatus field tracks this process (idle → learning → completed/failed). Brand image analysis runs Claude Opus (voice/tone detection) and GPT-4o (color detection) in parallel for comprehensive brand understanding.

Webhooks

Receive real-time notifications when events occur in your BriefBop workspace. Configure webhook endpoints to integrate with your existing tools and workflows.

Supported Events

Event	Description
proof.completed	AI proofing analysis has finished
proof.failed	AI proofing analysis encountered an error
generation.completed	AI content generation has finished
asset.uploaded	A new asset has been uploaded
asset.approved	An asset has been approved in a workflow
project.status_changed	A project's status has been updated

Register a Webhook

POST/api/webhooks

{
  "url": "https://your-server.com/webhooks/briefbop",
  "events": ["proof.completed", "generation.completed", "asset.approved"],
  "secret": "whsec_your_signing_secret"
}

Webhook Payload

{
  "id": "evt_abc123",
  "type": "proof.completed",
  "created_at": "2026-03-06T10:30:04Z",
  "data": {
    "proof_id": "proof_def456",
    "asset_id": "asset_abc123",
    "overall_score": 87,
    "status": "completed"
  }
}

Signature Verification: All webhook payloads include a X-BriefBop-Signature header. Verify this HMAC-SHA256 signature using your webhook secret to ensure payload authenticity.

Rate Limits & Quotas

API rate limits are applied per API key. Rate limit information is included in the response headers of every request.

Plan	Requests/min	AI Proofs/day	AI Generations/day	Storage
Starter	60	50	25	5 GB
Professional	300	500	250	50 GB
Enterprise	1,000	Unlimited	Unlimited	Unlimited

Rate Limit Headers

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1705312260

Error Handling

The API uses conventional HTTP response codes to indicate success or failure. Errors include a JSON body with details about what went wrong.

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'asset_id' field is required",
    "details": [
      {
        "field": "asset_id",
        "issue": "missing_required_field"
      }
    ],
    "request_id": "req_abc123"
  }
}

Error Codes

HTTP Status	Error Code	Description
400	VALIDATION_ERROR	Request body or parameters are invalid
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	Insufficient permissions for this action
404	NOT_FOUND	The requested resource does not exist
409	CONFLICT	Resource conflict (e.g. duplicate name)
429	RATE_LIMITED	Too many requests, retry after cooldown
500	INTERNAL_ERROR	An unexpected server error occurred
503	SERVICE_UNAVAILABLE	Service is temporarily unavailable

Tip: Always include the request_id from the error response when contacting support. This helps us trace and resolve your issue quickly.

Need Help?

Our developer support team is ready to assist you with integration questions, troubleshooting, and best practices.

Help & Support Contact Support