diff --git a/doc/api/issues.md b/doc/api/issues.md index 5702cdcf3c17a62cd5cd924760de99d28291cf99..54c099d4bf8a41c896209eedcdcfd0bbffede68d 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -29,17 +29,15 @@ GET /issues?iids[]=42&iids[]=43 GET /issues?search=issue+title+or+description ``` -|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------| | Attribute | Type | Required | Description | -|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------| +|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------| | `state` | string | no | Return all issues or just those that are `opened` or `closed` | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | | `milestone` | string | no | The milestone title | | `iids` | Array[integer] | no | Return only the issues having the given `iid` | | `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | -| `search` | string | no | Search issues against their `title` and `description` | -|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------| +| `search` | string | no | Search issues against their `title` and `description` | ```bash curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/issues @@ -111,9 +109,8 @@ GET /groups/:id/issues?iids[]=42&iids[]=43 GET /groups/:id/issues?search=issue+title+or+description ``` -|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------| | Attribute | Type | Required | Description | -|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------| +|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------| | `id` | integer | yes | The ID of a group | | `state` | string | no | Return all issues or just those that are `opened` or `closed` | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | @@ -122,7 +119,6 @@ GET /groups/:id/issues?search=issue+title+or+description | `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search group issues against their `title` and `description` | -|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------| ```bash @@ -195,9 +191,8 @@ GET /projects/:id/issues?iids[]=42&iids[]=43 GET /projects/:id/issues?search=issue+title+or+description ``` -|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------| | Attribute | Type | Required | Description | -|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------| +|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------| | `id` | integer | yes | The ID of a project | | `iids` | Array[integer] | no | Return only the milestone having the given `iid` | | `state` | string | no | Return all issues or just those that are `opened` or `closed` | @@ -206,7 +201,6 @@ GET /projects/:id/issues?search=issue+title+or+description | `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search project issues against their `title` and `description` | -|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------| ```bash @@ -270,12 +264,10 @@ Get a single project issue. GET /projects/:id/issues/:issue_iid ``` -|-------------+---------+----------+--------------------------------------| | Attribute | Type | Required | Description | -|-------------+---------+----------+--------------------------------------| +|-------------|---------|----------|--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | -|-------------+---------+----------+--------------------------------------| ```bash curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/41 @@ -337,23 +329,19 @@ Creates a new project issue. POST /projects/:id/issues ``` -|-------------------------------------------+---------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------| -| Attribute | Type | Required | Description | -|-------------------------------------------+---------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------| -| `id` | integer | yes | The ID of a project | -| `title` | string | yes | The title of an issue | -| `description` | string | no | The description of an issue | -| `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | -| `assignee_id` | integer | no | The ID of a user to assign issue | -| `milestone_id` | integer | no | The ID of a milestone to assign issue | -| `labels` | string | no | Comma-separated label names for an issue | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) | -| `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` | -| `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. | -| - | - | - | When passing a description or title, these values will take precedence over the default values. | -| `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion | -| - | - | - | as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | -|-------------------------------------------+---------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------| +| Attribute | Type | Required | Description | +|-------------------------------------------|---------|----------|--------------| +| `id` | integer | yes | The ID of a project | +| `title` | string | yes | The title of an issue | +| `description` | string | no | The description of an issue | +| `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | +| `assignee_id` | integer | no | The ID of a user to assign issue | +| `milestone_id` | integer | no | The ID of a milestone to assign issue | +| `labels` | string | no | Comma-separated label names for an issue | +| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) | +| `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` | +| `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. When passing a description or title, these values will take precedence over the default values.| +| `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug @@ -401,9 +389,8 @@ closed. PUT /projects/:id/issues/:issue_iid ``` -|----------------+---------+----------+------------------------------------------------------------------------------------------------------------| | Attribute | Type | Required | Description | -|----------------+---------+----------+------------------------------------------------------------------------------------------------------------| +|----------------|---------|----------|------------------------------------------------------------------------------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `title` | string | no | The title of an issue | @@ -415,7 +402,6 @@ PUT /projects/:id/issues/:issue_iid | `state_event` | string | no | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it | | `updated_at` | string | no | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) | | `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` | -|----------------+---------+----------+------------------------------------------------------------------------------------------------------------| ```bash curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close @@ -462,12 +448,10 @@ Only for admins and project owners. Soft deletes the issue in question. DELETE /projects/:id/issues/:issue_iid ``` -|-------------+---------+----------+--------------------------------------| | Attribute | Type | Required | Description | -|-------------+---------+----------+--------------------------------------| +|-------------|---------|----------|--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | -|-------------+---------+----------+--------------------------------------| ```bash curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85 @@ -486,13 +470,11 @@ project, it will then be assigned to the issue that is being moved. POST /projects/:id/issues/:issue_iid/move ``` -|-----------------+---------+----------+--------------------------------------| | Attribute | Type | Required | Description | -|-----------------+---------+----------+--------------------------------------| +|-----------------|---------|----------|--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `to_project_id` | integer | yes | The ID of the new project | -|-----------------+---------+----------+--------------------------------------| ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85/move @@ -544,12 +526,10 @@ is returned. POST /projects/:id/issues/:issue_iid/subscribe ``` -|-------------+---------+----------+--------------------------------------| | Attribute | Type | Required | Description | -|-------------+---------+----------+--------------------------------------| +|-------------|---------|----------|--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | -|-------------+---------+----------+--------------------------------------| ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/subscribe @@ -601,12 +581,10 @@ status code `304` is returned. POST /projects/:id/issues/:issue_iid/unsubscribe ``` -|-------------+---------+----------+--------------------------------------| | Attribute | Type | Required | Description | -|-------------+---------+----------+--------------------------------------| +|-------------|---------|----------|--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | -|-------------+---------+----------+--------------------------------------| ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/unsubscribe @@ -622,12 +600,10 @@ returned. POST /projects/:id/issues/:issue_iid/todo ``` -|-------------+---------+----------+--------------------------------------| | Attribute | Type | Required | Description | -|-------------+---------+----------+--------------------------------------| +|-------------|---------|----------|--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | -|-------------+---------+----------+--------------------------------------| ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/todo @@ -715,13 +691,11 @@ Sets an estimated time of work for this issue. POST /projects/:id/issues/:issue_iid/time_estimate ``` -|-------------+---------+----------+------------------------------------------| | Attribute | Type | Required | Description | -|-------------+---------+----------+------------------------------------------| +|-------------|---------|----------|------------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `duration` | string | yes | The duration in human format. e.g: 3h30m | -|-------------+---------+----------+------------------------------------------| ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/time_estimate?duration=3h30m @@ -746,12 +720,10 @@ Resets the estimated time for this issue to 0 seconds. POST /projects/:id/issues/:issue_iid/reset_time_estimate ``` -|-------------+---------+----------+--------------------------------------| | Attribute | Type | Required | Description | -|-------------+---------+----------+--------------------------------------| +|-------------|---------|----------|--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | -|-------------+---------+----------+--------------------------------------| ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/reset_time_estimate @@ -776,13 +748,11 @@ Adds spent time for this issue POST /projects/:id/issues/:issue_iid/add_spent_time ``` -|-------------+---------+----------+------------------------------------------| | Attribute | Type | Required | Description | -|-------------+---------+----------+------------------------------------------| +|-------------|---------|----------|------------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `duration` | string | yes | The duration in human format. e.g: 3h30m | -|-------------+---------+----------+------------------------------------------| ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/add_spent_time?duration=1h @@ -807,12 +777,10 @@ Resets the total spent time for this issue to 0 seconds. POST /projects/:id/issues/:issue_iid/reset_spent_time ``` -|-------------+---------+----------+--------------------------------------| | Attribute | Type | Required | Description | -|-------------+---------+----------+--------------------------------------| +|-------------|---------|----------|--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | -|-------------+---------+----------+--------------------------------------| ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/reset_spent_time @@ -835,12 +803,10 @@ Example response: GET /projects/:id/issues/:issue_iid/time_stats ``` -|-------------+---------+----------+--------------------------------------| | Attribute | Type | Required | Description | -|-------------+---------+----------+--------------------------------------| +|-------------|---------|----------|--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | -|-------------+---------+----------+--------------------------------------| ```bash curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/time_stats