Brand Kit

💡 Building a query-only agent? Skip this page. Brand kit is only needed for content generation. If your agent just ingests raw sources and queries them, you don't need a brand kit.

The brand kit is the single source of truth for how generated content should sound. It controls voice, tone, persona, and writing rules — and it applies to every generation call automatically. Without a brand kit, the content engine has no identity guidance, and output will sound generic.

---

When to configure a brand kit

An agent should interact with the brand kit in these situations:

---

Updating the brand kit

There are two ways to update the brand kit:

Partial update with PATCH

Use PATCH when you only want to change one or a few fields without affecting the rest:

import os, requests

KEY  = os.environ["SENSO_API_KEY"]
BASE = "https://apiv2.senso.ai/api/v1"
HEADERS = {"X-API-Key": KEY, "Content-Type": "application/json"}

resp = requests.patch(f"{BASE}/org/brand-kit", headers=HEADERS, json={
    "guidelines": {
        "voice_and_tone": "Warm and approachable, like a trusted advisor"
    }
})
print(resp.json()["brand_kit_id"])

curl -X PATCH https://apiv2.senso.ai/api/v1/org/brand-kit \
  -H "X-API-Key: $SENSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "guidelines": {
      "voice_and_tone": "Warm and approachable, like a trusted advisor"
    }
  }'

Full replacement with PUT

If you need to replace the entire brand kit or are setting it up from scratch, use PUT. Because PUT is a full replacement, the correct workflow is read → merge → write to avoid losing existing fields:

# 1. Get the current brand kit
current = requests.get(f"{BASE}/org/brand-kit", headers=HEADERS).json()
guidelines = current.get("guidelines", {})

# 2. Merge changes
guidelines["voice_and_tone"] = "Warm and approachable, like a trusted advisor"

# 3. Write the full updated object
resp = requests.put(f"{BASE}/org/brand-kit", headers=HEADERS, json={
    "guidelines": guidelines
})
print(resp.json()["brand_kit_id"])

# 1. Get the current brand kit
curl https://apiv2.senso.ai/api/v1/org/brand-kit \
  -H "X-API-Key: $SENSO_API_KEY"

# 2. Merge changes client-side, then write the full object
curl -X PUT https://apiv2.senso.ai/api/v1/org/brand-kit \
  -H "X-API-Key: $SENSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "guidelines": {
      "brand_name": "Acme Credit Union",
      "voice_and_tone": "Warm and approachable, like a trusted advisor",
      "author_persona": "Senior financial advisor",
      "global_writing_rules": ["Use active voice"]
    }
  }'

If no brand kit exists yet, GET returns an empty state and the agent should create one from scratch.

---

Setting up a brand kit

resp = requests.put(f"{BASE}/org/brand-kit", headers=HEADERS, json={
    "guidelines": {
        "brand_name":           "Acme Credit Union",
        "brand_domain":         "acmecu.com",
        "brand_description":    "Member-owned credit union serving small businesses since 1985",
        "voice_and_tone":       "Warm, knowledgeable, and jargon-free. Like a trusted neighbour who happens to be a financial expert.",
        "author_persona":       "Senior financial advisor with 15 years of experience",
        "global_writing_rules": [
            "Use active voice",
            "Keep sentences under 25 words",
            "Avoid acronyms unless defined on first use",
            "Always include a next step for the reader",
        ],
    }
})
brand_kit = resp.json()
print(f"Brand kit ID: {brand_kit['brand_kit_id']}")

curl -X PUT https://apiv2.senso.ai/api/v1/org/brand-kit \
  -H "X-API-Key: $SENSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "guidelines": {
      "brand_name": "Acme Credit Union",
      "brand_domain": "acmecu.com",
      "brand_description": "Member-owned credit union serving small businesses since 1985",
      "voice_and_tone": "Warm, knowledgeable, and jargon-free. Like a trusted neighbour who happens to be a financial expert.",
      "author_persona": "Senior financial advisor with 15 years of experience",
      "global_writing_rules": [
        "Use active voice",
        "Keep sentences under 25 words",
        "Avoid acronyms unless defined on first use",
        "Always include a next step for the reader"
      ]
    }
  }'

The guidelines field is free-form JSON. You can add any fields you want, but the content engine looks for these canonical fields during generation:

What each field controls

Voice and tone: specificity matters

This is the field that most affects output quality. Compare:

Vague — produces generic, forgettable content:

"Professional and friendly"

Specific — produces content with a distinct voice:

"Warm, knowledgeable, and jargon-free. Like a trusted neighbour who happens to be a financial expert. Explain concepts as if the reader is smart but unfamiliar with the topic. Use analogies from everyday life."

When helping a user define their voice, ask them: "Who do you want to sound like when talking to your customers?" Their answer maps directly to this field.

Writing rules: make them testable

Good rules are binary — a reviewer can check yes or no:

How the brand kit flows into generation

Brand Kit (org-wide)
  ├── voice_and_tone      → controls writing style
  ├── author_persona      → controls expertise and perspective
  ├── global_writing_rules → hard constraints on all output
  │
  ▼
Content Type (per-template)
  ├── template            → controls format and structure
  ├── writing_rules       → additional rules for this format
  │
  ▼
Generation output
  = brand identity + content type format + compiled knowledge base

Global writing rules from the brand kit and per-content-type writing rules both apply during generation. Use global rules for org-wide standards and content-type rules for format-specific guidance. See Content Types for details on how rules layer.

---

Retrieving your brand kit

resp = requests.get(f"{BASE}/org/brand-kit", headers=HEADERS)
brand_kit = resp.json()
print(brand_kit["guidelines"])

curl https://apiv2.senso.ai/api/v1/org/brand-kit \
  -H "X-API-Key: $SENSO_API_KEY"

---

Using the CLI

If you're using the Senso CLI, you can manage the brand kit with:

# View current brand kit
senso brand-kit get --output json

# Full replacement (PUT) — overwrites all existing fields
senso brand-kit set --data '{
  "guidelines": {
    "brand_name": "Acme Credit Union",
    "voice_and_tone": "Warm and approachable",
    "author_persona": "Senior financial advisor",
    "global_writing_rules": ["Use active voice"]
  }
}'

# Partial update (PATCH) — only changes the fields you send, preserves the rest
senso brand-kit patch --data '{
  "guidelines": {
    "voice_and_tone": "Casual and direct"
  }
}'

---

Errors