Search Atlas Help Center

🔌 Access Brand Voice Analysis via API

Open in
View as Markdown Open in ChatGPT Open in Claude
Camilo Aponte

Camilo Aponte

Last updated on Sep 30, 2026

🧭 Overview

Brand Vault stores your agency's brand identity details, including the Brand Voice Analysis — a structured breakdown of your brand's tone, style, and messaging guidelines. If you need to retrieve this data programmatically (for example, to integrate it into your own workflows or tools), the Search Atlas API gives you direct access.

This article explains how to authenticate, find your Brand ID, and call the correct endpoint to retrieve Brand Voice Analysis data for any brand in your workspace, such as creativeblue.agency.

🔑 Step 1: Get Your API Key

Before making any API calls, you need a valid Search Atlas API key.

  1. Log in to your Search Atlas account.
  2. Navigate to Settings → API Keys.
  3. Copy your API key and store it securely. Treat it like a password — do not share it publicly.

🏷️ Step 2: Find Your Brand ID

Every brand in Brand Vault has a unique Brand ID. You need this ID to query the correct brand's Voice Analysis.

  1. Open Brand Vault from the header apps-grid icon → More Features → Brand Vault.
  2. Select the brand you want to access (for example, creativeblue.agency).
  3. Check the URL in your browser — the Brand ID appears as a unique identifier in the URL path (for example, /brand-vault/brands/abc123xyz).
  4. Copy and save this ID for use in your API request.

Alternatively, you can list all brands in your workspace by calling the brands list endpoint and matching by brand name.

📡 Step 3: Call the Brand Voice Analysis Endpoint

Once you have your API key and Brand ID, use the following request structure to retrieve the Brand Voice Analysis:

  • Method: GET
  • Endpoint:/api/v1/brand-vault/brands/{brand_id}/voice-analysis
  • Header:Authorization: Bearer YOUR_API_KEY
  • Content-Type:application/json

Replace {brand_id} with the ID you copied in Step 2, and YOUR_API_KEY with your actual API key.

📦 Step 4: Understand the Response

A successful response returns a JSON object containing the brand's voice analysis fields. Common fields include:

  • tone — the overall tone of the brand (e.g., professional, conversational, authoritative)
  • style_guidelines — specific writing style rules for the brand
  • vocabulary — preferred and avoided words or phrases
  • audience — the target audience description
  • messaging_pillars — core themes and value propositions

You can use individual fields from this response to dynamically apply the brand voice in your own content pipelines or AI workflows.

⚙️ Using Dynamic Field-Based Preview

The API supports field-based filtering, so you can request only the specific voice attributes you need rather than retrieving the entire analysis object. Append a fields query parameter to your request to specify which fields to return.

  • Example: ?fields=tone,vocabulary,audience
  • This reduces payload size and speeds up integration, especially when embedding brand voice into real-time content generation tools.

⚠️ Common Issues and Fixes

  • 401 Unauthorized: Your API key is missing or incorrect. Double-check it in Settings → API Keys.
  • 404 Not Found: The Brand ID is wrong or the brand has been deleted. Re-confirm the ID from Brand Vault.
  • 403 Forbidden: Your account role may not have API access enabled. Contact your workspace admin to verify permissions.
  • Empty voice analysis fields: Brand Voice Analysis is generated after a brand profile is fully set up. Make sure the brand in Brand Vault has completed its onboarding and analysis steps.

💡 Best Practices

  • Store your API key as an environment variable — never hardcode it in your source code.
  • Cache Brand Voice Analysis responses if you query the same brand frequently to avoid unnecessary API calls.
  • Use the fields parameter to retrieve only what you need, keeping responses lightweight.
  • If you manage multiple brands (like an agency), loop through your brands list endpoint to batch-retrieve voice data for all clients.

🙋 Need More Help?

If you need further assistance, open the chat widget in the bottom-right corner of the platform and type human teammate to be connected with a member of our team.