Virtue Mirage — API & SDK

1. Get a key

In your Virtue Mirage dashboard, open Settings → API Key. There are two key types:

Send the key as Authorization: Bearer <key> or X-VM-Api-Key: <key>.

2. Drop-in script (fastest)

Best for BigCommerce, Magento, or any themed store. Paste one tag, then call the helpers. Add your storefront origin under Settings → API Key first, or the publishable key won't be authorised.

<script src="https://virtue-brain-534746878054.us-central1.run.app/sdk/virtue-mirage.js"
        data-vm-key="vm_pub_xxx"></script>
<script>
  VirtueMirage.setCustomer('shopper@example.com');

  // Show "Your size: M" in a container
  VirtueMirage.mountSizeBadge('#vm-size', {
    gender: 'women', heightCm: 168, weightKg: 64, category: 'tops'
  });

  // Add a "See it on me" button that renders on the shopper's avatar
  VirtueMirage.mountTryOnButton('#vm-tryon', {
    productId: '123',
    productImage: 'https://cdn.example.com/products/123/front.jpg'
  });
</script>

Lower-level calls are available too: VirtueMirage.getSize(), .avatarStatus(), .preRender(), .tryOn() — all return Promises.

3. Headless / server-side (REST)

Best for headless / React / Next / Vite, or a backend. The API is plain REST — call it with fetch (Node 18+, or any HTTP client) using your secret key on the server. No package to install.

const BASE = 'https://virtue-brain-534746878054.us-central1.run.app';
const headers = { 'Authorization': `Bearer ${process.env.VM_SECRET_KEY}`, 'Content-Type': 'application/json' };

// Size + Fit Advisor
const size = await fetch(`${BASE}/api/v1/public/size`, { method: 'POST', headers,
  body: JSON.stringify({ gender:'women', heightCm:168, weightKg:64, category:'tops' }) }).then(r => r.json());

// Does this shopper already have a digital twin? (network-wide)
const twin = await fetch(`${BASE}/api/v1/public/avatar-status?email=shopper%40example.com`, { headers }).then(r => r.json());

// Render a product on the shopper's avatar (cache-first, 1 token per render)
const tryon = await fetch(`${BASE}/api/v1/public/tryon`, { method: 'POST', headers,
  body: JSON.stringify({ email:'shopper@example.com', productId:'123', productUrl:'https://cdn.example.com/products/123/front.jpg' }) }).then(r => r.json());

A typed npm package (@virtuemirage/sdk) wrapping these calls ships with our marketplace release — until then, the drop-in script and the REST endpoints above are the supported paths.

4. Endpoint reference

POST /api/v1/public/size

curl -X POST https://virtue-brain-534746878054.us-central1.run.app/api/v1/public/size \
  -H "Authorization: Bearer vm_live_xxx" -H "Content-Type: application/json" \
  -d '{"gender":"women","heightCm":168,"weightKg":64,"category":"tops"}'

→ { "success": true, "size": "M", "confidence": "high", "category": "tops", "estimated": true }

Pass exact bust/waist/hips (with optional unit:"in") to override the estimate, or a productId to resolve category and the brand's size chart automatically.

GET /api/v1/public/avatar-status

curl "https://virtue-brain-534746878054.us-central1.run.app/api/v1/public/avatar-status?email=shopper@example.com" \
  -H "Authorization: Bearer vm_live_xxx"

→ { "success": true, "hasAvatar": true, "avatarUrl": "https://…",
    "brandOfRecord": "brand-a", "isNewToThisBrand": true }

POST /api/v1/public/tryon

curl -X POST https://virtue-brain-534746878054.us-central1.run.app/api/v1/public/tryon \
  -H "Authorization: Bearer vm_live_xxx" -H "Content-Type: application/json" \
  -d '{"email":"shopper@example.com","productId":"123","productUrl":"https://cdn.example.com/123/front.jpg"}'

→ { "success": true, "imageUrl": "https://…/tryon.jpg", "cached": false }

5. Errors