# WEARFITS API Integration

A playbook for integrating the WEARFITS Virtual Try-On API directly over HTTP:
which endpoints to call, in what order, and how. The examples below are minimal
and illustrative — the authoritative, always-current contract (every field,
enum, and mode) is the OpenAPI spec:

- OpenAPI 3.1 spec (JSON): https://api.wearfits.com/doc
- Swagger UI (interactive): https://api.wearfits.com/reference

For a drop-in browser widget instead of a direct integration, see the
`wearfits-virtual-tryon-widget` skill.

## Authentication

Every `/api/*` request needs an `X-API-Key` header (keys are issued by WEARFITS).
Never ship a service key in client-side code — call the API from your backend,
or use a scoped browser/proxy token.

## Integration flow

### 1. Create or reuse a digital twin

A digital twin is a reusable avatar. `POST /api/v1/virtual-fitting` creates one
inline from a single body source — for example a face image + clothing size:

```json
{
  "faceImage": "https://example.com/face.jpg",
  "clothingSize": { "height": 170, "size": "M" },
  "gender": "female",
  "topGarment": "https://shop.example/shirt.jpg"
}
```

Other body sources: face + silhouette image, a full-body photo, or face + body
measurements. The completed job returns a `digitalTwinId` — save it and reuse it
to skip twin generation (cached ~30 days). See /doc for every mode.

### 2. Submit a virtual fitting

With a saved twin, `POST /api/v1/virtual-fitting` is just garments + the twin id:

```json
{
  "digitalTwinId": "<saved-twin-id>",
  "topGarment": "https://shop.example/shirt.jpg",
  "bottomGarment": "https://shop.example/jeans.jpg"
}
```

At least one clothing garment or `productImage` is required. Slot inputs (`topGarment` / `bottomGarment` / `fullBodyGarment`) take one image URL or a `[packshot, on-model]` pair; `shoes` is an optional add-on. For a single product image, send `productImage` with optional `productCategory` (default `auto`) so the generation model sees only the twin/person and the product image, without a garment grid. The response carries a job id and a status URL:

```json
{ "success": true, "jobId": "uuid", "status": "queued",
  "statusUrl": "https://api.wearfits.com/api/v1/jobs/uuid" }
```

### 3. Track the job

Poll `GET /api/v1/jobs/{jobId}` (about every 2.5 s, with a bounded retry cap)
until `status` is `completed` or `failed`:

```json
{ "id": "uuid", "status": "completed",
  "results": [{ "url": "https://.../result.png", "digitalTwinId": "..." }] }
```

Read `results[0].url` for the try-on image and `results[0].digitalTwinId` (or
the top-level `digitalTwinId`) to reuse the avatar. Or pass a `webhookUrl` on the
request to be notified server-to-server instead of polling.

## Endpoints you will use

| Endpoint | Use it for |
| --- | --- |
| `POST /api/v1/virtual-fitting` | Create the digital twin (inline) and run the try-on. |
| `GET /api/v1/jobs/{jobId}` | Poll job status and read results. |
| `GET /api/v1/digital-twin/{id}` | Check that a saved twin is still valid. |
| `POST /api/v1/shoe-3d` | Footwear: generate a 3D shoe model + AR try-on (separate pipeline). |

## Webhooks

Pass `webhookUrl` on a request to receive the completed job server-to-server.
Deliveries are signed with HMAC-SHA256 using SHA-256(your API key) as the
secret — verify the signature before trusting the payload.

## Things to know

- Virtual fitting is asynchronous: every submission returns a job to poll.
- Footwear-only AR try-on is the `shoe-3d` pipeline, not virtual-fitting.
- Job result URLs carry an expiry — copy or download them before they expire.
- The examples above are minimal; read /doc for the full schema before coding.

## Reference

- OpenAPI 3.1 spec: https://api.wearfits.com/doc
- Swagger UI: https://api.wearfits.com/reference
- Full agent context: https://api.wearfits.com/llms-full.txt