Visual Brand Analysis

The POST /api/v1/analyze endpoint accepts an image URL and an analysis template, then returns a structured brand score with dimension breakdowns. This guide uses the built-in brand_scorecard template to score a competitor's homepage.

What you'll build

POST an image URL and the template name to the analyze endpoint. The image must be publicly accessible — use a direct link to a screenshot hosted on S3, Cloudflare Images, or any CDN.

curl -X POST https://www.linksii.com/api/v1/analyze \
  -H "Authorization: Bearer lnk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://cdn.example.com/screenshots/competitor-homepage.png",
    "template": "brand_scorecard",
    "workspace_id": "ws_01HXYZ",
    "context": {
      "brand_name": "Competitor Inc",
      "industry": "SaaS"
    }
  }'

Request body parameters

The brand_scorecard template returns an overall score (0–100) plus scores across five brand dimensions with explanations.

{
  "data": {
    "id": "analysis_01HPQR",
    "workspace_id": "ws_01HXYZ",
    "template": "brand_scorecard",
    "score": 74,
    "dimensions": {
      "visual_identity": {
        "score": 82,
        "summary": "Strong logo placement and consistent colour palette. Hero image reinforces the brand message."
      },
      "messaging_clarity": {
        "score": 71,
        "summary": "Value proposition is clear but the subheading is dense. Consider shorter copy above the fold."
      },
      "trust_signals": {
        "score": 68,
        "summary": "Logos present but no visible review counts. Adding social proof numbers would improve trust."
      },
      "cta_effectiveness": {
        "score": 79,
        "summary": "Primary CTA is prominent and action-oriented. Secondary CTA competes slightly with primary."
      },
      "ai_discoverability": {
        "score": 70,
        "summary": "Brand name appears in meta context but lacks structured data signals for AI indexing."
      }
    },
    "recommendations": [
      "Add aggregate review count near the hero CTA",
      "Shorten the subheading to under 12 words",
      "Include FAQ schema markup to improve AI discoverability"
    ],
    "image_url": "https://cdn.example.com/screenshots/competitor-homepage.png",
    "created_at": "2025-06-01T10:05:00Z"
  }
}

Accessing dimension scores

# Extract all dimension scores with jq
curl -X POST https://www.linksii.com/api/v1/analyze \
  -H "Authorization: Bearer lnk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://cdn.example.com/screenshots/competitor.png","template":"brand_scorecard","workspace_id":"ws_01HXYZ"}' \
  | jq '.data.dimensions | to_entries[] | "\(.key): \(.value.score)"'

Run the same template on multiple brands and compute the delta. The snippet below analyses two brands in parallel and prints a side-by-side comparison.

# Run both analyses (in separate terminals or background jobs)
curl -X POST https://www.linksii.com/api/v1/analyze \
  -H "Authorization: Bearer lnk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://cdn.example.com/my-brand.png","template":"brand_scorecard","workspace_id":"ws_01HXYZ","context":{"brand_name":"My Brand"}}' \
  > my_brand.json

curl -X POST https://www.linksii.com/api/v1/analyze \
  -H "Authorization: Bearer lnk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://cdn.example.com/competitor.png","template":"brand_scorecard","workspace_id":"ws_01HXYZ","context":{"brand_name":"Competitor Inc"}}' \
  > competitor.json

# Compare overall scores
echo "My Brand: $(jq '.data.score' my_brand.json)"
echo "Competitor: $(jq '.data.score' competitor.json)"

Common errors for this endpoint

Handling quota errors

# Check remaining quota from response headers
curl -I -X POST https://www.linksii.com/api/v1/analyze \
  -H "Authorization: Bearer lnk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{...}' \
  | grep -i "x-ratelimit"