---
title: Shoes & Bags AR Try-On — API Reference
product: ar-tryon
last_updated: '2026-09-22'
description: "Base URL: https://dev.wearfits.com"
---

# Shoes & Bags AR Try-On — API Reference

Base URL: `https://dev.wearfits.com`

---

## Authentication

All authenticated endpoints accept credentials via one of the following methods, checked in priority order:

### 1. Bearer Token (Recommended)

Include an API key or session token in the `Authorization` header:

```http
Authorization: Bearer your_api_key_here
```

API keys are created and managed at [dash.wearfits.com](https://dash.wearfits.com). This is the recommended method for server-to-server integrations.

### 2. Dashboard session

If the caller is logged into the WEARFITS dashboard in the same browser, the session is sent automatically. No additional headers are required. Server-to-server integrations should use an API key.

### 3. Query Parameter (Legacy, Discouraged)

```
GET /some/endpoint?token=your_token_here
```

This method may leak tokens in server logs and referrer headers. Avoid it in new integrations.

---

### API Key Validation

When a Bearer token is an API key created at `dash.wearfits.com`, it is validated against the following rules:

| Condition | Rejection reason |
|-----------|-----------------|
| Key not found in database | `not_found` |
| Key has `isActive = false` | `inactive` |
| `expiresAt` is set and in the past | `expired` |
| `maxUsage > 0` and `usageCount >= maxUsage` | `over_limit` |

All validation failures return HTTP **401** with error code `invalid_api_key`. Usage is incremented only on successful requests.

---

## Model Upload API

### `POST /tryon/api/upload_shoe`

Upload a binary GLB shoe model. On success the system automatically creates a new object and queues it for the Autofit processing pipeline.

**Authentication required:** API key from dash.wearfits.com, or a dashboard session in the same browser.

**Content-Type:** `multipart/form-data`

#### Request fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file` | file | Yes | Binary `.glb` file, maximum **30 MB** |
| `token` | string | No | Alternative authentication token (query/body parameter) |

#### Example request

```bash
curl -X POST https://dev.wearfits.com/tryon/api/upload_shoe \
  -H "Authorization: Bearer your_api_key_here" \
  -F "file=@shoe_model.glb"
```

#### Response — 200 OK

```json
{
    "id": "e84bc8b8afb5e6973556e376f0b942ab",
    "color_id": "default",
    "viewer_url": "https://app.wearfits.com/viewer?object=e84bc8b8afb5e6973556e376f0b942ab"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique object identifier (hex string) |
| `color_id` | string | Color/material variant identifier |
| `viewer_url` | string | Direct URL to preview the uploaded model in the 3D viewer |

#### Error responses

| HTTP Status | Error Code | Description |
|-------------|------------|-------------|
| 400 | `no_file` | No `.glb` file was included in the request |
| 400 | `file_too_large` | File exceeds the 30 MB limit |
| 401 | `unauthorized` | Missing or invalid authentication |
| 401 | `invalid_api_key` | API key is inactive, expired, or over quota |

---

## Autofit Status API

After a successful upload, the model enters the Autofit queue where it is automatically aligned and optimized for the try-on engine. Use this endpoint to poll processing progress.

### `GET /tryon/api/autofit_status`

**Authentication required:** No (public endpoint)

#### Query parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `id` | Yes | Object ID returned by `upload_shoe` |
| `color_id` | No | Color/material variant ID (defaults to `default`) |

#### Example request

```bash
curl "https://dev.wearfits.com/tryon/api/autofit_status?id=e84bc8b8afb5e6973556e376f0b942ab"
```

#### Response — 200 OK

```json
{
    "status": "finished",
    "progress": 100,
    "glb_url": "https://storage.googleapis.com/.../object.glb"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `status` | string | Current processing state (see values below) |
| `progress` | number | Completion percentage, 0–100 |
| `glb_url` | string | URL of the processed GLB file (present only when `status` is `finished`) |

When processing finishes, the response can also include `object_properties`. Public autofit metadata omits `created`, `createdBy`, `modifiedBy`, `owner`, `modified`, `model_url`, `custom`, and `materialsData`.
#### Status values

| Value | Description |
|-------|-------------|
| `in_queue` | Waiting for an available processing slot |
| `in_progress` | Actively being processed |
| `exporting` | Generating the final optimized GLB |
| `finished` | Model is ready for use in the viewer |
| `failed` | Processing encountered an unrecoverable error |

---
## Object & Asset API

These endpoints manage 3D objects, materials, and asset files. Most are public unless noted.

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/get_models` | List all available models (filtered by ownership when authenticated) |
| GET | `/api/get_object_properties/:name` | Retrieve properties for a named object |
| GET | `/api/get_materials/:name` | Retrieve materials for a named object |
| POST | `/api/set_object_properties` | Update object properties |
| POST | `/api/set_materials` | Update materials for an object |
| POST | `/api/upload_textures` | Upload texture files for an object |
| POST | `/api/upload_mesh` | Upload a mesh file for an object |
| POST | `/api/replace_mesh` | Replace the existing mesh of an object |
| POST | `/api/bake` | Bake textures for an object |
| POST | `/api/claim_object` | Claim ownership of an object |
| GET | `/api/get_gltf/:name` | Download the GLTF file for a named object |
| GET | `/api/get_usdz/:name` | Download the USDZ file for a named object |

For public metadata, `created`, `createdBy`, `modifiedBy`, `owner`, and `modified` are returned by `/api/get_object_properties/:name` only to the owner, a member of the same group, or an admin/low admin; `protected` does not hide them. `/api/get_materials/:name` includes these fields only for admins. The hosted viewer provides public fallback endpoints (no authentication required): `GET /tryonapi/get_object_properties/:name` and `GET /tryonapi/get_materials/:name`. Their responses always omit `created`, `createdBy`, `modifiedBy`, `owner`, and `modified`. The materials fallback accepts an optional `color_id` query parameter, uses `default` when it is omitted, and returns the requested preset plus the corresponding `<color_id>_mirror` preset when that mirror preset exists.
---
## Try-On API

Server-side endpoints for programmatic try-on operations.

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/tryon/api/garment_fit_on` | Apply a garment to a provided image |
| POST | `/tryon/api/shoes_fit_on` | Apply shoes to a provided image |
| POST | `/tryon/api/report_bug` | Submit a bug report from a try-on session |

---

## Try-On Viewer Endpoints

These are browser-facing HTML routes that load the client-side try-on experience.

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/tryon` | Main try-on experience |
| GET | `/tryon/app` | Try-on application (full UI) |
| GET | `/tryon/editor` | Try-on editor for content management |
| GET | `/tryon/accessory-editor` | Accessory (bags, jewelry) try-on editor |

Viewer endpoints support a rich set of URL parameters for runtime configuration. Key parameters include:

| Parameter | Values | Description |
|-----------|--------|-------------|
| `pose_quality` | `1` / `2` / `3` | ML pose model quality: lite / full / heavy |
| `native_ml_size` | `160` / `192` / `256` | Input resolution for the ML model |
| `mirror_mode` / `mm` | `1`–`5` | Mirror display mode |
| `turbo` | `0` / `1` | Enable alternating ML/optical-flow pipeline |
| `no_logs` | `0` / `1` | Disable worker logging (15–30% performance gain) |
| `settings` | `0` / `1` | Show advanced settings panel |
| `async_mode` | `0` / `1` | Enable asynchronous processing mode |
| `debug` | `0` / `1` | Enable debug overlay |

---

## T4L Payload Behavior

T4L payloads may assign materials to named mesh parts. A visible structural part with `material: null` keeps the material embedded in the GLB. Parts sent with `visible: false` or an empty material object are dropped.

Optional overlays whose names start with `perforado_`, `grabado_`, `bordado_`, `picado_`, `ghost_`, or `reflejo_ghost_`, and floor meshes whose names start with `suelo`, are included only when the payload supplies a visible part with a non-empty material object. They are dropped when their material is null or empty, when `visible` is `false`, or when they are omitted from the parts map.

---
## Rate Limits & Constraints

| Constraint | Value |
|------------|-------|
| Maximum file size | 30 MB per upload |
| Accepted upload format | Binary `.glb` only |
| Batch uploads | Queued; track progress via `/tryon/api/autofit_status` |
| API key usage tracking | Incremented per successful request only |
| API key quota enforcement | Enforced when `maxUsage > 0` |