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

# Projects

> Manage your real-estate catalog at the project level. CRUD operations on the parent of units.

A project is the top-level container for a real-estate development. It groups [units](/api-reference/units) and stores shared metadata (location, price band, amenities).

***

## List projects

```http theme={null}
GET /projects
```

**Scope:** `projects:read`. Paginated.

### Query parameters

| Param                                   | Notes                                                                     |
| --------------------------------------- | ------------------------------------------------------------------------- |
| `limit`, `offset`, `sortOrder`, `query` | See [Pagination](/pagination). `query` matches name, city, and promotora. |
| `type`                                  | Filter by project type.                                                   |
| `status`                                | Filter by `draft`, `published`, or `archived`.                            |
| `city`                                  | Filter by city (partial match).                                           |

### Response 200

Paginated `data[]`. Each item includes a `unitCount` derived field.

```json theme={null}
{
  "id": "proj_...",
  "name": "Bavarian Forest",
  "type": "residential",
  "promotora": "Acme Developers",
  "city": "Punta Cana",
  "address": "Av. Estados Unidos #1",
  "description": "...",
  "country": "DO",
  "state": "La Altagracia",
  "operationType": "sale",
  "currency": "USD",
  "salePrice": 250000,
  "rentPrice": null,
  "minPrice": 180000,
  "maxPrice": 320000,
  "bedrooms": 2,
  "bathrooms": 2.5,
  "parkingSpots": 1,
  "builtArea": 110,
  "lotArea": 0,
  "status": "published",
  "image": "https://cdn.flowestate.app/...",
  "unitCount": 24,
  "createdAt": "2025-08-01T12:00:00.000Z",
  "updatedAt": "2026-04-29T12:00:00.000Z"
}
```

***

## Create a project

```http theme={null}
POST /projects
```

**Scope:** `projects:write`.

### Request body

Only `name` is required. You can include an optional `units[]` array to create initial units in the same call.

```json theme={null}
{
  "name": "Bavarian Forest",
  "type": "residential",
  "promotora": "Acme Developers",
  "city": "Punta Cana",
  "address": "Av. Estados Unidos #1",
  "description": "...",
  "country": "DO",
  "state": "La Altagracia",
  "operationType": "sale",
  "currency": "USD",
  "salePrice": 250000,
  "rentPrice": null,
  "bedrooms": 2,
  "bathrooms": 2.5,
  "parkingSpots": 1,
  "builtArea": 110,
  "lotArea": 0,
  "status": "draft",
  "units": [
    { "name": "A-101", "type": "apartment", "price": 250000, "area": 110, "status": "available" }
  ]
}
```

`status`: `draft` | `published` | `archived` (default `draft`).

### Response 201

```json theme={null}
{
  "id": "proj_...",
  "name": "Bavarian Forest",
  "type": "residential",
  "city": "Punta Cana",
  "status": "draft",
  "unitCount": 1,
  "createdAt": "2026-04-29T18:04:15.000Z"
}
```

### Webhook side effects

A `project.created` event is dispatched. If `units[]` was provided, a `unit.created` event also fires for each unit.

***

## Get a project

```http theme={null}
GET /projects/{projectId}
```

**Scope:** `projects:read`. Includes the embedded `units[]` array with each unit's id, name, type, price, area, status, and timestamps.

***

## Update a project

```http theme={null}
PUT /projects/{projectId}
```

**Scope:** `projects:write`. All fields optional, must provide at least one.

### Webhook side effects

A `project.updated` event is dispatched.

***

## Delete a project

```http theme={null}
DELETE /projects/{projectId}
```

**Scope:** `projects:write`.

<Warning>Deleting a project also deletes all its units. This is irreversible.</Warning>

### Response 200

```json theme={null}
{ "deleted": true, "id": "proj_..." }
```

### Webhook side effects

A `project.deleted` event is dispatched.