ConnectCloud Developers

Forge items

Forge is ConnectCloud's software development module: projects with a key (APP) and their items – bugs, stories, tasks – numbered per project (APP-12). Every project owns its configuration: statuses, workflows, item types, labels and custom fields. Everything below is under https://api.mbcom.cloud/api/forge/v1; every operation is in the Forge reference. Handing items to desk and back is the Handoff guide.

Step Operations Permission
Projects and configuration listForgeProjects, getForgeProjectConfig tenant:forge:read
Create createForgeItem tenant:forge:write, or a project member (reporters may create)
Find searchForgeItems, listForgeProjectItems, getForgeItem tenant:forge:read
Change and move patchForgeItem, transitionForgeItem, setForgeItemAssignees, setForgeItemLabels tenant:forge:write (developer or higher)
Discuss listForgeComments, createForgeComment tenant:forge:read

Projects are private (members only) or tenant (every forge reader); member roles are reporter < developer < maintainer < admin. A project or item the caller may not see answers 404, and so does a confidential item for everyone but forge admins, maintainers, its reporter and its assignees.

Read the project's configuration

Statuses, workflows, types, labels and fields belong to each project and differ between projects of one tenant. Read them per project with GET /projects/{key}/config:

curl 'https://api.mbcom.cloud/api/forge/v1/projects/APP/config' -H "Authorization: Bearer $ACCESS_TOKEN"
Key What you take from it
itemTypes[] id, key, name, level (a parent type has a higher level), workflowId, archived
statuses[] id, key, name, category, isDefault (where new items start)
workflows[] statusIds and transitions[] (fromStatusId → toStatusId; empty = any move allowed)
labels[], customFields[] label ids and names, custom field keys
itemTemplates[] templates that prefill type, title, description and labels

Keys never change, names may. The one thing every project shares is the status category of each status: triage, todo, active, on_hold, done and cancelled. Build your logic on categories ("is it done?", "move it to active"), not on status keys of one project. Single parts are also served by listForgeStatuses, listForgeWorkflows and listForgeItemTypes.

Create an item

curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/APP/items' \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "typeId": "<id of the type, from the configuration>",
    "title": "Export bricht bei Umlauten im Dateinamen ab",
    "description": "Schritte:\n1. Datei `Übersicht.csv` exportieren\n2. Fehler 500",
    "assignees": ["max.mustermann@muster-gmbh.example"],
    "labelIds": ["<label id>"]
  }'

Only title is required. Without typeId the project's default type is used, without statusId the default status of the type's workflow; templateKey fills what you leave out from an item template. parentNumber makes it a child of another item of the project (its type needs a higher level). The answer (201) is the item with number, ref (APP-12) and version. An archived project answers 409 project_archived.

Creating an item is not idempotent: after a timeout, search for it (q with the title) before creating it again.

Find items

searchForgeItems (GET /items) searches every project the caller sees, listForgeProjectItems one project (in rank order by default). Filters combine, lists are comma separated:

curl 'https://api.mbcom.cloud/api/forge/v1/items?project=APP&category=todo,active&assignee=me&sort=updated&limit=50' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

q (words in title or description, or a reference such as APP-12), project (keys), status (keys), category, type (keys), label (names; an item must carry all), assignee (me or an e-mail), milestone, iteration (active for the running one) and open (true open, false closed). Pass nextCursor as cursor for the next page (limit 1–200; see Pagination). Converted items are left out unless includeConverted=true.

getForgeItem (GET /items/APP-12) reads one item with its sections. An item moved to another project answers 404 moved with details.redirect naming its new reference; the tombstone of an item converted to desk carries convertedTo, and every write to it is 409 converted.

Move an item through the workflow

The simplest way is transitionForgeItem: send either a statusKey or a category:

curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/APP/items/12/transition' \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
  -d '{"category": "done"}'

With category forge picks the first status of that category the workflow allows from the current status, so the same call works in every project; an item already in the category stays where it is (200, nothing recorded). The call needs no version. A move the workflow does not allow is 409 transition_not_allowed – read the workflow's transitions and go through an intermediate status. Entering done or cancelled sets closedAt and resolution.

Other changes – title, description, type, estimate, dates, custom fields, milestone, iteration, also the status by statusId – go through patchForgeItem with the version you read (409 version_conflict when it changed: read again and retry). Assignees and labels have their own routes (setForgeItemAssignees, assignForgeItem, setForgeItemLabels, addForgeItemLabel).

A project can run automations on every change; a blocking one that fails refuses the write with 422 automation_blocked (details.reason, details.message) – the change was not stored.

Events

For webhooks and flows, forge announces forge.item.created, forge.item.updated, forge.item.status_changed, forge.item.closed, forge.item.reopened, forge.item.assigned, forge.item.commented and more (the flows catalogue lists them). They carry ids, the reference and states: read the item through the API for its content.

View as Markdown