Skip to main content

​
Overview

The Analysis API enables you to run full or flash brand analyses programmatically, retrieve results, and manage analysis history. Base Endpoint: /v1/analyses Required Scopes:
  • read:analyses - Retrieve analyses
  • write:analyses - Create analyses

​
Create Analysis

Run a new brand analysis.

​
POST /v1/analyze

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",
    "context": "B2B SaaS platform for project management"
  }'

​
Request Parameters

ParameterTypeRequiredDescription
urlstringYesWebsite URL to analyze (must be publicly accessible)
typestringNofull or flash (default: full)
contextstringNoAdditional context to improve analysis (max 500 chars)
social_linksarrayNoSocial media URLs ["https://twitter.com/brand"]
testbooleanNoTest mode (doesn’t count toward quotas)

​
Response

{
  "data": {
    "id": "anl_abc123",
    "status": "processing",
    "type": "full",
    "url": "https://example.com",
    "created_at": "2026-01-27T14:23:45Z",
    "estimated_completion": "2026-01-27T14:24:15Z"
  }
}
Status Values:
  • processing - Analysis in progress (use webhook or poll for completion)
  • completed - Results available
  • failed - Analysis failed (check error_message)

​
Get Analysis

Retrieve completed analysis results.

​
GET /v1/analyses/:id

curl https://api.branddna.app/v1/analyses/anl_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "data": {
    "id": "anl_abc123",
    "status": "completed",
    "type": "full",
    "url": "https://example.com",
    "created_at": "2026-01-27T14:23:45Z",
    "completed_at": "2026-01-27T14:24:12Z",
    "results": {
      "brandIdentity": {
        "archetype": "Sage",
        "archetypeDescription": "Wisdom and knowledge...",
        "voice": ["Professional", "Data-driven"],
        "missionStatement": "Empowering teams..."
      },
      "personas": [
        {
          "name": "Tech-Savvy Founder Sarah",
          "demographics": { ... },
          "painPoints": [ ... ],
          "motivations": [ ... ]
        }
      ],
      "swot": {
        "strengths": [ ... ],
        "weaknesses": [ ... ],
        "opportunities": [ ... ],
        "threats": [ ... ]
      },
      "strategy": {
        "initiatives": [ ... ]
      }
    }
  }
}
Full analysis includes all 13 dashboard sections. Flash audit returns targeted insights only.

​
List Analyses

Retrieve paginated list of analyses.

​
GET /v1/analyses

curl "https://api.branddna.app/v1/analyses?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Query Parameters

ParameterTypeDefaultDescription
pageinteger1Page number
limitinteger20Results per page (max: 100)
statusstring—Filter: completed, processing, failed
typestring—Filter: full or flash
created_afterstring—ISO 8601 date (e.g., 2026-01-01)
created_beforestring—ISO 8601 date
sortstringcreated_atSort field
orderstringdescasc or desc

​
Response

{
  "data": [
    {
      "id": "anl_abc123",
      "status": "completed",
      "url": "https://example.com",
      "type": "full",
      "created_at": "2026-01-27T14:23:45Z"
    },
    ...
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 145,
    "pages": 8
  }
}

​
Delete Analysis

Delete analysis from history.

​
DELETE /v1/analyses/:id

curl https://api.branddna.app/v1/analyses/anl_abc123 \
  -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "data": {
    "id": "anl_abc123",
    "deleted": true
  }
}
Deletion is permanent and cannot be undone. Consider exporting before deleting.

​
Export Analysis

Generate PDF export of analysis.

​
POST /v1/analyses/:id/export

curl https://api.branddna.app/v1/analyses/anl_abc123/export \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "pdf",
    "sections": ["all"]
  }'

​
Request Parameters

ParameterTypeRequiredDescription
formatstringNopdf or json (default: pdf)
sectionsarrayNoSections to include, or ["all"] (default)
white_labelbooleanNoRemove Brand DNA branding (Agency only)

​
Response

{
  "data": {
    "export_id": "exp_xyz789",
    "status": "processing",
    "download_url": null,
    "expires_at": null
  }
}
Polling for Completion: 
curl https://api.branddna.app/v1/exports/exp_xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"
Completed Response: 
{
  "data": {
    "export_id": "exp_xyz789",
    "status": "completed",
    "download_url": "https://cdn.branddna.app/exports/exp_xyz789.pdf",
    "expires_at": "2026-02-03T14:23:45Z"
  }
}
Download URLs expire after 7 days. Use webhooks to be notified when export is ready.

​
Webhooks

Subscribe to events instead of polling:

​
Available Events

  • analysis.started - Analysis began processing
  • analysis.completed - Analysis finished successfully
  • analysis.failed - Analysis failed with error
See Webhooks for setup.

​
Error Handling

​
400 Bad Request

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

​
404 Not Found

Analysis doesn’t exist: 
{
  "error": "Not found",
  "message": "Analysis anl_abc123 not found"
}

​
422 Unprocessable Entity

URL cannot be analyzed (e.g., requires login, blocked by robots.txt): 
{
  "error": "Unprocessable entity",
  "message": "Website requires authentication or is not publicly accessible"
}

​
Rate Limits

Analysis creation has additional quotas:
TierAnalyses/HourConcurrent
Pro605
Agency30020
429 Response: 
{
  "error": "Rate limit exceeded",
  "message": "Maximum 60 analyses per hour. Resets at 2026-01-27T15:00:00Z",
  "retry_after": 3600
}

​
Example: Full Workflow

const fetch = require('node-fetch');

const API_KEY = process.env.BRAND_DNA_API_KEY;
const BASE_URL = 'https://api.branddna.app/v1';

async function analyzeBrand(url) {
  // 1. Create analysis
  const createResponse = await fetch(`${BASE_URL}/analyze`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ url, type: 'full' })
  });

  const { data: analysis } = await createResponse.json();
  console.log(`Analysis created: ${analysis.id}`);

  // 2. Poll for completion (or use webhook)
  let result;
  while (true) {
    await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5s

    const getResponse = await fetch(`${BASE_URL}/analyses/${analysis.id}`, {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    });

    result = await getResponse.json();

    if (result.data.status === 'completed') {
      break;
    } else if (result.data.status === 'failed') {
      throw new Error('Analysis failed');
    }

    console.log('Still processing...');
  }

  console.log('Analysis complete:', result.data);
  return result.data;
}

analyzeBrand('https://example.com');
Ready to chat with Helix? See Chat API →