# WorkItemLink

A directed link between two work items (`blocks`, `duplicates`, `relates_to` and four more), the rows the linked items section in plnnrly is built from. A link is read relative to the work item you asked about: one row is "blocks ACM-9" from one end and "is blocked by ACM-4" from the other, which is what `direction` and `relationship` carry. There is no PATCH: the only mutable property of a link is which two items it joins, so re-linking is a DELETE plus a POST. Deleting either work item deletes the link with it.

## Used by
- GET /api/v2/work-item-links/{work_item_link}: Read a work item link (WorkItemLink)
- GET /api/v2/work-items/{work_item}/links: List a work item's links (WorkItemLinkList)
- POST /api/v2/work-items/{work_item}/links: Link a work item to another (WorkItemLink)

## WorkItemLink fields
- id (integer, required): Unique identifier.
- source_work_item_id (integer, required): Work item the link points away from. On a link created through `POST work-items/{work_item}/links` this is always the work item named in the path.
- target_work_item_id (integer, required): Work item the link points at. Always in the same project as the source.
- link_type (string, required): The relationship, stored from the source item's point of view: `blocks`, `clones`, `duplicates`, `merged_into`, `causes`, `relates_to` or `split_to`. Only `relates_to` is symmetric.
- created_by (integer or null, required, server-assigned): User who created the link, or `null` where that account has since been deleted. Resolve it with `GET /api/v2/users/{user}`; it is not includable.
- created_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): Creation timestamp.
- updated_at (timestamp (YYYY-MM-DDThh:mm:ssZ), required): Last-write timestamp; use for incremental sync.
- direction (string, required): Which way this link points relative to the work item you asked about: `forward` when that item is the source, `inverse` when it is the target. On the flat `GET work-item-links/{work_item_link}` there is no work item in the path, so the link is read on its own terms and this is always `forward`.
- relationship (string, required): The relationship in words, from the point of view of the work item you asked about: `blocks` from the source end, `is blocked by` from the target end. Always in English: the API pins the locale.
- source_work_item (Ref or WorkItemSummary, required): Work item the link points away from.
- target_work_item (Ref or WorkItemSummary, required): Work item the link points at.
- links (WorkItemLinkLinks, required)
  - self (url, required): The canonical URI of this record.

## Variants

### WorkItemLinkList

What a collection returns, and what `?view=summary` returns on a single record.

12 fields.
Identical to the detail object above.

### WorkItemLinkSummary

The embedded form: what you get when another resource carries this one and you did not `include` it.

3 fields.
Omits: link_type, created_by, created_at, updated_at, direction, relationship, source_work_item, target_work_item, links

### WorkItemLinkLinks

The `links` object on this resource.

Keys: self

## Example
```json
{
  "id": 1,
  "source_work_item_id": 1,
  "target_work_item_id": 1,
  "link_type": "blocks",
  "created_by": 1,
  "created_at": "2026-03-04T09:15:00Z",
  "updated_at": "2026-03-04T09:15:00Z",
  "direction": "…",
  "relationship": "…",
  "source_work_item": {
    "id": 1
  },
  "target_work_item": {
    "id": 1
  },
  "links": {
    "self": "https://<your-url>/api/v2/work-items/1"
  }
}
```