Getting Started

This guide walks you through making your first API call to analyze a brand.

Prerequisites

A Brandparser account
An API key from your workspace settings

Step 1: Get Your API Key

Log in to your Brandparser dashboard
Navigate to Settings > API Keys
Click Create API Key
Choose an environment (staging for testing, production for live use)
Copy your key - it won't be shown again

Your key will look like: bp_prod_xxxxxxxxxxxxxxxxxxxx

Step 2: Submit a URL for Analysis

Use the /v1/api/parse endpoint to submit a website for brand analysis:

curl -X POST https://api.brandparser.com/v1/api/parse \
  -H "Authorization: Bearer bp_prod_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://stripe.com"}'

Response:

{
  "data": {
    "brand_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued",
    "source_url": "https://stripe.com",
    "message": "Analysis started. Poll GET /v1/api/brands/:brandId for results."
  }
}

Step 3: Check Analysis Status

Poll the brand endpoint to check if analysis is complete:

curl https://api.brandparser.com/v1/api/brands/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer bp_prod_your_api_key"

Response while processing:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "stripe.com",
    "source_url": "https://stripe.com",
    "analysis_status": "running",
    "analysis_started_at": "2024-01-15T10:30:00Z",
    "analysis": null
  }
}

Step 4: Retrieve Results

Once analysis_status is "completed", the full analysis is available:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Stripe",
    "source_url": "https://stripe.com",
    "analysis_status": "completed",
    "analysis_started_at": "2024-01-15T10:30:00Z",
    "analysis_completed_at": "2024-01-15T10:32:45Z",
    "analysis": {
      "colors": {
        "primary": "#635BFF",
        "palette": [...]
      },
      "typography": {
        "headings": {...},
        "body": {...}
      },
      "logos": [...],
      "mission": {...},
      "tone": {...}
    }
  }
}

Complete Example (Node.js)

const API_KEY = "bp_prod_your_api_key";
const BASE_URL = "https://api.brandparser.com";

async function analyzeBrand(url) {
  // Submit URL for analysis
  const parseRes = await fetch(`${BASE_URL}/v1/api/parse`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ url }),
  });

  const { data } = await parseRes.json();
  const brandId = data.brand_id;

  // Poll until complete
  while (true) {
    const brandRes = await fetch(`${BASE_URL}/v1/api/brands/${brandId}`, {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });

    const brand = await brandRes.json();

    if (brand.data.analysis_status === "completed") {
      return brand.data;
    }

    if (brand.data.analysis_status === "failed") {
      throw new Error("Analysis failed");
    }

    // Wait 5 seconds before polling again
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
}

// Usage
const brand = await analyzeBrand("https://stripe.com");
console.log(brand.analysis);

Next Steps

API Guide - End-to-end integration tutorials (branded UI, emails, white-labeling)
Authentication - Learn about API key management
Environments - Understand staging vs production
API Reference - Full endpoint documentation