Documentation

Overview

The Brand Context Protocol (BCP) is an open standard for expressing brand identity in machine-readable JSON format. It enables AI tools, design platforms, and marketing systems to understand and respect your brand guidelines automatically.

Minimal Example

{
  "brand": {
    "id": "my-brand",
    "display_name": "My Brand",
    "brand_type": "consumer_brand"
  }
}

Core Schema

The core BCP schema defines the structure of a brand context document. It uses JSON Schema (draft-07) for validation.

Brand Object

The brand object is the only required top-level field. It identifies the brand.

Identity

The identity section captures the brand's core essence—mission, values, and archetype.

{
  "identity": {
    "mission": "Make beauty accessible to everyone",
    "values": ["authenticity", "simplicity", "inclusivity"],
    "brand_archetype": "everyperson"
  }
}

Visual

The visual section defines the brand's visual identity system including logo, colors, and typography.

Primary Brand Mark

Describes the main logo or brand mark with type (logo, profile_image, wordmark, symbol), file URL, and minimum size requirements for digital (px) and print (mm).

Colors

Five color palette buckets: primary, secondary, neutral, background, and accent. Each color entry has a name, hex value (pattern: #RRGGBB), a human-readable usage description, and a machine-readable roles array for brand guard tools. Use accent for high-emphasis colors used sparingly — highlights, badges, or key CTAs distinct from the primary palette.

Typography

Primary font family and allowed weights.

{
  "visual": {
    "primary_brand_mark": {
      "type": "wordmark",
      "file_url": "https://brand.example.com/logo.svg",
      "min_size": { "digital_px": 40, "print_mm": 15 }
    },
    "colors": {
      "primary": [
        {
          "name": "Brand Blue",
          "hex": "#0066CC",
          "usage": "Headers, CTAs, and primary action buttons",
          "roles": ["heading", "primary_action", "accent"]
        }
      ],
      "neutral": [
        {
          "name": "Ink",
          "hex": "#1A1A1A",
          "usage": "Body text and headings",
          "roles": ["text", "heading"]
        }
      ],
      "background": [
        {
          "name": "Canvas",
          "hex": "#FFFFFF",
          "usage": "Page and section backgrounds",
          "roles": ["background"]
        }
      ],
      "accent": [
        {
          "name": "Electric Yellow",
          "hex": "#FFD600",
          "usage": "Highlights, badges, and attention-drawing micro-interactions",
          "roles": ["accent", "icon"]
        }
      ]
    },
    "typography": {
      "primary": { "family": "Inter", "weights": [400, 500, 700] }
    }
  }
}

Verbal

The verbal section defines how the brand communicates—its voice, tone, and vocabulary rules.

Voice & Tone

A textual description of the brand voice, plus 2–4 tone descriptors that capture how the brand sounds:

Available tone descriptors: authoritative, approachable, bold, calm, confident, conversational, direct, empathetic, empowering, enthusiastic, inspirational, nurturing, playful, sophisticated, warm, witty.

Vocabulary

Lists of encouraged words and forbidden words (each with a reason and suggested alternative).

{
  "verbal": {
    "voice": {
      "description": "Warm, knowledgeable, like a trusted friend",
      "tone": ["warm", "approachable", "confident"]
    },
    "vocabulary": {
      "encouraged_words": ["discover", "explore", "together"],
      "forbidden_words": [
        { "word": "cheap", "reason": "Undermines value", "alternative": "affordable" }
      ]
    }
  }
}

Positioning

Describes the brand's market positioning and target audience.

{
  "positioning": {
    "target_audience": {
      "primary": {
        "description": "Health-conscious millennials aged 25-40"
      }
    }
  }
}

Governance

The governance layer is the executable core of BCP v2 — deterministic enforcement rules for marketing tactics, claims, pricing, and per-channel policy. Brands inherit sensible defaults from the Global Policy Library and override what they need.

Risk & Enforcement

Sets the overall brand tolerance for content risk.

Tactics Policy

Controls which marketing tactics are allowed, warned, escalated, or blocked. Each override references a tactic from the Global Policy Library by tactic_id.

"tactics_policy": {
  "inherit_defaults": true,
  "overrides": [
    { "tactic_id": "countdown_timer", "enforcement": "block" },
    { "tactic_id": "false_scarcity", "enforcement": "block" },
    { "tactic_id": "social_proof", "enforcement": "allow" }
  ]
}

Claims Policy

Controls how brand and product claims are governed. Works with the Claims Registry companion.

Pricing & Urgency

Channel Overrides

Per-channel adjustments to tone and policy. Core rules stay consistent; each channel adapts what it needs.

Valid channels: meta_ads, google_ads, email, website, support, social_instagram, social_twitter, social_linkedin, sms, marketplace.

"channel_overrides": {
  "social_linkedin": {
    "tone": ["authoritative", "confident", "direct"],
    "tactics_overrides": [
      { "tactic_id": "countdown_timer", "enforcement": "block" }
    ]
  },
  "email": {
    "tone": ["warm", "confident"],
    "urgency_policy": "moderate"
  }
}

Approval Workflow

Defines tiered approval requirements for content that triggers escalation.

"approval_workflow": {
  "enabled": true,
  "tiers": [
    {
      "tier": "minor",
      "scope": "Social media posts, internal emails",
      "approvers": ["marketing_team"]
    },
    {
      "tier": "major",
      "scope": "Ad campaigns, press releases",
      "approvers": ["brand_director", "cmo"]
    }
  ]
}

Runtime Overrides

Time-bound policy relaxations for campaigns. These take highest precedence in the merge chain.

"runtime_overrides": [
  {
    "override_id": "diwali-sale-2026",
    "valid_from": "2026-10-15T00:00:00Z",
    "valid_until": "2026-11-05T23:59:59Z",
    "channel_scope": ["email", "social_instagram"],
    "tactics_overrides": [
      { "tactic_id": "limited_time_offer", "enforcement": "allow" }
    ],
    "approved_by": "brand_director"
  }
]

Companion Contexts

Beyond the core BCP, brands can attach companion context files that carry domain-specific data. These are separate JSON documents linked to the same brand, each governed by its own schema.

Claims Registry

Registry of brand/product claims subject to governance enforcement. Each claim references a GPL claim_type_id so the engine can cross-reference against governance.claims_policy. Claims can be scoped to specific products (via sku:<id>) or the brand as a whole.

{
  "brand_ref": "my-brand",
  "claims": [
    {
      "claim_id": "recycled_soles",
      "claim_type_id": "sustainability_claim",
      "claim_text": "100% recycled ocean plastic in all soles",
      "scope": ["sku:RUN-100", "sku:RUN-200"],
      "evidence_url": "https://example.com/sustainability-report.pdf",
      "verified": true,
      "valid_until": "2027-01-01"
    }
  ]
}

Versioning

Every brand's BCP is version-controlled. When changes are published, a snapshot of the current data is saved to the version history with a changelog entry. You can roll back to any previous version.

# List versions
GET /api/brands/:brand_id/versions

# Rollback to version 3
POST /api/brands/:brand_id/rollback
{ "target_version": 3 }

Data Sources

Upload structured data (reviews, surveys, social analytics, support tickets) that the platform normalizes and uses to generate smart BCP update suggestions.

# Upload a data source
POST /api/brands/:brand_id/data-sources
Content-Type: multipart/form-data
{ source_type: "reviews", file: reviews.json }

# Run cross-source analysis
POST /api/brands/:brand_id/analyze
{ "source_ids": [1, 2, 3] }

Drafts & Review

The draft workflow lets you generate, review, and selectively apply BCP changes before they go live.

Extensions & Policy Library

Global Policy Library (GPL)

The GPL is the canonical menu of marketing tactics, claim types, escalation triggers, platform constraints, and disclaimer templates that brands reference by ID. BCP ships with vertical defaults:

• d2c-policy-defaults — 38+ tactics across urgency, scarcity, social proof, fear appeals, dark patterns, and more. 15+ claim types. Escalation triggers and disclaimer templates.
• b2b-policy-defaults — B2B-specific policy defaults for enterprise marketing.
• compliance-taxonomy — Taxonomy of compliance categories and industry profiles.

Brands set governance.tactics_policy.inherit_defaults: true to inherit GPL defaults, then override individual tactics via overrides[]. Platform constraints from the GPL are immutable — brands cannot relax them.

Official Extensions

Added under the extensions key for domain-specific needs:

• ecommerce — Product presentation (description style, image guidelines, title format), pricing display (charm/prestige/round), sale vocabulary, shipping, and review response tone.

Companion Schemas

Companion contexts are separate JSON documents linked to the same brand:

• claims-registry — Brand/product claims with GPL type refs, evidence links, verification status, and expiry dates. See Claims Registry.

Custom Extensions

Brands can add proprietary fields using the x- prefix pattern:

{
  "brand": { "id": "orbitops-cloud" },
  "x-orbitops-enterprise-playbooks": {
    "endorsement_guidelines": { ... },
    "athlete_tiers": { ... }
  }
}

API Reference

Authentication

API keys are created per-brand on the Access & Keys page. Each key is scoped to one brand and carries permissions that control what it can do:

Pass the key as a Bearer token:

Authorization: Bearer bcp_AbCd1234...

When using an API key, you do not need to pass brand_id in the request body — the brand is resolved from the key automatically.

Read Brand Context

Fetch the brand's BCP JSON, scoped by the key's allowed sections.

GET /brands/:brand_id/brand-context.json
Authorization: Bearer bcp_...

Alternatively, pass the key as a query parameter:

GET /brands/:brand_id/brand-context.json?key=bcp_...

Without a key, only public sections (brand, identity, visual, metadata) are returned.

Evaluate Text

Score text against the brand's tone, vocabulary, tactics policy, and claims governance. Requires the evaluate permission.

POST /api/text/evaluate
Authorization: Bearer bcp_...
Content-Type: application/json

{
  "text": "Limited time offer! Buy now before it's too late!",
  "communication_type": "auto",
  "channel": "email"
}

communication_type can be auto (LLM detects it), ad_copy, product_listing, social_post, support_reply, etc. channel activates channel-specific overrides.

Rewrite Text

Rewrite off-brand text to align with the brand's voice and policies. Requires evaluate permission.

POST /api/text/rewrite
Authorization: Bearer bcp_...
Content-Type: application/json

{
  "text": "Cheap products on sale!!!",
  "communication_type": "product_listing"
}

Evaluate Design

Evaluate extracted design data (colors, fonts, logo) against brand visual guidelines. Requires evaluate permission.

POST /api/design/evaluate
Authorization: Bearer bcp_...
Content-Type: application/json

{
  "design_data": {
    "colors": [{ "hex": "#FF0000", "role_hint": "text" }],
    "background_colors": [{ "hex": "#FFFFFF" }],
    "fonts": ["Inter", "Roboto"],
    "has_logo": true
  },
  "source_app": "canva",
  "strictness": "standard"
}

Analyze Image

Analyze a rasterized design image against brand guidelines using vision models. Use this when the design has no editable layers (e.g. a pre-made banner). Requires evaluate permission.

POST /api/design/analyze-image
Authorization: Bearer bcp_...
Content-Type: application/json

{
  "image_base64": "<base64-encoded JPEG or PNG>",
  "image_mime_type": "image/jpeg",
  "source_app": "canva"
}