# Projects

Projects belong to the organization that creates them and group run sessions. A project's tasks are its sessions. Names keep their display case; matching accepts the exact name or slug without regard to case. A project is created explicitly; a run never creates one.

## The project object

| Field         | Type                       | Meaning                                                                                                                     |
| ------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string, 1 to 64 characters | No control characters.                                                                                                      |
| `slug`        | string                     | Lowercase words joined by `-`.                                                                                              |
| `counts`      | object                     | Tasks per column: `needs_you`, `running`, `done`, `failed`.                                                                 |
| `updated_at`  | date-time                  |                                                                                                                             |
| `now`         | list, up to 3              | What is running: `task_id`, `latest_run_id`, `title`, `workbench`, `source` (`cloud`), `text` (up to 140 characters), `at`. |
| `waiting`     | list                       | Tasks waiting on you: `task_id`, `latest_run_id`, `title`, `text`, `at`.                                                    |
| `latest_done` | object or null             | The latest completion: `task_id`, `latest_run_id`, `title`, `at`, `has_outcome`.                                            |
| `today`       | object                     | `runs`, `tokens`, `cost_usd` (or null).                                                                                     |

## List projects

`GET /v1/projects`

Key `runs:read`, or session: member.

| Query          | Type | Meaning        |
| -------------- | ---- | -------------- |
| `organization` | slug | For a session. |

Response `200` `{ "projects": [ ... ] }`.

## Create a project

`POST /v1/projects`

Key `runs:write`, or session: member.

| Field          | Type                       | Meaning        |
| -------------- | -------------------------- | -------------- |
| `name`         | string, 1 to 64 characters | Required.      |
| `organization` | slug                       | For a session. |

Response `201`: the project. Names and slugs are unique within the organization.

## List tasks

`GET /v1/projects/:slug/tasks`

Key `runs:read`, or session: member. Newest update first.

| Query          | Type | Meaning        |
| -------------- | ---- | -------------- |
| `organization` | slug | For a session. |

Response `200`:

```json
{
    "tasks": [
        {
            "id": "wbs_...",
            "project": { "name": "API", "slug": "api" },
            "source": "cloud",
            "title": "Review the open migration",
            "workbench": { "name": "code-review", "version": "1.2.0" },
            "status": "needs_input",
            "column": "needs_you",
            "latest_run_id": "wb_...",
            "needs_input": true,
            "created_at": "...",
            "updated_at": "..."
        }
    ]
}
```

`status` is the latest run's status. `column` is `needs_you`, `running`, `done`, or `failed`.

## Use a project

Pass `project` (name or slug) to `POST /v1/runs` or the MCP `run` tool. Filter runs and sessions with `project` on `GET /v1/runs` and `GET /v1/sessions`, or wait on a whole project with the MCP `wait` tool. Project and task changes are published on the [realtime socket](/docs/api/events#realtime) under `project:<slug>`.

Projects on workbenches.dev are separate from the local projects `wb project` manages on your machine.