---
title: "POST /api/v1/projects/{project_id}/issues/{ref}/links"
method: POST
path: "/api/v1/projects/{project_id}/issues/{ref}/links"
---

# POST /api/v1/projects/{project_id}/issues/{ref}/links

`POST /api/v1/projects/{project_id}/issues/{ref}/links`

## Path parameters

- `project_id` integer, required
- `ref` string, required

## Request body

- CreateLinkRequestBody
  - `actor` string
  - `replace` boolean
  - `to_ref` string, required
  - `type` 'parent' | 'blocks' | 'related', required

## Response `200`

OK

- CreateLinkResponseBody
  - `changed` boolean, required
  - `event` Event, required
    - `actor` string, required
    - `content_hash` string, required
    - `created_at` string, date-time, required
    - `hlc_counter` integer, required
    - `hlc_physical_ms` integer, required
    - `id` integer, required
    - `issue_id` integer
    - `issue_short_id` string
    - `issue_uid` string
    - `origin_instance_uid` string, required
    - `payload` string, required
    - `project_id` integer, required
    - `project_name` string, required
    - `project_uid` string, required
    - `related_issue_id` integer
    - `related_issue_short_id` string
    - `related_issue_uid` string
    - `type` string, required
    - `uid` string, required
  - `issue` Issue, required
    - `author` string, required
    - `body` string, required
    - `closed_at` string, date-time
    - `closed_reason` string
    - `created_at` string, date-time, required
    - `deleted_at` string, date-time
    - `id` integer, required
    - `metadata` object, required
    - `occurrence_key` string
    - `owner` string
    - `priority` integer
    - `project_id` integer, required
    - `project_uid` string
    - `recurrence_id` integer
    - `revision` integer, required
    - `short_id` string, required
    - `status` string, required
    - `title` string, required
    - `uid` string, required
    - `updated_at` string, date-time, required
  - `link` LinkOut, required
    - `author` string, required
    - `created_at` string, date-time, required
    - `from` LinkPeer, required
      - `project` string, required
      - `qualified_id` string, required
      - `short_id` string, required
      - `status` string, required
      - `uid` string, required
    - `id` integer, required
    - `to` LinkPeer, required
      - `project` string, required
      - `qualified_id` string, required
      - `short_id` string, required
      - `status` string, required
      - `uid` string, required
    - `type` string, required

## Other responses

- `default` — Error

## Changes

- **2026-08-05** `1a5a27920493` — 1 info
  - the request property `actor` became optional
- **2026-07-09** `987b717e44b2` — 2 info
  - added the required property `link/from/status` to the response with the `200` status
  - added the required property `link/to/status` to the response with the `200` status
- **2026-06-16** `88357e9777d5` — 1 breaking, 4 info
  - removed the required property `link/project_id` from the response with the `200` status
  - added the required property `link/from/project` to the response with the `200` status
  - added the required property `link/from/qualified_id` to the response with the `200` status
  - added the required property `link/to/project` to the response with the `200` status
  - …1 more
- **2026-06-05** `783ece1efda1` — 6 breaking, 1 info
  - removed the required property `link/from/project` from the response with the `200` status
  - removed the required property `link/from/qualified_id` from the response with the `200` status
  - removed the required property `link/from/status` from the response with the `200` status
  - removed the required property `link/to/project` from the response with the `200` status
  - …3 more

[Change history](https://skmtc.dev/kenn-io/apis/kata/changes/api/v1/projects/:project_id/issues/:ref/links/post.md)

---

[API](https://skmtc.dev/kenn-io/apis/kata.md) · [All operations](https://skmtc.dev/kenn-io/apis/kata/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/kenn-io/kata/revisions/2d4207e1e028/schema)