---
title: "Create an issue link"
method: POST
path: "/api/v4/projects/{id}/issues/{issue_iid}/links"
tags: ["issues"]
---

# Create an issue link

`POST /api/v4/projects/{id}/issues/{issue_iid}/links`

## Request

- Base URL: `https://gitlab.com`
- URL: `https://gitlab.com/api/v4/projects/{id}/issues/{issue_iid}/links`
- Auth: none declared

Creates a two-way relationship between two issues. The user must be allowed to update both issues to succeed.

## Path parameters

- `id` string, required
- `issue_iid` integer, required

## Request body

- PostApiV4ProjectsIdIssuesIssueIidLinks: Create an issue link
  - `target_project_id` string, required: The ID or URL-encoded path of a target project
  - `target_issue_iid` string, required: The internal ID of a target project’s issue
  - `link_type` 'relates_to' | 'blocks' | 'is_blocked_by': The type of the relation (“relates_to”, “blocks”, “is_blocked_by”),defaults to “relates_to”)

## Response `201`

Create an issue link

- APIEntitiesIssueLink: API_Entities_IssueLink model
  - `id` integer, required
  - `source_issue` APIEntitiesIssueBasic, required
    - `id` integer, required
    - `iid` integer, required
    - `project_id` integer, required
    - `title` string, required
    - `description` string, required
    - `state` string, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `closed_at` string, date-time, required
    - `closed_by` APIEntitiesUserBasic, required: API_Entities_UserBasic model
      - `id` integer, required
      - `username` string, required
      - `public_email` string, required
      - `name` string, required
      - `state` string, required
      - `locked` boolean, required
      - `avatar_url` string, required
      - `avatar_path` string
      - `custom_attributes` APIEntitiesCustomAttribute[]
        - `key` string, required
        - `value` string, required
      - `web_url` string, required
    - `labels` string[], required
    - `milestone` APIEntitiesMilestone, required
      - `id` integer, required
      - `iid` integer, required
      - `project_id` integer
      - `group_id` string
      - `title` string, required
      - `description` string, required
      - `state` string, required
      - `created_at` string, required
      - `updated_at` string, required
      - `due_date` string, required
      - `start_date` string, required
      - `expired` boolean, required
      - `web_url` string, required
    - `assignees` APIEntitiesUserBasic, required: API_Entities_UserBasic model
      - `id` integer, required
      - `username` string, required
      - `public_email` string, required
      - `name` string, required
      - `state` string, required
      - `locked` boolean, required
      - `avatar_url` string, required
      - `avatar_path` string
      - `custom_attributes` APIEntitiesCustomAttribute[]
        - `key` string, required
        - `value` string, required
      - `web_url` string, required
    - `author` APIEntitiesUserBasic, required: API_Entities_UserBasic model
      - `id` integer, required
      - `username` string, required
      - `public_email` string, required
      - `name` string, required
      - `state` string, required
      - `locked` boolean, required
      - `avatar_url` string, required
      - `avatar_path` string
      - `custom_attributes` APIEntitiesCustomAttribute[]
        - `key` string, required
        - `value` string, required
      - `web_url` string, required
    - `type` string, required: One of ["ISSUE", "INCIDENT", "TEST_CASE", "REQUIREMENT", "TASK", "TICKET"]
    - `assignee` APIEntitiesUserBasic, required: API_Entities_UserBasic model
      - `id` integer, required
      - `username` string, required
      - `public_email` string, required
      - `name` string, required
      - `state` string, required
      - `locked` boolean, required
      - `avatar_url` string, required
      - `avatar_path` string
      - `custom_attributes` APIEntitiesCustomAttribute[]
        - `key` string, required
        - `value` string, required
      - `web_url` string, required
    - `user_notes_count` integer, required
    - `merge_requests_count` integer, required
    - `upvotes` integer, required
    - `downvotes` integer, required
    - `start_date` string, date, required
    - `due_date` string, date, required
    - `confidential` boolean, required
    - `discussion_locked` boolean, required
    - `issue_type` string, required
    - `web_url` string, required
    - `time_stats` APIEntitiesIssuableTimeStats, required: API_Entities_IssuableTimeStats model
      - `time_estimate` integer, required
      - `total_time_spent` integer, required
      - `human_time_estimate` string, required
      - `human_total_time_spent` string, required
    - `task_completion_status` APIEntitiesTaskCompletionStatus, required
      - `count` integer, required
      - `completed_count` integer, required
    - `weight` integer
    - `blocking_issues_count` integer, required
  - `target_issue` APIEntitiesIssueBasic, required
    - `id` integer, required
    - `iid` integer, required
    - `project_id` integer, required
    - `title` string, required
    - `description` string, required
    - `state` string, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `closed_at` string, date-time, required
    - `closed_by` APIEntitiesUserBasic, required: API_Entities_UserBasic model
      - `id` integer, required
      - `username` string, required
      - `public_email` string, required
      - `name` string, required
      - `state` string, required
      - `locked` boolean, required
      - `avatar_url` string, required
      - `avatar_path` string
      - `custom_attributes` APIEntitiesCustomAttribute[]
        - `key` string, required
        - `value` string, required
      - `web_url` string, required
    - `labels` string[], required
    - `milestone` APIEntitiesMilestone, required
      - `id` integer, required
      - `iid` integer, required
      - `project_id` integer
      - `group_id` string
      - `title` string, required
      - `description` string, required
      - `state` string, required
      - `created_at` string, required
      - `updated_at` string, required
      - `due_date` string, required
      - `start_date` string, required
      - `expired` boolean, required
      - `web_url` string, required
    - `assignees` APIEntitiesUserBasic, required: API_Entities_UserBasic model
      - `id` integer, required
      - `username` string, required
      - `public_email` string, required
      - `name` string, required
      - `state` string, required
      - `locked` boolean, required
      - `avatar_url` string, required
      - `avatar_path` string
      - `custom_attributes` APIEntitiesCustomAttribute[]
        - `key` string, required
        - `value` string, required
      - `web_url` string, required
    - `author` APIEntitiesUserBasic, required: API_Entities_UserBasic model
      - `id` integer, required
      - `username` string, required
      - `public_email` string, required
      - `name` string, required
      - `state` string, required
      - `locked` boolean, required
      - `avatar_url` string, required
      - `avatar_path` string
      - `custom_attributes` APIEntitiesCustomAttribute[]
        - `key` string, required
        - `value` string, required
      - `web_url` string, required
    - `type` string, required: One of ["ISSUE", "INCIDENT", "TEST_CASE", "REQUIREMENT", "TASK", "TICKET"]
    - `assignee` APIEntitiesUserBasic, required: API_Entities_UserBasic model
      - `id` integer, required
      - `username` string, required
      - `public_email` string, required
      - `name` string, required
      - `state` string, required
      - `locked` boolean, required
      - `avatar_url` string, required
      - `avatar_path` string
      - `custom_attributes` APIEntitiesCustomAttribute[]
        - `key` string, required
        - `value` string, required
      - `web_url` string, required
    - `user_notes_count` integer, required
    - `merge_requests_count` integer, required
    - `upvotes` integer, required
    - `downvotes` integer, required
    - `start_date` string, date, required
    - `due_date` string, date, required
    - `confidential` boolean, required
    - `discussion_locked` boolean, required
    - `issue_type` string, required
    - `web_url` string, required
    - `time_stats` APIEntitiesIssuableTimeStats, required: API_Entities_IssuableTimeStats model
      - `time_estimate` integer, required
      - `total_time_spent` integer, required
      - `human_time_estimate` string, required
      - `human_total_time_spent` string, required
    - `task_completion_status` APIEntitiesTaskCompletionStatus, required
      - `count` integer, required
      - `completed_count` integer, required
    - `weight` integer
    - `blocking_issues_count` integer, required
  - `link_type` string, required

## Other responses

- `400`: Bad Request
- `401`: Unauthorized

---

[API](https://skmtc.dev/gitlab/apis/gitlab-api.md) - [All operations](https://skmtc.dev/gitlab/apis/gitlab-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gitlab/apis/gitlab-api/revisions/b234947ef3f2?raw)