API Reference

Roman API Documentation

Integrate Roman's virtual fitting room into your e-commerce platform with our RESTful API. Get size recommendations, create try-on sessions, and manage your catalog programmatically.

Authentication

All API requests require an API key sent via the Authorization header.

// Include in all requests

Authorization: Bearer YOUR_API_KEY

Get your API key from the dashboard settings. Keep your key secret and never expose it in client-side code.

Base URL

https://api.roman-fitting.com/v1

Endpoints

GET/api/retailer/catalog

Retrieve your clothing catalog items with optional filters.

Request

GET /api/retailer/catalog?category=shirts&gender=male
Authorization: Bearer YOUR_API_KEY

Response

{
  "ok": true,
  "data": [
    {
      "_id": "64a1b2c3d4e5f6789...",
      "name": "Classic Oxford Shirt",
      "brand": "Your Brand",
      "price": 79.99,
      "category": "shirts",
      "gender": "male",
      "available_sizes": "XS,S,M,L,XL,XXL",
      "size_chart": {
        "XS": { "chest": [82, 87], "waist": [68, 73] },
        "S": { "chest": [87, 92], "waist": [73, 78] },
        "M": { "chest": [92, 100], "waist": [78, 86] },
        "L": { "chest": [100, 108], "waist": [86, 94] },
        "XL": { "chest": [108, 116], "waist": [94, 102] }
      }
    }
  ]
}

POST/api/retailer/recommend

Generate a size recommendation based on user measurements and clothing item.

Request

POST /api/retailer/recommend
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "clothing_item_id": "64a1b2c3d4e5f6789...",
  "measurements": {
    "chest": 96,
    "waist": 82,
    "hips": 98,
    "height": 178,
    "weight": 75
  },
  "preferred_fit": "regular"
}

Response

{
  "ok": true,
  "data": {
    "recommended_size": "M",
    "confidence_score": 92,
    "fit_notes": "Based on your chest measurement of 96cm and waist of 82cm, we recommend size M. Your chest sits comfortably in the middle of the M range (92-100cm), suggesting an ideal fit.",
    "alternative_size": "L",
    "size_breakdown": {
      "chest_fit": "ideal",
      "waist_fit": "ideal",
      "overall": "regular"
    }
  }
}

POST/api/retailer/try-on

Create a virtual try-on session and save the results for analytics.

Request

POST /api/retailer/try-on
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "clothing_item_id": "64a1b2c3d4e5f6789...",
  "user_id": "customer-external-id",
  "measurements": {
    "chest": 96,
    "waist": 82,
    "hips": 98
  }
}

Response

{
  "ok": true,
  "data": {
    "session_id": "sess_abc123...",
    "recommended_size": "M",
    "confidence_score": 92,
    "fit_notes": "Size M provides the best overall fit based on the provided measurements.",
    "created_at": "2026-03-27T10:30:00Z"
  }
}

Rate Limits

Plan	Requests/Min	Try-Ons/Month
Free	60	100
Professional	600	10,000
Enterprise	Custom	Custom

Ready to integrate Roman into your platform?