ConnectCloud Developers

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 of blocks, 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 created
  • createdBy (string, required): E-mail of who created the link
  • direction (string, required): outgoing: this item is the source; incoming: the other item is (one of outgoing, incoming)
  • id (string (uuid), required): Link id
  • item (object, required): The other item
    • id (string (uuid), required): Item id
    • projectKey (string, required): Project key
    • ref (string, required): Item reference, e.g. WEB-3
    • statusCategory (string, required): Status category
    • statusKey (string, required): Status key
    • statusName (string, required): Status name
    • title (string, required): Title
    • typeKey (string, required): Item type key
  • kind (string, required): Link kind (one of blocks, 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"}'

View as Markdown · Interactive reference · OpenAPI