> ## Documentation Index
> Fetch the complete documentation index at: https://docs.drssed.app/llms.txt
> Use this file to discover all available pages before exploring further.

# How to create and manage outfits with Drssed API

> Learn how to create outfits, build visual scenes from clothing items, and manage outfit metadata like seasons, tags, and visibility settings.

This guide covers everything you need to work with outfits in the Drssed API. An outfit groups clothing items together and arranges them in a visual scene — a canvas where each item has a position, scale, and rotation. You will learn how to create an outfit with a scene, list and retrieve outfits, update outfit details, and delete outfits you no longer need.

<Note>
  The `scene` array defines how clothing items are visually arranged in the outfit collage. Each entry is a `CanvasPlacement` object that references a clothing item by its `clothing_id` and specifies its position (`x`, `y`), depth (`z`), `scale`, and `rotation`.
</Note>

<Steps>
  <Step title="Create an outfit">
    Call `POST /users/me/outfits` to create a new outfit. At minimum you must provide a `name`. You can optionally include a description, a scene layout, seasons, tags, and visibility settings.

    **Body fields:**

    | Field         | Type                | Required | Description                                                                  |
    | ------------- | ------------------- | -------- | ---------------------------------------------------------------------------- |
    | `name`        | string              | Yes      | Display name for the outfit                                                  |
    | `description` | string              | No       | Optional freeform description                                                |
    | `scene`       | array of placements | No       | Visual layout of clothing items (see below)                                  |
    | `seasons`     | array of strings    | No       | `Spring`, `Summer`, `Autumn`, `Winter`                                       |
    | `tags`        | array of strings    | No       | `Casual`, `Formal`, `Sports`, `Vintage`, `Outdoor`, `Party`, `Work`, `Beach` |
    | `is_public`   | boolean             | No       | Whether other users can see this outfit (default: `false`)                   |
    | `is_favorite` | boolean             | No       | Mark as a favorite (default: `false`)                                        |

    Each object in the `scene` array must include:

    | Field         | Type   | Description                           |
    | ------------- | ------ | ------------------------------------- |
    | `clothing_id` | string | ID of an existing clothing item       |
    | `x`           | float  | Horizontal position on the canvas     |
    | `y`           | float  | Vertical position on the canvas       |
    | `z`           | int    | Stacking order (higher = in front)    |
    | `scale`       | float  | Size multiplier (1.0 = original size) |
    | `rotation`    | float  | Rotation in degrees                   |

    ```bash theme={null}
    curl -X POST https://api.drssed.com/users/me/outfits \
      -H "Authorization: Bearer {token}" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Weekend casual",
        "description": "Relaxed look for a weekend outing",
        "seasons": ["Spring", "Autumn"],
        "tags": ["Casual"],
        "is_public": false,
        "is_favorite": true,
        "scene": [
          {
            "clothing_id": "clo_abc001",
            "x": 120.0,
            "y": 80.0,
            "z": 1,
            "scale": 1.0,
            "rotation": 0.0
          },
          {
            "clothing_id": "clo_abc002",
            "x": 120.0,
            "y": 260.0,
            "z": 0,
            "scale": 1.0,
            "rotation": 0.0
          }
        ]
      }'
    ```

    A successful response returns `201 Created` with the new outfit:

    ```json theme={null}
    {
      "outfit": {
        "outfit_id": "out_xyz001",
        "user_id": "usr_000111",
        "name": "Weekend casual",
        "description": "Relaxed look for a weekend outing",
        "is_public": false,
        "is_favorite": true,
        "seasons": ["Spring", "Autumn"],
        "tags": ["Casual"],
        "scene": [
          {
            "clothing_id": "clo_abc001",
            "x": 120.0,
            "y": 80.0,
            "z": 1,
            "scale": 1.0,
            "rotation": 0.0
          },
          {
            "clothing_id": "clo_abc002",
            "x": 120.0,
            "y": 260.0,
            "z": 0,
            "scale": 1.0,
            "rotation": 0.0
          }
        ],
        "created_at": "2024-06-01T11:00:00+00:00",
        "updated_at": "2024-06-01T11:00:00+00:00"
      }
    }
    ```
  </Step>

  <Step title="List outfits">
    You have two options for listing outfits depending on whose wardrobe you are viewing.

    <Info>
      `GET /users/me/outfits` returns **all** of your outfits, including private ones. `GET /users/{user_id}/outfits` returns only the **public** outfits for a given user. Use the `/me` route when building your own wardrobe view; use the `/{user_id}` route when displaying another user's public outfits.
    </Info>

    Both routes accept `limit` (default `50`) and `offset` (default `0`) for pagination.

    ```bash theme={null}
    curl "https://api.drssed.com/users/me/outfits?limit=20&offset=0" \
      -H "Authorization: Bearer {token}"
    ```

    The response includes the outfit list alongside pagination metadata:

    ```json theme={null}
    {
      "limit": 20,
      "offset": 0,
      "total": 5,
      "items": [
        {
          "outfit_id": "out_xyz001",
          "name": "Weekend casual",
          "is_public": false,
          "is_favorite": true,
          "seasons": ["Spring", "Autumn"],
          "tags": ["Casual"],
          "created_at": "2024-06-01T11:00:00+00:00",
          "updated_at": "2024-06-01T11:00:00+00:00"
        }
      ]
    }
    ```
  </Step>

  <Step title="Get a specific outfit">
    Retrieve the full details of a single outfit — including its complete scene array — with `GET /outfits/{outfit_id}`.

    ```bash theme={null}
    curl https://api.drssed.com/outfits/out_xyz001 \
      -H "Authorization: Bearer {token}"
    ```

    ```json theme={null}
    {
      "outfit": {
        "outfit_id": "out_xyz001",
        "user_id": "usr_000111",
        "name": "Weekend casual",
        "description": "Relaxed look for a weekend outing",
        "is_public": false,
        "is_favorite": true,
        "seasons": ["Spring", "Autumn"],
        "tags": ["Casual"],
        "scene": [
          {
            "clothing_id": "clo_abc001",
            "x": 120.0,
            "y": 80.0,
            "z": 1,
            "scale": 1.0,
            "rotation": 0.0
          },
          {
            "clothing_id": "clo_abc002",
            "x": 120.0,
            "y": 260.0,
            "z": 0,
            "scale": 1.0,
            "rotation": 0.0
          }
        ],
        "created_at": "2024-06-01T11:00:00+00:00",
        "updated_at": "2024-06-01T11:00:00+00:00"
      }
    }
    ```
  </Step>

  <Step title="Update an outfit">
    Use `PATCH /outfits/{outfit_id}` to update any subset of fields. All fields are optional — only what you include is changed. To rearrange items in the scene, pass the full updated `scene` array.

    **Updatable fields:** `name`, `is_favorite`, `is_public`, `seasons`, `tags`, `scene`

    ```bash theme={null}
    curl -X PATCH https://api.drssed.com/outfits/out_xyz001 \
      -H "Authorization: Bearer {token}" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Weekend casual (updated)",
        "is_public": true,
        "tags": ["Casual", "Outdoor"]
      }'
    ```

    A successful update returns `200 OK` with the updated outfit object.
  </Step>

  <Step title="Delete an outfit">
    Remove an outfit with `DELETE /outfits/{outfit_id}`. Like clothing items, outfits are soft-deleted — they disappear from your list immediately but are not permanently erased right away.

    ```bash theme={null}
    curl -X DELETE https://api.drssed.com/outfits/out_xyz001 \
      -H "Authorization: Bearer {token}"
    ```

    A successful deletion returns `204 No Content` with an empty body.
  </Step>
</Steps>

## Rate limits

Most outfit endpoints are limited to **5 requests per minute**. The `PATCH /outfits/{outfit_id}` endpoint has a stricter limit of **3 requests per minute**.