## Projects with spent time and budget state (desk:read)

`GET /api/desk/v1/projects`

Module: Desk · operationId: `listProjects` · Tag: Projects · Auth: access token (`Authorization: Bearer <accessToken>`)

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `q` | query | string |  |  |
| `status` | query | string |  | Comma-separated statuses |
| `phase` | query | string |  | Comma-separated phases (new, active, waiting, done) of the projects' statuses – of their type's workflow, or of the built-in statuses |
| `customer` | query | string |  |  |
| `spaceId` | query | string |  | Home space of the projects (id or key); an unknown space gives an empty list |
| `type` | query | string |  | Project type of the projects (id or key); an unknown type gives an empty list |
| `responsible` | query | string |  | Responsible person of the projects: `me` (the caller) or a person reference |
| `archived` | query | boolean |  |  |
| `limit` | query | integer |  | (max 500) |
| `offset` | query | integer |  |  |

### Responses

- **200** Projects (`application/json`)

Fields of the 200 answer:

- `items` (array of Project)
  - `spaceId` (string, required): Home space of the project (id or key on input, always the id in responses); must be an active space of the tenant. Required when a project is created; an update without it keeps the stored space
  - `title` (string, required): Title of the project (max length 200)
  - `archived` (boolean): Archived: the project is kept for existing data but no longer offered in pickers
  - `budgetAmount` (number, nullable): Budget as a net amount (EUR)
  - `budgetMinutes` (integer, nullable): Time budget; the warning uses it
  - `budgetState` (string, read-only): Absent without a time budget or while the spent time is unknown (one of `ok`, `warning`, `exceeded`)
  - `createdAt` (string (date-time), read-only): When the project was created
  - `createdBy` (string, read-only): Login (e-mail) of who created the project
  - `customFields` (object): Values of the type's layout fields, keyed by field key ("cf." optional on input)
  - `customer` (Ref | null): Masterdata customer of the project
  - `description` (string): Description of the project
  - `endOn` (string (date), nullable): Planned end
  - `flatRateArticle` (object, nullable): No longer used: flat-rate articles are chosen on HR's work entries (ADR 0040); ignored on write and no longer returned
  - `hourlyRate` (number, nullable): No longer used: hourly rates of projects are HR's work rates with the project reference (ADR 0040); ignored on write and no longer returned
  - `id` (string, read-only): Id of the project
  - `itemsByPhase` (object, read-only): In lists only: the project's tickets by phase (new, active, waiting, done), counted like the project summary (merged tickets left out)
  - `number` (integer, read-only): Project number, unique in the tenant
  - `phase` (string, read-only): Phase of the status (one of `new`, `active`, `waiting`, `done`)
  - `plannedMinutes` (integer, nullable): Planned effort in minutes
  - `responsibleName` (string): Name of the person responsible
  - `responsibleRef` (string): Login (e-mail) of the person responsible
  - `spentMinutes` (integer, nullable, read-only): Work HR booked with the project as reference (`desk:project:<id>`, worked minus breaks, ADR 0040); null when HR does not answer
  - `startOn` (string (date), nullable): Planned start
  - `status` (string): A status of the type's workflow (default its initial status; changes follow its transitions); without type planned, active, on_hold, done or cancelled
  - `ticketDisplay` (string): How the project's tickets show in the ticket lists and boards: `tickets` as ordinary tickets, `projects` only on the projects page, `hidden` not in the lists (unless assigned to the viewer). An update without it keeps the stored value (one of `tickets`, `projects`, `hidden`; default `"tickets"`)
  - `typeId` (string, nullable): Project type (id or key on input); null: the built-in statuses and no custom fields
  - `updatedAt` (string (date-time), read-only): When the project was last changed
  - `updatedBy` (string, read-only): Login (e-mail) of who last changed the project
  - `version` (integer): Version of the project; send it back on change (409 version_conflict when it is outdated)
  - `warnPercent` (integer): Budget warning from this share (default 80) (max 100)
- `total` (integer)

Example 200 answer:

```json
{
  "items": [
    {
      "budgetAmount": 22400,
      "budgetMinutes": 9600,
      "budgetState": "ok",
      "createdAt": "2026-11-02T07:30:00Z",
      "customer": {
        "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c21",
        "name": "Donau Maschinenbau AG"
      },
      "endOn": "2026-11-23",
      "id": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
      "number": 1,
      "phase": "active",
      "responsibleName": "Emma Maier",
      "responsibleRef": "emma.maier@muster-it.example",
      "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
      "spentMinutes": 4260,
      "startOn": "2026-11-02",
      "status": "laufend",
      "title": "ERP-Einführung Donau Maschinenbau",
      "typeId": "6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01",
      "updatedAt": "2026-11-12T16:00:00Z",
      "version": 6
    }
  ],
  "total": 1
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/projects' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
