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.