API Reference

The uvoo API lets you integrate brand-aware prompt generation and asset analysis into your existing workflow. All endpoints return JSON.

Brands

GET /brands

List all brands in your workspace.

curl https://api.uvoo.ai/v1/brands \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "brands": [
    {
      "id": "brand_abc123",
      "name": "My Brand",
      "asset_count": 284,
      "status": "ready",
      "created_at": "2026-03-01T10:00:00Z"
    }
  ]
}

POST /brands

Create a new brand and start ingestion.

curl -X POST https://api.uvoo.ai/v1/brands \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Brand",
    "source": {
      "type": "instagram",
      "handle": "yourbrand"
    }
  }'

Source types: instagram, website, upload.

Assets

GET /brands/:id/assets

Returns paginated list of assets with all extracted signals.

GET /brands/brand_abc123/assets?limit=20&offset=0

{
  "assets": [
    {
      "id": "asset_xyz789",
      "url": "https://cdn.uvoo.ai/assets/...",
      "signals": {
        "palette_hex": ["#f5f0e8", "#2c2c2c", "#d4a853"],
        "palette_cielab": [[95, 1, 5], [8, 0, 0], [68, 5, 42]],
        "lighting_type": "natural",
        "lighting_direction": "side",
        "mood_cluster": ["warm", "editorial", "intimate"],
        "fill_ratio": 0.28,
        "grain_level": 0.15,
        "brand_similarity_score": 0.87
      }
    }
  ],
  "total": 284,
  "limit": 20,
  "offset": 0
}

Prompts

POST /brands/:id/prompts

Generate brand-tuned prompts from a reference image URL or asset ID.

curl -X POST https://api.uvoo.ai/v1/brands/brand_abc123/prompts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": {
      "type": "url",
      "url": "https://example.com/reference.jpg"
    },
    "models": ["midjourney", "dalle3", "stable_diffusion", "ideogram"]
  }'

{
  "prompts": {
    "midjourney": "editorial product shot, soft diffused natural light, warm tones #f5f0e8 #d4a853 #2c2c2c, centered composition, negative space --ar 4:3 --style raw --v 6.1 --s 200",
    "dalle3": "A warm editorial product photograph...",
    "stable_diffusion": "(editorial photography:1.3), ...",
    "ideogram": "Warm editorial product photo: ..."
  },
  "brand_signals_applied": {
    "palette": ["#f5f0e8", "#d4a853", "#2c2c2c"],
    "lighting": "soft diffused natural",
    "mood": ["warm", "editorial", "intimate"],
    "composition": "centered, 0.28 fill ratio"
  }
}

Brand profile

GET /brands/:id/profile

Returns the aggregated brand signals — the statistical summary across all analyzed assets.

{
  "brand_id": "brand_abc123",
  "asset_count": 284,
  "profile": {
    "dominant_palette": ["#f5f0e8", "#2c2c2c", "#d4a853"],
    "color_temperature_mean": 5200,
    "warmth_ratio_mean": 0.71,
    "lighting_type_distribution": {
      "natural": 0.78,
      "studio": 0.15,
      "mixed": 0.07
    },
    "top_mood_tags": ["warm", "editorial", "intimate", "minimal", "organic"],
    "fill_ratio_mean": 0.27,
    "content_type_distribution": {
      "product": 0.45,
      "lifestyle": 0.38,
      "campaign": 0.17
    }
  }
}

Error codes