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 spacetitle(string, required): Title of the project (max length 200)archived(boolean): Archived: the project is kept for existing data but no longer offered in pickersbudgetAmount(number, nullable): Budget as a net amount (EUR)budgetMinutes(integer, nullable): Time budget; the warning uses itbudgetState(string, read-only): Absent without a time budget or while the spent time is unknown (one ofok,warning,exceeded)createdAt(string (date-time), read-only): When the project was createdcreatedBy(string, read-only): Login (e-mail) of who created the projectcustomFields(object): Values of the type's layout fields, keyed by field key ("cf." optional on input)customer(Ref | null): Masterdata customer of the projectdescription(string): Description of the projectendOn(string (date), nullable): Planned endflatRateArticle(object, nullable): No longer used: flat-rate articles are chosen on HR's work entries (ADR 0040); ignored on write and no longer returnedhourlyRate(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 returnedid(string, read-only): Id of the projectitemsByPhase(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 tenantphase(string, read-only): Phase of the status (one ofnew,active,waiting,done)plannedMinutes(integer, nullable): Planned effort in minutesresponsibleName(string): Name of the person responsibleresponsibleRef(string): Login (e-mail) of the person responsiblespentMinutes(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 answerstartOn(string (date), nullable): Planned startstatus(string): A status of the type's workflow (default its initial status; changes follow its transitions); without type planned, active, on_hold, done or cancelledticketDisplay(string): How the project's tickets show in the ticket lists and boards:ticketsas ordinary tickets,projectsonly on the projects page,hiddennot in the lists (unless assigned to the viewer). An update without it keeps the stored value (one oftickets,projects,hidden; default"tickets")typeId(string, nullable): Project type (id or key on input); null: the built-in statuses and no custom fieldsupdatedAt(string (date-time), read-only): When the project was last changedupdatedBy(string, read-only): Login (e-mail) of who last changed the projectversion(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:
{
"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
curl -X GET 'https://api.mbcom.cloud/api/desk/v1/projects' \
-H "Authorization: Bearer $ACCESS_TOKEN"