# 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](/reference/forge). Handing items to desk and back is the [Handoff guide](/guides/handoffs).

| Step | Operations | Permission |
|---|---|---|
| Projects and configuration | [`listForgeProjects`](/reference/forge/listForgeProjects), [`getForgeProjectConfig`](/reference/forge/getForgeProjectConfig) | `tenant:forge:read` |
| Create | [`createForgeItem`](/reference/forge/createForgeItem) | `tenant:forge:write`, or a project member (reporters may create) |
| Find | [`searchForgeItems`](/reference/forge/searchForgeItems), [`listForgeProjectItems`](/reference/forge/listForgeProjectItems), [`getForgeItem`](/reference/forge/getForgeItem) | `tenant:forge:read` |
| Change and move | [`patchForgeItem`](/reference/forge/patchForgeItem), [`transitionForgeItem`](/reference/forge/transitionForgeItem), [`setForgeItemAssignees`](/reference/forge/setForgeItemAssignees), [`setForgeItemLabels`](/reference/forge/setForgeItemLabels) | `tenant:forge:write` (developer or higher) |
| Discuss | [`listForgeComments`](/reference/forge/listForgeComments), [`createForgeComment`](/reference/forge/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`](/reference/forge/getForgeProjectConfig):

```bash
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`](/reference/forge/listForgeStatuses), [`listForgeWorkflows`](/reference/forge/listForgeWorkflows)
and [`listForgeItemTypes`](/reference/forge/listForgeItemTypes).

## Create an item

```bash
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`](/reference/forge/searchForgeItems) (`GET /items`) searches every project the caller sees,
[`listForgeProjectItems`](/reference/forge/listForgeProjectItems) one project (in rank order by default). Filters
combine, lists are comma separated:

```bash
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](/guides/pagination)). Converted items are left out
unless `includeConverted=true`.

[`getForgeItem`](/reference/forge/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`](/reference/forge/transitionForgeItem): send **either** a `statusKey`
**or** a `category`:

```bash
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`](/reference/forge/patchForgeItem) with the `version` you read (**409**
`version_conflict` when it changed: read again and retry). Assignees and labels have their own routes
([`setForgeItemAssignees`](/reference/forge/setForgeItemAssignees), [`assignForgeItem`](/reference/forge/assignForgeItem),
[`setForgeItemLabels`](/reference/forge/setForgeItemLabels), [`addForgeItemLabel`](/reference/forge/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](/guides/webhooks) and [flows](/guides/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.
