Copy as Markdown

Partner API Integration Guide

The Brand Kit OS Partner API lets partner applications pull rich brand context to enhance AI-generated content. This guide covers everything you need to integrate.

Base URL:

https://fupwpcqmyykfiuakjxxc.supabase.co/functions/v1/partner-api

---

Getting Started

Integration takes three steps:

1. Link — Call POST /v1/integrations/partner/link with a brand_kit_id to receive your API key and webhook secret.
2. Pull — Call GET /v1/brand-kits/{id} before generating content to fetch the latest brand context.
3. Listen — Receive webhook pushes when a brand kit is updated or deleted.

---

Authentication

Every request requires a Bearer token in the Authorization header:

Authorization: Bearer pk_a1b2c3d4e5f6...

Per-Partner Keys (recommended)

During the /link step, Brand Kit OS returns a unique API key prefixed with pk_. This key is:

• Shown only once — save it securely
• Hashed (SHA-256) before storage — we never store the plaintext
• Independently revocable per partner integration
• Used for all subsequent API calls

Global Key (deprecated)

The legacy PARTNER_API_KEY environment variable is still accepted as a fallback. It will be removed in a future version. Migrate to per-partner keys.

---

API Reference

POST /v1/integrations/partner/link

Links a partner app to a Brand Kit OS brand kit. Called once during onboarding.

Request:

curl -X POST \
  https://fupwpcqmyykfiuakjxxc.supabase.co/functions/v1/partner-api/v1/integrations/partner/link \
  -H "Authorization: Bearer <GLOBAL_PARTNER_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"brand_kit_id": "uuid-here", "external_user_id": "leafpad-user-123", "external_workspace_id": "leafpad-ws-456", "webhook_url": "https://api.leafpad.app/webhooks/bkos"}'

Response (201):

{
  "integration": {
    "id": "uuid",
    "brand_kit_id": "uuid",
    "partner_name": "leafpad",
    "external_user_id": "leafpad-user-123",
    "external_workspace_id": "leafpad-ws-456",
    "webhook_url": "https://api.leafpad.app/webhooks/bkos",
    "is_active": true
  },
  "partner_api_key": "pk_a1b2c3d4e5f67890...",
  "webhook_secret": "uuid-uuid",
  "message": "Save these credentials — they will not be shown again."
}

⚠️ Save partner_api_key and webhook_secret immediately. They are displayed only once.

---

GET /v1/brand-kits/{brand_kit_id}

Returns the full brand kit data for a single brand kit.

curl https://fupwpcqmyykfiuakjxxc.supabase.co/functions/v1/partner-api/v1/brand-kits/<BRAND_KIT_ID> \
  -H "Authorization: Bearer pk_a1b2c3d4..."

Response (200):

{
  "brand_kit_id": "uuid",
  "workspace_id": "uuid",
  "updated_at": "2026-02-19T12:00:00Z",
  "version": 3,
  "compat": { "..." },
  "full": { "..." }
}

See Data Model Reference for the compat and full schemas.

---

GET /v1/brand-kits

Lists brand kits linked to a partner identity.

curl "https://fupwpcqmyykfiuakjxxc.supabase.co/functions/v1/partner-api/v1/brand-kits?external_user_id=leafpad-user-123&limit=20&offset=0" \
  -H "Authorization: Bearer pk_a1b2c3d4..."

At least one of external_user_id or external_workspace_id is required.

Response (200):

{
  "data": [ { "brand_kit_id": "...", "compat": {}, "full": {} } ],
  "pagination": { "limit": 20, "offset": 0, "count": 1 }
}

---

Data Model Reference

Every brand kit response contains two data layers:

compat — Drop-in Fields

Simplified fields that map directly to common partner fields (Description, Keywords, Style).

full — Rich Context

Detailed brand data organized into 8 categories.

full.voice

full.audience

full.messaging

full.visuals

full.seo

full.constraints

full.examples

full.ctas

---

Webhooks

When a brand kit is updated or deleted, Brand Kit OS sends a POST request to your registered webhook_url.

Events

Payload

{
  "event_id": "uuid",
  "event_type": "brand_kit.upserted",
  "occurred_at": "2026-02-19T12:00:00Z",
  "brand_kit_id": "uuid",
  "workspace_id": "uuid",
  "version": 3,
  "compat": { "..." },
  "full": { "..." }
}

For brand_kit.deleted, the compat and full fields are omitted.

Signature Verification

Every webhook includes two headers for verification:

Reject the webhook if the timestamp is more than 5 minutes old (replay protection).

Node.js Example

const crypto = require("crypto");

function verifyWebhook(body, secret, timestamp, signature) {
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > 300) return false; // 5 min window

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${body}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Python Example

import hmac, hashlib, time

def verify_webhook(body: str, secret: str, timestamp: int, signature: str) -> bool:
    if abs(time.time() - timestamp) > 300:
        return False

    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.{body}".encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

---

Error Handling

All errors return a consistent JSON structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": {}
  }
}

Retry Guidance

• 429: Wait and retry after 60 seconds
• 500: Retry with exponential backoff (1s, 2s, 4s, max 3 retries)
• 4xx (other): Do not retry — fix the request

---

Rate Limits

When rate limited, you receive a 429 response. Wait for the current window to expire (≤60 seconds) before retrying.

---

Leafpad Mapping Guide

This section maps Brand Kit OS data to Leafpad's current fields for easy integration.

Direct Field Mapping (compat layer)

Enhanced AI Context (full layer)

For superior blog content, feed these additional fields into your AI prompt:

Example AI Prompt Enhancement

You are writing a blog post for [brand].

TONE: Use these descriptors: ${compat.writing_style}
DO SAY: ${full.voice.do_phrases.join(", ")}
DON'T SAY: ${full.voice.dont_phrases.join(", ")}
AUDIENCE: Writing for ${full.audience.personas[0].name} who struggles with ${full.audience.pain_points.join(", ")}
NEVER MENTION: ${full.constraints.taboo_topics.join(", ")}
INCLUDE CTA: ${full.ctas.primary_ctas[0]}

---

API Calls Summary