## A project by id or number (desk:read)

`GET /api/desk/v1/projects/{id}`

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

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | Id or number |

### Responses

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

Fields of the 200 answer:

- `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)

Example 200 answer:

```json
{
  "archived": false,
  "budgetAmount": 22400,
  "budgetMinutes": 9600,
  "budgetState": "ok",
  "createdAt": "2026-11-02T07:30:00Z",
  "createdBy": "emma.maier@muster-it.example",
  "customFields": {
    "ansprechpartner_kunde": "Stefan Eder (IT-Leiter)",
    "auftragsnummer": "A-2026-0412"
  },
  "customer": {
    "id": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c21",
    "name": "Donau Maschinenbau AG"
  },
  "description": "Einführung der ERP-Lösung bei Donau Maschinenbau am Standort Neutraubling: Installation, Konfiguration, Datenübernahme, Schulung und Produktivstart.",
  "endOn": "2026-11-23",
  "id": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
  "itemsByPhase": {
    "active": 3,
    "done": 9,
    "new": 9,
    "waiting": 0
  },
  "number": 1,
  "phase": "active",
  "plannedMinutes": 8400,
  "responsibleName": "Emma Maier",
  "responsibleRef": "emma.maier@muster-it.example",
  "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
  "spentMinutes": 4260,
  "startOn": "2026-11-02",
  "status": "laufend",
  "ticketDisplay": "tickets",
  "title": "ERP-Einführung Donau Maschinenbau",
  "typeId": "6e3f4a5b-7c8d-4e9f-8a1b-3c4d5e6f7a01",
  "updatedAt": "2026-11-12T16:00:00Z",
  "updatedBy": "emma.maier@muster-it.example",
  "version": 6,
  "warnPercent": 80
}
```

### Example request

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