API Reference

Everything on this page happens between your server and ours. Your API key is a secret: keep it on your server, never in a browser page, a mobile app or a public repository.

1. 1Get API access. Growth and Professional create a key in the dashboard. Free and Starter request access first. See Plans and API access.
2. 2Exchange the key for tokens. POST /auth/token returns an access token (valid 24 hours) and a refresh token (valid 30 days). Do this once, then reuse the access token.
3. 3Send a photo. POST /analyze with the access token. This is the only call that uses up your scan quota. It can take 20 seconds or more.
4. 4Read the result. Scores, grades and suggestions for the conditions in your plan. Show the results the way described in Using the results responsibly.
5. 5Fetch overlay images (optional). GET /analyze/{request_id}/assets, for scans you sent with collect_image=true.

Which calls use up scans

Before you start

• An account on app.rupam.ai and API access for it (see the next section).
• A server that can keep a secret and call https://api.rupam.ai.
• A face photo that meets the photo rules: JPEG or PNG, one person, clearly visible.
• The person's consent to send their photo (see Using the results responsibly).

What you can do through the API depends on your plan. Prices are on the Pricing page; this table shows what each plan gives an API customer.

Which conditions each plan returns is listed in the Conditions reference. The limits are per account, not per key: see Rate limits and quotas.

What appears in plan.features

API keys authenticate your server with the Rupam platform. Which plan you are on decides how you get one; see Plans and API access.

sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Rupam uses a two-step auth flow. Your API key is a long-lived credential; exchange it for short-lived access and refresh tokens to make API calls.

curl -X POST https://api.rupam.ai/rupam/v1/auth/token \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_expires_in": 2592000,
  "plan": {
    "plan_id": "growth",
    "rpm": 150,
    "rph": 300,
    "rpd": 2000,
    "rpp": 10000,
    "features": ["analyze", "makeup_tryon", "product_recommendations", "api_keys", "routine_builder"],
    "allowed_conditions": ["acne", "pores", "dark_circles", "pigmentation", "wrinkles", "oiliness", "redness", "texture", "skin_age", "fine_lines", "eye_bags", "blackheads"]
  }
}

Authorization: Bearer <access_token>

curl -X POST https://api.rupam.ai/rupam/v1/auth/refresh \
  -H "Authorization: Bearer <refresh_token>"

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_expires_in": 2592000,
  "plan": {
    "plan_id": "growth",
    "rpm": 150,
    "rph": 300,
    "rpd": 2000,
    "rpp": 10000,
    "features": ["analyze", "makeup_tryon", "product_recommendations", "api_keys", "routine_builder"],
    "allowed_conditions": ["acne", "pores", "dark_circles", "pigmentation", "wrinkles", "oiliness", "redness", "texture", "skin_age", "fine_lines", "eye_bags", "blackheads"]
  }
}

import time, httpx

BASE_URL = "https://api.rupam.ai/rupam/v1"

class RupamAuth:
    """Keeps one access token, renews it early, and falls back to the API key."""

    def __init__(self, api_key):
        self.api_key = api_key
        self.access = self.refresh = None
        self.expires_at = 0

    def _store(self, data):
        self.access = data["access_token"]
        self.refresh = data["refresh_token"]                     # rotated: keep the newest
        self.expires_at = time.time() + data["expires_in"] - 3600  # renew an hour early

    def renew(self):
        if self.refresh:
            r = httpx.post(f"{BASE_URL}/auth/refresh", headers={"Authorization": f"Bearer {self.refresh}"})
            if r.status_code == 200:
                return self._store(r.json())
        r = httpx.post(f"{BASE_URL}/auth/token", headers={"Authorization": f"Bearer {self.api_key}"})
        r.raise_for_status()
        self._store(r.json())

    def headers(self):
        if time.time() >= self.expires_at:
            self.renew()
        return {"Authorization": f"Bearer {self.access}"}

const BASE_URL = "https://api.rupam.ai/rupam/v1";

class RupamAuth {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.access = null;
    this.refresh = null;
    this.expiresAt = 0;
  }

  store(data) {
    this.access = data.access_token;
    this.refresh = data.refresh_token; // rotated: keep the newest
    this.expiresAt = Date.now() + (data.expires_in - 3600) * 1000; // renew an hour early
  }

  async renew() {
    if (this.refresh) {
      const r = await fetch(BASE_URL + "/auth/refresh", { method: "POST", headers: { Authorization: "Bearer " + this.refresh } });
      if (r.ok) return this.store(await r.json());
    }
    const r = await fetch(BASE_URL + "/auth/token", { method: "POST", headers: { Authorization: "Bearer " + this.apiKey } });
    if (!r.ok) throw new Error("Token exchange failed: " + r.status);
    this.store(await r.json());
  }

  async headers() {
    if (Date.now() >= this.expiresAt) await this.renew();
    return { Authorization: "Bearer " + this.access };
  }
}

Errors return a JSON body with a detail field, in one of three shapes. Check its type before you read it.

{ "detail": "Only JPEG/JPG and PNG images are allowed." }

{ "detail": { "error": "rate_limit_exceeded", "detail": "Rate limit of 150 req/min reached" } }

{ "detail": [ { "loc": ["query", "limit"], "msg": "Input should be greater than or equal to 1", "type": "greater_than_equal" } ] }

A string is a plain message, an object has a machine-readable error, and an array is a request-validation failure. An unexpected failure also carries a reference you can quote to us.

Error codes

What to retry

Limits belong to your account, not to a key. If you have created several keys, or use several products, they all draw from the same pool. The pool is shared by every endpoint that scans.

Your own limits are returned in the plan object of POST /auth/token and POST /auth/refresh.

• All four windows apply at the same time. Reaching any one returns HTTP 429 with that window's code.
• The plan period starts on the day your plan started, not on the 1st of the month.
• Sending the same photo again is a new request and uses a scan, even when the result comes from cache.
• A rejected photo (422) or a failed scan (5xx) is refunded and does not count.
• Only two scans are processed at once; the rest wait in a queue, so response time grows under load. Keep your own concurrency at or below two and allow up to 210 seconds.
• Extra scans beyond the plan period are available from Starter, if switched on in the dashboard. A failed payment stops scanning with 402 payment_failed.

Every object inside conditions[] shares this shape. grade and severity are both derived from score using the same thresholds, so they always agree with each other.

conditions[] contains only the conditions in your plan. Every condition has the shared fields described above (condition_id, condition_name, severity, score, grade, confidence, suggestions_key) plus the extra fields below. skin_type and skin_tone are returned on every plan in skin_profile.

• The results are cosmetic, not medical. Describe them as an assessment of visible skin features. Do not present them as a diagnosis or a treatment recommendation.
• Say that the result comes from AI. Where you show a result or a suggestion, show that it was produced by an automated analysis, and show the disclaimer when you use product recommendations.
• A face photo is personal data. You decide why and how you collect it, so you must tell the person what you do with it and get their consent where the law requires it, before you send it to the API. Send only what you need.
• You choose what we keep. With collect_image=false nothing is stored. With collect_image=true the photo and result images are stored for the retention period of your plan (see the plans table).
• Treat the skin tone as an estimate. Do not use it to make decisions about a person.

This is guidance for building with the API, not legal advice. See our Privacy Policy and Terms.

The REST API is not the only route. If you would rather not write server code:

Getting help

When you write to us, include the request_id of the scan (or the reference from an error), the time in UTC, the endpoint, the HTTP status and your plan. Never send your API key or a face photo by email.