## The plan of a project: its items, milestones, dependencies and findings (desk:read)

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

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

Items the caller does not see are left out, and so are dependencies to them. Findings flag delays and conflicts as of today; nothing is moved – reschedule an item with PATCH /items/{ref} (startOn, dueAt) at its version.

### Parameters

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

### Responses

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

Fields of the 200 answer:

- `dependencies` (array of ItemDependency): Only between visible items
  - `createdAt` (string (date-time), read-only): When it was created
  - `createdBy` (string, read-only): Login (e-mail) of who created it
  - `id` (string, read-only): Id of the dependency
  - `kind` (string): Kind of dependency (one of `finish_to_start`)
  - `lagDays` (integer): Days between the predecessor's end and the successor's start; negative = overlap (max 365)
  - `predecessorId` (string): Item that has to end first
  - `projectId` (string, read-only): Project of the dependency
  - `successorId` (string): Starts lagDays after the predecessor ended (finish-to-start)
- `findings` (array of PlanFinding): What the plan flags
  - `days` (integer): By how many days (conflict, late, at_risk)
  - `dependencyId` (string): Dependency concerned
  - `itemId` (string): Item concerned
  - `kind` (string): What the plan flags (one of `conflict`, `late`, `blocked`, `at_risk`, `milestone_late`, `undated`)
  - `milestoneId` (string): Milestone concerned
- `items` (array of object): The project's items the caller sees; endOn is the date of the due date (Europe/Berlin)
  - `assignees` (array of object): People working on the item
  - `endOn` (string (date), nullable): End of the item
  - `estimateMinutes` (integer, nullable): Estimate in minutes
  - `id` (string): Id of the item
  - `number` (integer): Number of the item
  - `parentId` (string, nullable): Parent item
  - `phase` (string): Phase of the status (one of `new`, `active`, `waiting`, `done`)
  - `projectMilestoneId` (string, nullable): Milestone of the item
  - `spaceId` (string): Space of the item
  - `spentMinutes` (integer, nullable): Work HR booked on the ticket; null when HR does not answer
  - `startOn` (string (date), nullable): Start of the item
  - `status` (string): Status key
  - `title` (string): Title
  - `typeId` (string): Type of the item
  - `version` (integer): Send it when rescheduling through PATCH /items/{ref}
- `milestones` (array of ProjectMilestone): Milestones of the project
  - `achievedAt` (string (date-time), nullable, read-only): When the milestone was reached
  - `achievedBy` (string, read-only): The person, or system for completion by items
  - `completion` (string): manual: achieved by hand; items: reached once all its items are done (and open again when one reopens) (one of `manual`, `items`)
  - `contractId` (string, read-only): Contract of a contract batch (empty otherwise)
  - `customerId` (string, read-only): The invoice's customer
  - `description` (string): Description of the milestone
  - `dueOn` (string (date)): Due date
  - `id` (string, read-only): Id of the milestone
  - `items` (integer, read-only): Visible items of the milestone (plan only)
  - `itemsDone` (integer, read-only): Visible items of the milestone that are done (plan only)
  - `label` (string, read-only): The unit as the invoice names it (project, contract, customer name)
  - `position` (integer): Position among the project's milestones
  - `projectId` (string, read-only): Project of a project batch (empty otherwise)
  - `scope` (string, read-only): (one of `project`, `contract`, `customer`)
  - `title` (string): Title of the milestone (max length 200)
  - `version` (integer): Version of the milestone; send it back on change
- `project` (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)
- `today` (string (date)): The day the findings are computed for (Europe/Berlin)

Example 200 answer:

```json
{
  "dependencies": [
    {
      "createdAt": "2026-11-02T07:30:00Z",
      "createdBy": "emma.maier@muster-it.example",
      "id": "8e5f6a7b-9c0d-4e1f-8a3b-5c6d7e8f9a01",
      "kind": "finish_to_start",
      "lagDays": 1,
      "predecessorId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d0b",
      "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
      "successorId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d0c"
    }
  ],
  "findings": [
    {
      "days": 5,
      "itemId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d0b",
      "kind": "late"
    },
    {
      "days": 3,
      "kind": "milestone_late",
      "milestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e03"
    }
  ],
  "items": [
    {
      "assignees": [
        {
          "role": "owner",
          "userRef": "emma.maier@muster-it.example"
        }
      ],
      "endOn": "2026-11-15",
      "estimateMinutes": null,
      "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d09",
      "number": 56,
      "parentId": null,
      "phase": "active",
      "projectMilestoneId": null,
      "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
      "spentMinutes": 600,
      "startOn": "2026-11-10",
      "status": "in_arbeit",
      "title": "Datenübernahme",
      "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f06",
      "version": 3
    },
    {
      "assignees": [
        {
          "role": "owner",
          "userRef": "paul.schmid@muster-it.example"
        }
      ],
      "endOn": "2026-11-13",
      "estimateMinutes": 480,
      "id": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d0b",
      "number": 58,
      "parentId": "4a1b2c3d-5e6f-4a7b-8c9d-1e2f3a4b5d09",
      "phase": "active",
      "projectMilestoneId": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e03",
      "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
      "spentMinutes": 540,
      "startOn": "2026-11-12",
      "status": "in_arbeit",
      "title": "Probeimport und Prüfung",
      "typeId": "5d2e3f4a-6b7c-4d8e-9f0a-2b3c4d5e6f07",
      "version": 4
    }
  ],
  "milestones": [
    {
      "achievedAt": null,
      "completion": "items",
      "dueOn": "2026-11-15",
      "id": "6c3d4e5f-7a8b-4c9d-8e1f-3a4b5c6d7e03",
      "items": 3,
      "itemsDone": 1,
      "position": 2,
      "projectId": "5b2c3d4e-6f7a-4b8c-9d0e-2f3a4b5c6d01",
      "scope": "project",
      "title": "Daten übernommen",
      "version": 1
    }
  ],
  "project": {
    "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",
    "responsibleRef": "emma.maier@muster-it.example",
    "spaceId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7d00",
    "startOn": "2026-11-02",
    "status": "laufend",
    "title": "ERP-Einführung Donau Maschinenbau",
    "version": 6
  },
  "today": "2026-11-18"
}
```

### Example request

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