> 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/projects.md).

# Projects

### What is a Project?

A **Project** is a top-level container that groups all the work done on a single property. It has an address, a cover image, and aggregated counts of input and result assets. Every order must belong to a project.

***

### Create a Project

```
POST https://api.aihomedesign.com/v3/project
x-api-key: <your_api_key>
Content-Type: application/json
```

| Field     | Type   | Required | Description              |
| --------- | ------ | -------- | ------------------------ |
| `address` | string | ✅        | Property address or name |

```bash
curl --location 'https://api.aihomedesign.com/v3/project' \
  --header 'x-api-key: <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{ "address": "123 Maple Street, Austin TX 78701" }'
```

**Response (201 Created):**

```json
{
  "id": "6984bd700fc3c3c614c2bea5",
  "address": "123 Maple Street, Austin TX 78701",
  "cover_src": "",
  "input_count": 0,
  "result_count": 0,
  "bookmarked_count": 0,
  "default": false,
  "updated_at": "2025-07-05"
}
```

***

### Fetch a Single Project

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

| Query param | Description                       |
| ----------- | --------------------------------- |
| `width`     | Resize cover image to this width  |
| `height`    | Resize cover image to this height |

```bash
curl 'https://api.aihomedesign.com/v3/project/6984bd700fc3c3c614c2bea5' \
  --header 'x-api-key: <your_api_key>'
```

***

### List All Projects

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

| Query param        | Default | Description                  |
| ------------------ | ------- | ---------------------------- |
| `page`             | `1`     | Page number                  |
| `limit`            | `10`    | Results per page (max 30)    |
| `sort`             | `desc`  | `asc`, `desc`, or `modified` |
| `s`                | —       | Free-text search on address  |
| `width` / `height` | —       | Resize cover thumbnails      |

**Response:**

```json
{
  "data": [
    {
      "id": "6984bd700fc3c3c614c2bea5",
      "address": "123 Maple Street",
      "cover_src": "https://...",
      "input_count": 3,
      "result_count": 12,
      "bookmarked_count": 2,
      "default": false,
      "updated_at": "2025-07-05"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total_count": 24,
    "total_pages": 3,
    "previous_page": "",
    "next_page": "?page=2&limit=10"
  }
}
```

***

### Fetch Orders Inside a Project

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

Returns all orders that belong to the specified project, including their input assets and process results.

| Query param        | Default | Description                  |
| ------------------ | ------- | ---------------------------- |
| `page`             | `1`     | Page number                  |
| `limit`            | `10`    | Results per page (max 30)    |
| `sort`             | `desc`  | `asc`, `desc`, or `modified` |
| `width` / `height` | —       | Resize image thumbnails      |

```bash
curl 'https://api.aihomedesign.com/v3/project/6984bd700fc3c3c614c2bea5/order' \
  --header 'x-api-key: <your_api_key>'
```