---
title: "POST /item/{itemId}/dependency"
method: POST
path: "/item/{itemId}/dependency"
tags: ["Work Items and OKRs"]
---

# POST /item/{itemId}/dependency

`POST /item/{itemId}/dependency`

Create, retype, or remove a dependency between two items — work items (epics,
features, stories, bugs, tasks, requirements) and/or portfolio initiatives.
Products, OKRs, key results and super-initiatives cannot have dependencies and
are rejected (422) on create/retype; `remove` is allowed regardless of type.
Upsert — creates the relation or changes its type; `remove: true` deletes it
(idempotent — removing an absent dependency returns 200 with removed=false).
Directional from the path item: "item <type> relatedItem". Relation types:
`blocks`, `blocked by`, `related`. Read dependencies via get_item `fields=all`.

## Path parameters

- `itemId` string, required

## Request body

- DependencyWriteRequest
  - `relatedItemId` string, required — The other item in the relation: numeric ID or shortId `KEY-N`.
  - `type` string — Relation type, directional from the path item: "item <type> relatedItem". One of `blocks`, `blocked by`, `related`. Required unless remove=true. Typed `string` (not a union) so an invalid value gets one clear controller message ("type must be one of: …") instead of a raw tsoa union error.
  - `remove` boolean — true = delete the dependency between the two items (type is ignored).

## Response `200`

The resulting dependency

- DependencyWrite
  - `itemId` string, required
  - `relatedItemId` string, required
  - `type` 'blocks' | 'blocked by' | 'related', nullable, required
  - `removed` boolean, required

## Other responses

- `401` — No access
- `404` — Item not found
- `422` — Invalid input

---

[API](https://skmtc.net/craft/apis/craft-io-public-api.md) · [All operations](https://skmtc.net/craft/apis/craft-io-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/craft/craft-io-public-api/versions/2d001661c781/schema)