# Projects

### List the projects in an account, newest first

`GET /accounts/{accountId}/projects`

**Required role:** reader

**Parameters**

- `cursor` _(query)_ · `string` · optional — Opaque cursor (page.nextCursor).
- `limit` _(query)_ · `number` · optional — Page size (1–100, default 20).
- `accountId` _(path)_ · `string` · required

**Returns**

- `200` · `ProjectsPageDto`

Attributes of `ProjectsPageDto`:

- `data` · `object[]` · read-only
- `page` · `object` · read-only

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects \
  -H "Authorization: Bearer kc_your_api_token"
```

**Example response** (`200`)

```json
{
  "data": [
    {
      "id": "acct_01example0000000000000000x",
      "accountId": "acct_01example0000000000000000x",
      "name": "my-app",
      "serviceCount": 0,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "page": {
    "nextCursor": "example",
    "hasMore": true
  }
}
```

### Create a project

`POST /accounts/{accountId}/projects`

**Required role:** admin

Creates the project and assigns it an immutable, account-unique word slug.

**Parameters**

- `accountId` _(path)_ · `string` · required

**Request body**

- `name` · `string` · required — The immutable identity name (url-safe word, 3-16 chars). Pick carefully — it cannot be renamed.

**Returns**

- `200` · `ProjectDto`

Attributes of `ProjectDto`:

- `id` · `string` · read-only
- `accountId` · `string` · read-only
- `name` · `string` · required — The project’s IDENTITY: an immutable, account-unique, url-safe word (namespaces this project’s environments in the cloud).
- `serviceCount` · `integer` · read-only — Total active services across all of the project’s environments (shown on the project card).
- `createdAt` · `string <date-time>` · read-only
- `updatedAt` · `string <date-time>` · read-only

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects \
  -X POST \
  -H "Authorization: Bearer kc_your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "my-app"
    }'
```

**Example response** (`200`)

```json
{
  "id": "acct_01example0000000000000000x",
  "accountId": "acct_01example0000000000000000x",
  "name": "my-app",
  "serviceCount": 0,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}
```

### Get a project

`GET /accounts/{accountId}/projects/{projectId}`

**Required role:** reader

**Parameters**

- `projectId` _(path)_ · `string` · required
- `accountId` _(path)_ · `string` · required

**Returns**

- `200` · `ProjectDto`

Attributes of `ProjectDto`:

- `id` · `string` · read-only
- `accountId` · `string` · read-only
- `name` · `string` · required — The project’s IDENTITY: an immutable, account-unique, url-safe word (namespaces this project’s environments in the cloud).
- `serviceCount` · `integer` · read-only — Total active services across all of the project’s environments (shown on the project card).
- `createdAt` · `string <date-time>` · read-only
- `updatedAt` · `string <date-time>` · read-only

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId \
  -H "Authorization: Bearer kc_your_api_token"
```

**Example response** (`200`)

```json
{
  "id": "acct_01example0000000000000000x",
  "accountId": "acct_01example0000000000000000x",
  "name": "my-app",
  "serviceCount": 0,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}
```

### Delete a project

`DELETE /accounts/{accountId}/projects/{projectId}`

**Required role:** admin

**Parameters**

- `projectId` _(path)_ · `string` · required
- `accountId` _(path)_ · `string` · required

**Returns**

- `204`

**Example request**

```bash
curl https://api.koo.io/accounts/:accountId/projects/:projectId \
  -X DELETE \
  -H "Authorization: Bearer kc_your_api_token"
```