> 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"]
      }
    ]
  }'
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.aihomedesign.com/resources/migrating-from-v1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.