> For the complete documentation index, see [llms.txt](https://doc.aihomedesign.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.aihomedesign.com/resources/migrating-from-v1.md).

# Migrating from V1

V3 replaces the V1 API entirely. This page maps every V1 concept and endpoint to its V3 equivalent so you can migrate without guessing.

***

### Concept Mapping

| V1                                                 | V3                                                                       | Notes                                        |
| -------------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------- |
| `service_name` (e.g. `service-ai-virtual-staging`) | `tool` slug (e.g. `tool-virtual-staging`)                                | Same idea, new naming scheme                 |
| `space_name` (e.g. `space-bedroom`)                | Widget item slug (e.g. `item-bedroom-widget-space-tool-virtual-staging`) | Now part of the `widgets` array              |
| Widget IDs (numeric)                               | Widget & item slugs (string)                                             | Slugs are human-readable and self-describing |
| No project concept                                 | `POST /v3/project`                                                       | Orders must now belong to a project          |

***

### Endpoint Mapping

| V1 endpoint            | V3 equivalent       | Key difference                                                                     |
| ---------------------- | ------------------- | ---------------------------------------------------------------------------------- |
| `POST /v1/order/image` | `POST /v3/order`    | Upload + order creation are now one call; returns `order_id` **and** `assets[].id` |
| `POST /v1/order`       | `POST /v3/process`  | The "submit order" step is now called "create process"                             |
| `GET /v1/order/:id`    | `GET /v3/order/:id` | Response includes full `processes` array with results                              |

***

### Migration Steps

1. **Create a project** for each property you work with (`POST /v3/project`) — there is no V1 equivalent.
2. **Replace your image upload call** — instead of `POST /v1/order/image`, use `POST /v3/order` (multipart). It returns both `order_id` and asset IDs in one response.
3. **Replace your order submission call** — instead of `POST /v1/order` with `service_name` and `space_name`, use `POST /v3/process` with:
   * `tool` (slug)
   * `asset_map` (maps input slot slug → asset ID)
   * `widgets` (array of `{ slug, item_slugs }`)
4. **Update your webhook handler** — the V3 payload shape is richer; check Webhook Reference for the exact fields.

***

### Example: V1 vs V3 Side by Side

**V1 — upload image:**

```bash
curl --location 'https://api.aihomedesign.com/v1/order/image' \
  --header 'x-api-key: <key>' \
  --form 'image=@"/path/to/room.jpg"' \
  --form 'service_name="service-ai-virtual-staging"'
# → returns { "order_id": "..." }
```

**V3 — create order:**

```bash
curl --location 'https://api.aihomedesign.com/v3/order' \
  --header 'x-api-key: <key>' \
  --form 'project_id="<project_id>"' \
  --form 'asset_file=@"/path/to/room.jpg"'
# → returns { "order_id": "...", "assets": [{ "id": "...", ... }] }
```

**V1 — submit order:**

```bash
curl --location 'https://api.aihomedesign.com/v1/order' \
  --header 'x-api-key: <key>' \
  --data '{
    "order_id": "...",
    "service_name": "service-ai-virtual-staging",
    "space_name": "space-bedroom",
    "widget_ids": [12, 34]
  }'
```

**V3 — create process:**

```bash
curl --location 'https://api.aihomedesign.com/v3/process' \
  --header 'x-api-key: <key>' \
  --data '{
    "order_id": "...",
    "tool": "tool-virtual-staging",
    "asset_map": {
      "tool-virtual-staging-input-image": "<asset_id>"
    },
    "widgets": [
      {
        "slug": "widget-space-tool-virtual-staging",
        "item_slugs": ["item-bedroom-widget-space-tool-virtual-staging"]
      },
      {
        "slug": "widget-style-tool-virtual-staging",
        "item_slugs": ["item-modern-widget-style-tool-virtual-staging"]
      }
    ]
  }'
```