Skip to content
forgit api docs

Create an issue

POST
/api/v4/projects/{id}/issues

Creates an issue for a specified project.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
One of:
string

The ID or URL-encoded path of the project

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
title
required

The title of an issue

string
nullable
created_at

Date time when the issue was created. Available only for admins and project owners.

string format: date-time
nullable
merge_request_to_resolve_discussions_of

The IID of a merge request for which to resolve discussions

integer
nullable
discussion_to_resolve

The ID of a discussion to resolve, also pass merge_request_to_resolve_discussions_of

string
nullable
iid

The internal ID of a project issue. Available only for admins and project owners.

integer
nullable
description

The description of an issue

string
nullable
assignee_ids

The array of user IDs to assign issue

Array<integer>
nullable
assignee_id

[Deprecated] The ID of a user to assign issue

integer
nullable
milestone_id

The ID of a milestone to assign issue

integer
nullable
milestone

The title of a project or ancestor-group milestone to assign the issue to. Mutually exclusive with milestone_id.

string
nullable <= 255 characters
labels

Comma-separated list of label names

Array<string>
nullable
add_labels

Comma-separated list of label names

Array<string>
nullable
remove_labels

Comma-separated list of label names

Array<string>
nullable
due_date

Date string in the format YEAR-MONTH-DAY

string
nullable
start_date

Date string in the format YEAR-MONTH-DAY

string
nullable
confidential

Boolean parameter if the issue should be confidential

boolean
nullable
discussion_locked

Boolean parameter indicating if the issue’s discussion is locked

boolean
nullable
issue_type

The type of the issue. Accepts: issue, incident, test_case, requirement, task, ticket

string
nullable
Allowed values: issue incident test_case requirement task ticket
severity

The severity of the issue. Only applies to incidents. Accepts: unknown, low, medium, high, critical

string
nullable
Allowed values: unknown low medium high critical
weight

The weight of the issue

integer
nullable
epic_id

The ID of an epic to associate the issue with

integer
nullable
epic_iid

The IID of an epic to associate the issue with (deprecated)

integer
nullable

Responses

Section titled “Responses”

201

Section titled “201”

Created

Media typeapplication/json
object
id
integer format: int64
iid
integer
project_id
integer format: int64
title
string
description
string
state
string
created_at
string format: date-time
updated_at
string format: date-time
closed_at
string format: date-time
closed_by
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
labels
Array<string>
milestone
object
id
integer format: int64
iid
integer format: int64
project_id
integer format: int64
group_id
string
title
string
description
string
state
string
created_at
string
updated_at
string
due_date
string
start_date
string
expired
boolean
web_url
string
assignees
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
author
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
type

One of [“ISSUE”, “INCIDENT”, “TEST_CASE”, “REQUIREMENT”, “TASK”, “TICKET”]

string
assignee
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
user_notes_count
integer
merge_requests_count
integer
upvotes
integer
downvotes
integer
start_date
string format: date
due_date
string format: date
confidential
boolean
discussion_locked
boolean
issue_type
string
web_url
string
time_stats
object
time_estimate
integer
total_time_spent
integer
human_time_estimate
string
human_total_time_spent
string
task_completion_status
object
count
integer
completed_count
integer
weight
integer
blocking_issues_count
integer
has_tasks
boolean
task_status
string
_links
object
self
string
notes
string
award_emoji
string
project
string
closed_as_duplicate_of
string
references
object
short
string
relative
string
full
string
severity

One of [“UNKNOWN”, “LOW”, “MEDIUM”, “HIGH”, “CRITICAL”]

string
subscribed
boolean
moved_to_id
integer format: int64
imported
boolean
imported_from
string
service_desk_reply_to
string
epic_iid
string
epic
object
id
string
iid
string
title
string
url
string
group_id
string
human_readable_end_date
string
human_readable_timestamp
string
iteration
object
id
integer format: int64
iid
integer
sequence
integer
group_id
integer format: int64
title
string
description
string
state
integer
created_at
string format: date-time
updated_at
string format: date-time
start_date
string format: date
due_date
string format: date
web_url
string
health_status
string
Example
{
  "id": 84,
  "iid": 14,
  "project_id": 4,
  "title": "Impedit et ut et dolores vero provident ullam est",
  "description": "Repellendus impedit et vel velit dignissimos.",
  "state": "closed",
  "created_at": "2022-08-17T12:46:35.053Z",
  "updated_at": "2022-11-14T17:22:01.470Z",
  "closed_at": "2022-11-15T08:30:55.232Z",
  "closed_by": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "labels": [
    "bug"
  ],
  "assignees": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "author": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "type": "ISSUE",
  "assignee": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "start_date": "2022-11-18",
  "due_date": "2022-11-20",
  "issue_type": "issue",
  "web_url": "http://example.com/example/example/issues/14",
  "time_stats": {
    "time_estimate": 12600,
    "total_time_spent": 3600,
    "human_time_estimate": "3h 30m",
    "human_total_time_spent": "1h"
  },
  "task_completion_status": {
    "count": 5,
    "completed_count": 3
  },
  "weight": 5,
  "blocking_issues_count": 2,
  "has_tasks": true,
  "task_status": "2 of 4 tasks completed",
  "_links": {
    "self": "http://example.com/api/v4/projects/1/issues/2",
    "notes": "http://example.com/api/v4/projects/1/issues/2/notes",
    "award_emoji": "http://example.com/api/v4/projects/1/issues/2/award_emoji",
    "project": "http://example.com/api/v4/projects/1",
    "closed_as_duplicate_of": "http://example.com/api/v4/projects/1/issues/75"
  },
  "references": {
    "short": "&6",
    "relative": "&6",
    "full": "test&6"
  },
  "subscribed": false,
  "moved_to_id": 1,
  "imported": false,
  "imported_from": "github",
  "service_desk_reply_to": "user@example.com",
  "iteration": {
    "id": 1,
    "iid": 1,
    "sequence": 1,
    "group_id": 1,
    "title": "Iteration I",
    "description": "Iteration description",
    "state": 1,
    "created_at": "2022-01-31T15:10:45.080Z",
    "updated_at": "2022-01-31T15:10:45.080Z",
    "start_date": "2022-01-01",
    "due_date": "2022-01-31",
    "web_url": "https://gitlab.example.com/groups/gitlab-org/-/iterations/1"
  }
}

400

Section titled “400”

Bad Request

404

Section titled “404”

Not Found