API Documentation

The AuraLens API provides programmatic access to the world's most comprehensive fashion intelligence graph. Integrate verified celebrity outfit data, real-time trend metrics, and visual search directly into your platform.

Read about our Agent Routing Architecture →

Quick Start

Authentication

Obtain your API key from the developer dashboard. Send it in the Authorization header.

Base URL

All API requests should be prefixed with https://api.auralens.com/v1.

Authentication

AuraLens uses Bearer Token authentication. Pass your API key in the header of each request.

# Example Request
curl -X GET https://api.auralens.com/v1/creators/jennie-kim \
  -H "Authorization: Bearer al_live_8ka..." \
  -H "Content-Type: application/json"

Security Warning: Never expose your API key in client-side code. Proxy all requests through your own backend server.

Rate Limits

Limits vary by plan. Headers are returned with every request indicating current usage.

Header	Description
X-RateLimit-Limit	The maximum number of requests you're permitted to make per hour.
X-RateLimit-Remaining	The number of requests remaining in the current time window.
X-RateLimit-Reset	The time at which the current rate limit window resets (UTC epoch seconds).

Errors

AuraLens uses standard HTTP response codes to indicate the success or failure of an API request.

Code	Description
200	OK - The request was successful.
400	Bad Request - The request was invalid or cannot be served.
401	Unauthorized - Missing or invalid API key.
429	Too Many Requests - Rate limit exceeded.

// Error Response Body
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You have exceeded your request limit of 1000/hour.",
    "documentation_url": "https://auralens.com/docs/errors"
  }
}

Creators

Retrieve structured data on content creators, celebrities, and influencers.

GET /v1/creators/{id} 1 Credit

Returns a creator object with styling profile, social stats, and recent outfits.

Arguments

id Required	string	The unique identifier of the creator (e.g., `jennie-kim`).
expand Optional	array	Expand related objects. Allowed: `outfits`, `brands`.

Response

{
  "id": "jennie-kim",
  "name": "Jennie Kim",
  "global_rank": 2,
  "commercial_score": 98.5,
  "style_profile": {
    "aesthetic": "Modern Luxury",
    "top_brands": ["Chanel", "Jacquemus"]
  }
}

Shows

Access fashion data indexed from K-dramas and global series.

GET /v1/shows/{id}/outfits 2 Credits

List outfits identified in a specific show, filterable by episode or character.

id Required	The show ID (e.g., `cloy`).
episode Optional	Filter by episode number.
character Optional	Filter by character ID (e.g., `yoon-seri`).

Products

Search and retrieve product details, availability, and affiliate links.

GET /v1/products/{id} 1 Credit

Get detailed metadata for a specific product item.

id Required The product ID (e.g., prod_swarovski_88).

Visual Search

Programmatic access to the AuraLens visual recognition engine.

POST /v1/visual-search 10 Credits

Accepts an image URL or binary and returns matched products with confidence scores.

// Request
{
  "image_url": "https://example.com/scene.jpg",
  "min_confidence": 0.8
}

// Response
{
  "matches": [
    {
      "product_id": "prod_123",
      "name": "Swarovski Earrings",
      "confidence": 0.96,
      "bbox": [120, 45, 200, 150]
    }
  ]
}

Trends Intelligence

Access the core engine of AuraLens. Raw signals on what is heating up before it goes mainstream.

GET /v1/trends/forecast PRO

Get predictive analytics for specific categories. Uses 30-day velocity vectors to predict breakout items.

category Required	Narrow forecast to `handbags`, `shoes`, `jewelry`.
horizon Optional	Prediction window in days (default: 7, max: 30).

// Response
{
  "category": "handbags",
  "forecast_date": "2026-02-10",
  "breakout_items": [
    {
      "term": "Oversized Slouch Bag",
      "current_velocity": 24.5, // Searches/hour
      "acceleration": 1.8, // Rate of change
      "predicted_peak": "2026-02-14",
      "confidence": 0.92
    }
  ]
}

Aura Score Index

The "Credit Score" for fashion virality. A composite metric (0-100) derived from screen time, social volume, and commercial conversion.

GET /v1/scores/aura/{item_id} 1 Credit

Alpha Feature: Aura Score is re-calculated every 6 hours based on global ingestion.

// Response object for "Gentle Monster - Lilit"
{
  "item_id": "gm-lilit-01",
  "aura_score": 94,
  "rating": "SS Tier",
  "components": {
    "screen_time": 98, // Minutes visible on verified celebs
    "social_volume": 88, // Mentions on X/TikTok
    "commercial_intent": 95 // Click-through rate to retail
  },
  "historical_trend": [82, 85, 91, 94] // Last 4 weeks
}

Merchant Reputation Score

Protect your users from dropshippers. We maintain a live index of merchant trust based on shipping times, return rates, and authenticity.

GET /v1/merchants/validate SECURITY

Check a domain against our "Red List" of known dropshippers and counterfeits.

// Request
{
  "domain": "fast-fashion-nova-x.com"
}

// Response - BLOCKED
{
  "domain": "fast-fashion-nova-x.com",
  "trust_score": 12, // 0-100 (Red Zone)
  "status": "BLOCKED",
  "flags": [
    "Dropshipping detected (AliExpress)",
    "Image theft confirmed",
    "No physical address"
  ],
  "alternatives": [
    {
       "domain": "farfetch.com",
       "trust_score": 98
    }
  ]
}