Documentation

This page describes the public HTTP surface for creating and managing try-on sessions. It is designed to be useful before implementation, so it includes request shapes, error behavior, and rollout notes rather than just a feature list.

Base URL

https://api.tryon-api.com/v1

Auth model

Bearer token in the Authorization header.

Last reviewed

March 24, 2026.

Quick start

A typical integration creates a session, receives a launch URL, and embeds that URL in a product page button or mobile handoff flow.

POST /v1/sessions
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "product_id": "sku-12345",
  "category": "footwear",
  "experience": "browser",
  "callback_url": "https://merchant.example/callbacks/tryon",
  "locale": "en-US"
}

Auth

All requests use a bearer token. Tokens should be stored server-side and never embedded directly in public client code.

Authorization: Bearer YOUR_API_TOKEN

Supported flows

Browser session

Opens a shareable launch URL for mobile web or embedded browser use.

QR handoff

Returns a QR asset for desktop-to-mobile transition.

Callback completion

Posts a completion payload to the configured callback URL when a session ends.

Objects

Session object

Represents a generated try-on session and includes a status, launch URL, expiry, and category-specific metadata.

Asset object

Represents product media or model assets associated with a session request.

Callback payload

Includes session ID, completion state, timestamps, and any configured merchant reference IDs.

Example request and response

POST /v1/sessions
{
  "product_id": "sku-12345",
  "category": "footwear",
  "experience": "browser",
  "callback_url": "https://merchant.example/callbacks/tryon",
  "locale": "en-US"
}

200 OK
{
  "id": "tsn_01HZZXYZ123",
  "status": "ready",
  "launch_url": "https://launch.tryon-api.com/s/tsn_01HZZXYZ123",
  "expires_at": "2026-03-24T18:00:00Z",
  "qr_code_url": "https://launch.tryon-api.com/qr/tsn_01HZZXYZ123.png"
}

Errors

400 Invalid request payload or unsupported category.

401 Missing or invalid bearer token.

404 Session not found.

429 Rate limit exceeded for the current plan.

500 Internal service error. Retry with exponential backoff.

Integration notes

  • Start with one category and instrument completion, launch, and callback events.
  • Keep tokens server-side and proxy session creation through your backend.
  • Test mobile web behavior on real devices before broad rollout.
  • Use the pricing page to map estimated session volume to the right plan.