> 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/key-concepts/orders.md).

# Orders

### What is an Order?

An **Order** bundles one or more input images together and makes them ready for AI processing. Think of it as the "job ticket" — you create it once per set of input photos, then fire as many processes against it as you want.

An order has:

* **Entry assets** — the original uploaded images
* **Processes** — all AI jobs run against this order
* **Status** — `idle` while waiting, active during processing

#### Asset roles

| Role              | Description                                                        |
| ----------------- | ------------------------------------------------------------------ |
| `primary_angle`   | The main photo (required; only one allowed per order)              |
| `secondary_angle` | An additional angle of the same space (only one allowed per order) |
| `mask`            | A binary mask image used by mask-based tools                       |

***

### Create an Order (Upload Images)

```
POST https://api.aihomedesign.com/v3/order
x-api-key: <your_api_key>
Content-Type: multipart/form-data
```

| Form field    | Required     | Description                                                                               |
| ------------- | ------------ | ----------------------------------------------------------------------------------------- |
| `project_id`  | Optional     | ID of the project to attach this order to                                                 |
| `asset_file`  | At least one | Image file(s) to upload — repeat for multiple files                                       |
| `asset_roles` | Optional     | Role for each file — positionally aligned with `asset_files`, defaults to `primary_angle` |

**Single image:**

<pre class="language-bash"><code class="lang-bash"><strong>curl --location 'https://api.aihomedesign.com/v3/order' \
</strong>  --header 'x-api-key: &#x3C;your_api_key>' \
  --form 'project_id="6984bd700fc3c3c614c2bea5"' \
  --form 'asset_file=@"/path/to/room.jpeg"'
</code></pre>

**Two images — primary + secondary angle:**

```bash
curl --location 'https://api.aihomedesign.com/v3/order' \
  --header 'x-api-key: <your_api_key>' \
  --form 'project_id="6984bd700fc3c3c614c2bea5"' \
  --form 'asset_file=@"/path/to/house_front.jpeg"' \
  --form 'asset_file=@"/path/to/house_side.jpeg"' \
  --form 'asset_role="primary_angle"' \
  --form 'asset_role="secondary_angle"'
```

**Upload Mask Image (Item Removal Mask tool)**

<pre class="language-bash"><code class="lang-bash"><strong>curl --location 'https://api.aihomedesign.com/v3/order/:id/append' \
</strong>  --header 'x-api-key: &#x3C;your_api_key>' \
  --form 'project_id="6984bd700fc3c3c614c2bea5"' \
  --form 'asset_file=@"/path/to/mask.png"' \
  --form 'asset_role="mask"' \
  --form 'asset_type="mask"' \
</code></pre>

{% hint style="info" %}
A binary mask image — blue (**#7878CD**) pixels = remove | black pixels = keep
{% endhint %}

**Response (201 Created):**

```json
{
  "order_id": "69a6aa03a374700bff4a1328",
  "assets": [
    {
      "id": "69a6aa03a374700bff4a1327",
      "src": "https://cdn.aihomedesign.com/...",
      "asset_type": "image",
      "asset_role": "primary_angle"
    }
  ]
}
```

> **Save** the `order_id` and each asset `id` — you need them when creating a process.

***

### Fetch a Single Order

```
GET https://api.aihomedesign.com/v3/order/:id
x-api-key: <your_api_key>
```

Optional query params: `width`, `height` to resize image URLs.

**Response:**

```json
{
  "id": "69a6aa03a374700bff4a1328",
  "project_id": "6984bd700fc3c3c614c2bea5",
  "entry_assets": [
    {
      "id": "69a6aa03a374700bff4a1327",
      "asset_type": "image",
      "asset_role": "primary_angle",
      "src": "https://cdn.aihomedesign.com/...",
      "thumbnail_src": "https://cdn.aihomedesign.com/.../thumb"
    }
  ],
  "status": "idle",
  "created_at": "2025-07-05T10:00:00Z",
  "updated_at": "2025-07-05T10:00:00Z",
  "processes": [
    {
      "id": "69a6bb11a374700bff4a1333",
      "tool": "tool-virtual-staging",
      "status": "done",
      "final_assets": [...]
    }
  ]
}
```