ConnectCloud Developers

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:

{
  "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"

View as Markdown · Interactive reference · OpenAPI