Link an item to another item (tenant:forge:write and, as a member, at least developer)
POST /api/forge/v1/projects/{key}/items/{number}/links
Module: Forge · operationId: createForgeItemLink · Tag: Items · Auth: access token (Authorization: Bearer <accessToken>)
Same permission as changing an item; the target may be in any project of the tenant the caller sees. No self links; a blocks link that closes a cycle is 409 link_cycle; an existing link 409 link_exists. duplicates closes the item with resolution duplicate. Writes forge.item.linked (and closed).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
key |
path | string | yes | Project key (e.g. APP) |
number |
path | integer | yes | Item number in the project (12 of APP-12) |
Request body
application/json (required)
kind(string, required): Seen from this item: it blocks / relates to / duplicates the target (one ofblocks,relates,duplicates)target(string, required): Reference of the other item, e.g. WEB-3
Example:
{
"kind": "blocks",
"target": "APP-7"
}
Responses
- 201 Linked (
application/json) - 400 Error (
application/json) - 403 Error (
application/json) - 404 Error (
application/json) - 409 Error (
application/json)
Fields of the 201 answer:
createdAt(string (date-time), required): When the link was createdcreatedBy(string, required): E-mail of who created the linkdirection(string, required):outgoing: this item is the source;incoming: the other item is (one ofoutgoing,incoming)id(string (uuid), required): Link iditem(object, required): The other itemid(string (uuid), required): Item idprojectKey(string, required): Project keyref(string, required): Item reference, e.g. WEB-3statusCategory(string, required): Status categorystatusKey(string, required): Status keystatusName(string, required): Status nametitle(string, required): TitletypeKey(string, required): Item type key
kind(string, required): Link kind (one ofblocks,relates,duplicates)
Example 201 answer:
{
"createdAt": "2026-10-28T10:40:00Z",
"createdBy": "emma.maier@muster-it.example",
"direction": "outgoing",
"id": "6c7d8e9f-0a1b-4c2d-9e3f-5a6b7c8d9e01",
"item": {
"id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c07",
"projectKey": "APP",
"ref": "APP-7",
"statusCategory": "todo",
"statusKey": "offen",
"statusName": "Offen",
"title": "Cursor-basierte Seitenwechsel in der Ticketliste",
"typeKey": "aufgabe"
},
"kind": "blocks"
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/items/1/links' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"kind":"blocks","target":"APP-7"}'