Skip to main content

​
Introduction

The Brand DNA API enables programmatic access to brand analysis, Helix AI chat, workspace management, and more. Build custom integrations, automate workflows, and embed brand intelligence into your applications.
Pro/Agency Tier Required — API access is available on Pro (49/mo)andAgency(49/mo) and Agency (199/mo + seats) plans.

​
Base URL

https://api.branddna.app/v1
All API requests should use this base URL with HTTPS.

​
Authentication

All requests require authentication via Bearer token: 
curl https://api.branddna.app/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
See Authentication for details on obtaining and using API keys.

​
Quick Start

​
1. Get Your API Key

1

Upgrade to Pro/Agency

API access requires Pro or Agency subscription
2

Create API Key

Settings → API Keys → Create New Key
3

Copy & Secure

Store key securely (shown only once)

​
2. Make Your First Request

curl https://api.branddna.app/v1/analyze \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "type": "full"
  }'

​
3. Handle Response

{
  "id": "anl_abc123",
  "status": "completed",
  "url": "https://example.com",
  "created_at": "2026-01-27T14:23:45Z",
  "results": {
    "brandIdentity": { ... },
    "personas": [ ... ],
    "swot": { ... }
  }
}

​
Core Endpoints

Analyze Brands

Run full or flash analyses programmatically

Chat with Helix

Send messages and receive AI responses

Manage Workspace

Create, update, and retrieve tasks

Track Competitors

Monitor competitor changes (Pro/Agency)

Team Management

Add/remove team members (Agency only)

Webhooks

Receive event notifications

​
Rate Limits

TierRequests/MinRequests/HourRequests/Day
Pro601,00010,000
Agency1205,00050,000
Headers: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1706368800
429 Response: 
{
  "error": "Rate limit exceeded",
  "message": "You have exceeded 60 requests per minute",
  "retry_after": 45
}
Need higher limits? Contact enterprise@branddna.app

​
Response Format

​
Success Response (2xx)

{
  "data": {
    "id": "anl_abc123",
    "status": "completed",
    ...
  }
}

​
Error Response (4xx/5xx)

{
  "error": "Validation error",
  "message": "URL is required",
  "details": {
    "field": "url",
    "code": "REQUIRED_FIELD"
  }
}

​
Error Codes

Status CodeMeaningCommon Causes
400Bad RequestInvalid JSON, missing required fields
401UnauthorizedMissing or invalid API key
403ForbiddenInsufficient permissions for this action
404Not FoundResource doesn’t exist
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer-side issue (retry with backoff)
503Service UnavailableMaintenance or outage

​
Pagination

List endpoints support pagination: Request: 
curl "https://api.branddna.app/v1/analyses?page=2&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response: 
{
  "data": [ ... ],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 145,
    "pages": 8
  }
}
Parameters:
  • page (default: 1): Page number
  • limit (default: 20, max: 100): Results per page

​
Filtering & Sorting

Filter by date: 
curl "https://api.branddna.app/v1/analyses?created_after=2026-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY"
Sort results: 
curl "https://api.branddna.app/v1/analyses?sort=created_at&order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Idempotency

POST and PUT requests support idempotency via Idempotency-Key header: 
curl https://api.branddna.app/v1/analyze \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
Benefits:
  • Prevent duplicate analyses if request is retried
  • Safe to retry failed requests
  • Idempotency keys expire after 24 hours

​
Versioning

Current API version: v1 Version in URL: 
https://api.branddna.app/v1/analyze
Breaking Changes:
  • New API versions released when breaking changes occur
  • v1 supported for minimum 12 months after new version release
  • Deprecation notices sent 90 days in advance

​
SDKs & Libraries

Official SDKs:

JavaScript/Node.js

npm install @branddna/sdk

Python

pip install branddna

Ruby

gem install branddna

PHP

composer require branddna/sdk
Community SDKs:
Don’t see your language? The API is REST-based—any HTTP client works!

​
Webhooks

Subscribe to events instead of polling: Available Events:
  • analysis.started
  • analysis.completed
  • analysis.failed
  • competitor.changed
  • export.ready
See Webhooks for setup.

​
Testing

​
Sandbox Environment

Test API integrations without affecting production: 
https://sandbox-api.branddna.app/v1
Differences from Production:
  • No rate limits
  • Data deleted after 7 days
  • Uses test API keys (starts with sk_test_)

​
Test Mode

Use production API with test: true flag: 
curl https://api.branddna.app/v1/analyze \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "test": true
  }'
Test Mode Behavior:
  • Doesn’t count toward quotas
  • Results not saved to history
  • Marked as “Test” in API logs

​
Best Practices

Never make API requests over HTTP. All requests must use HTTPS for security.
Implement retry logic with exponential backoff for 5xx errors. Don’t retry 4xx errors (fix the request instead).
Cache analysis results locally to reduce API calls and improve performance. Most analyses don’t change frequently.
Subscribe to webhooks instead of polling for analysis completion. Reduces API calls and latency.
Monitor X-RateLimit-Remaining header and implement backoff before hitting limits.

​
Support

API Documentation

Complete reference at docs.branddna.app/api

Email Support

api@branddna.app

Status Page

status.branddna.app

Community

Discord
Ready to build? Start with Authentication →