2020-05-26 23:08:26 -04:00
---
stage: Plan
group: Project Management
2020-11-26 01:09:20 -05:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-05-26 23:08:26 -04:00
---
2020-10-02 14:08:56 -04:00
# To dos API
2016-06-16 05:12:42 -04:00
2020-03-31 23:07:57 -04:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/3188) in GitLab 8.10.
2016-06-16 05:12:42 -04:00
2020-10-02 14:08:56 -04:00
## Get a list of to dos
2016-06-16 05:12:42 -04:00
2021-02-08 19:09:37 -05:00
Returns a list of [to-do items ](../user/todos.md ). When no filter is applied, it
returns all pending to-do items for the current user. Different filters allow the
user to refine the request.
2016-06-16 05:12:42 -04:00
2020-02-28 22:07:51 -05:00
```plaintext
2016-06-16 05:12:42 -04:00
GET /todos
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2020-09-08 14:08:48 -04:00
| `action` | string | no | The action to be filtered. Can be `assigned` , `mentioned` , `build_failed` , `marked` , `approval_required` , `unmergeable` , `directly_addressed` or `merge_train_removed` . |
2016-06-16 05:12:42 -04:00
| `author_id` | integer | no | The ID of an author |
| `project_id` | integer | no | The ID of a project |
2018-07-16 09:35:19 -04:00
| `group_id` | integer | no | The ID of a group |
2020-10-02 14:08:56 -04:00
| `state` | string | no | The state of the to do. Can be either `pending` or `done` |
2020-10-28 14:08:52 -04:00
| `type` | string | no | The type of to-do item. Can be either `Issue` , `MergeRequest` , `DesignManagement::Design` or `AlertManagement::Alert` |
2016-06-16 05:12:42 -04:00
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/todos"
2016-06-16 05:12:42 -04:00
```
Example Response:
```json
[
{
2016-06-22 13:15:09 -04:00
"id": 102,
2016-06-16 05:12:42 -04:00
"project": {
2016-06-22 13:15:09 -04:00
"id": 2,
"name": "Gitlab Ce",
"name_with_namespace": "Gitlab Org / Gitlab Ce",
2019-09-18 14:06:14 -04:00
"path": "gitlab-foss",
"path_with_namespace": "gitlab-org/gitlab-foss"
2016-06-16 05:12:42 -04:00
},
"author": {
2016-06-22 13:15:09 -04:00
"name": "Administrator",
"username": "root",
"id": 1,
2016-06-16 05:12:42 -04:00
"state": "active",
2016-06-22 13:15:09 -04:00
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
2016-10-13 07:24:09 -04:00
"web_url": "https://gitlab.example.com/root"
2016-06-16 05:12:42 -04:00
},
2016-06-22 13:15:09 -04:00
"action_name": "marked",
"target_type": "MergeRequest",
"target": {
"id": 34,
"iid": 7,
"project_id": 2,
"title": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
"description": "Et ea et omnis illum cupiditate. Dolor aspernatur tenetur ducimus facilis est nihil. Quo esse cupiditate molestiae illo corrupti qui quidem dolor.",
"state": "opened",
"created_at": "2016-06-17T07:49:24.419Z",
"updated_at": "2016-06-17T07:52:43.484Z",
"target_branch": "tutorials_git_tricks",
"source_branch": "DNSBL_docs",
"upvotes": 0,
"downvotes": 0,
"author": {
"name": "Maxie Medhurst",
"username": "craig_rutherford",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80& d=identicon",
2016-10-13 07:24:09 -04:00
"web_url": "https://gitlab.example.com/craig_rutherford"
2016-06-22 13:15:09 -04:00
},
"assignee": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
2016-10-13 07:24:09 -04:00
"web_url": "https://gitlab.example.com/root"
2016-06-22 13:15:09 -04:00
},
"source_project_id": 2,
"target_project_id": 2,
"labels": [],
2021-06-09 23:10:01 -04:00
"draft": false,
2016-06-22 13:15:09 -04:00
"work_in_progress": false,
"milestone": {
"id": 32,
"iid": 2,
"project_id": 2,
"title": "v1.0",
"description": "Assumenda placeat ea voluptatem voluptate qui.",
"state": "active",
"created_at": "2016-06-17T07:47:34.163Z",
"updated_at": "2016-06-17T07:47:34.163Z",
"due_date": null
},
2017-02-17 08:56:13 -05:00
"merge_when_pipeline_succeeds": false,
2016-06-22 13:15:09 -04:00
"merge_status": "cannot_be_merged",
"user_notes_count": 7
},
2020-02-06 10:09:11 -05:00
"target_url": "https://gitlab.example.com/gitlab-org/gitlab-foss/-/merge_requests/7",
2016-06-22 13:15:09 -04:00
"body": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
2016-06-16 05:12:42 -04:00
"state": "pending",
2020-04-23 05:09:46 -04:00
"created_at": "2016-06-17T07:52:35.225Z",
"updated_at": "2016-06-17T07:52:35.225Z"
2016-06-16 05:12:42 -04:00
},
{
2016-06-22 13:15:09 -04:00
"id": 98,
2016-06-16 05:12:42 -04:00
"project": {
2016-06-22 13:15:09 -04:00
"id": 2,
"name": "Gitlab Ce",
"name_with_namespace": "Gitlab Org / Gitlab Ce",
2019-09-18 14:06:14 -04:00
"path": "gitlab-foss",
"path_with_namespace": "gitlab-org/gitlab-foss"
2016-06-16 05:12:42 -04:00
},
"author": {
2016-06-22 13:15:09 -04:00
"name": "Maxie Medhurst",
"username": "craig_rutherford",
"id": 12,
2016-06-16 05:12:42 -04:00
"state": "active",
2016-06-22 13:15:09 -04:00
"avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80& d=identicon",
2016-10-13 07:24:09 -04:00
"web_url": "https://gitlab.example.com/craig_rutherford"
2016-06-16 05:12:42 -04:00
},
2016-06-22 13:15:09 -04:00
"action_name": "assigned",
"target_type": "MergeRequest",
"target": {
"id": 34,
"iid": 7,
"project_id": 2,
"title": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
"description": "Et ea et omnis illum cupiditate. Dolor aspernatur tenetur ducimus facilis est nihil. Quo esse cupiditate molestiae illo corrupti qui quidem dolor.",
"state": "opened",
"created_at": "2016-06-17T07:49:24.419Z",
"updated_at": "2016-06-17T07:52:43.484Z",
"target_branch": "tutorials_git_tricks",
"source_branch": "DNSBL_docs",
"upvotes": 0,
"downvotes": 0,
"author": {
"name": "Maxie Medhurst",
"username": "craig_rutherford",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80& d=identicon",
2016-10-13 07:24:09 -04:00
"web_url": "https://gitlab.example.com/craig_rutherford"
2016-06-22 13:15:09 -04:00
},
"assignee": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
2016-10-13 07:24:09 -04:00
"web_url": "https://gitlab.example.com/root"
2016-06-22 13:15:09 -04:00
},
"source_project_id": 2,
"target_project_id": 2,
"labels": [],
2021-06-09 23:10:01 -04:00
"draft": false,
2016-06-22 13:15:09 -04:00
"work_in_progress": false,
"milestone": {
"id": 32,
"iid": 2,
"project_id": 2,
"title": "v1.0",
"description": "Assumenda placeat ea voluptatem voluptate qui.",
"state": "active",
"created_at": "2016-06-17T07:47:34.163Z",
"updated_at": "2016-06-17T07:47:34.163Z",
"due_date": null
},
2017-02-17 08:56:13 -05:00
"merge_when_pipeline_succeeds": false,
2016-06-22 13:15:09 -04:00
"merge_status": "cannot_be_merged",
"user_notes_count": 7
},
2020-02-06 10:09:11 -05:00
"target_url": "https://gitlab.example.com/gitlab-org/gitlab-foss/-/merge_requests/7",
2016-06-22 13:15:09 -04:00
"body": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
2016-06-16 05:12:42 -04:00
"state": "pending",
2020-04-23 05:09:46 -04:00
"created_at": "2016-06-17T07:49:24.624Z",
"updated_at": "2016-06-17T07:49:24.624Z"
2016-06-16 05:12:42 -04:00
}
]
```
2020-10-28 14:08:52 -04:00
## Mark a to-do item as done
2016-06-16 05:12:42 -04:00
2020-10-02 14:08:56 -04:00
Marks a single pending to do given by its ID for the current user as done. The
to do marked as done is returned in the response.
2016-06-16 05:12:42 -04:00
2020-02-28 22:07:51 -05:00
```plaintext
2017-02-21 04:00:33 -05:00
POST /todos/:id/mark_as_done
2016-06-16 05:12:42 -04:00
```
Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2020-10-28 14:08:52 -04:00
| `id` | integer | yes | The ID of to-do item |
2016-06-16 05:12:42 -04:00
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/todos/130/mark_as_done"
2016-06-16 05:12:42 -04:00
```
Example Response:
```json
{
2016-06-22 13:15:09 -04:00
"id": 102,
"project": {
"id": 2,
"name": "Gitlab Ce",
"name_with_namespace": "Gitlab Org / Gitlab Ce",
2019-09-18 14:06:14 -04:00
"path": "gitlab-foss",
"path_with_namespace": "gitlab-org/gitlab-foss"
2016-06-22 13:15:09 -04:00
},
"author": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
2016-10-13 07:24:09 -04:00
"web_url": "https://gitlab.example.com/root"
2016-06-22 13:15:09 -04:00
},
"action_name": "marked",
"target_type": "MergeRequest",
"target": {
"id": 34,
"iid": 7,
"project_id": 2,
"title": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
"description": "Et ea et omnis illum cupiditate. Dolor aspernatur tenetur ducimus facilis est nihil. Quo esse cupiditate molestiae illo corrupti qui quidem dolor.",
"state": "opened",
"created_at": "2016-06-17T07:49:24.419Z",
"updated_at": "2016-06-17T07:52:43.484Z",
"target_branch": "tutorials_git_tricks",
"source_branch": "DNSBL_docs",
"upvotes": 0,
"downvotes": 0,
"author": {
"name": "Maxie Medhurst",
"username": "craig_rutherford",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80& d=identicon",
2016-10-13 07:24:09 -04:00
"web_url": "https://gitlab.example.com/craig_rutherford"
2016-06-22 13:15:09 -04:00
},
"assignee": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80& d=identicon",
2016-10-13 07:24:09 -04:00
"web_url": "https://gitlab.example.com/root"
2016-06-22 13:15:09 -04:00
},
"source_project_id": 2,
"target_project_id": 2,
"labels": [],
2021-06-09 23:10:01 -04:00
"draft": false,
2016-06-22 13:15:09 -04:00
"work_in_progress": false,
"milestone": {
"id": 32,
"iid": 2,
"project_id": 2,
"title": "v1.0",
"description": "Assumenda placeat ea voluptatem voluptate qui.",
"state": "active",
"created_at": "2016-06-17T07:47:34.163Z",
"updated_at": "2016-06-17T07:47:34.163Z",
"due_date": null
},
2017-02-17 08:56:13 -05:00
"merge_when_pipeline_succeeds": false,
2016-06-22 13:15:09 -04:00
"merge_status": "cannot_be_merged",
"subscribed": true,
"user_notes_count": 7
},
2020-02-06 10:09:11 -05:00
"target_url": "https://gitlab.example.com/gitlab-org/gitlab-foss/-/merge_requests/7",
2016-06-22 13:15:09 -04:00
"body": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
"state": "done",
2020-04-23 05:09:46 -04:00
"created_at": "2016-06-17T07:52:35.225Z",
"updated_at": "2016-06-17T07:52:35.225Z"
2016-06-16 05:12:42 -04:00
}
```
2020-10-02 14:08:56 -04:00
## Mark all to dos as done
2016-06-16 05:12:42 -04:00
2020-10-02 14:08:56 -04:00
Marks all pending to dos for the current user as done. It returns the HTTP status code `204` with an empty response.
2016-06-16 05:12:42 -04:00
2020-02-28 22:07:51 -05:00
```plaintext
2017-02-21 04:00:33 -05:00
POST /todos/mark_as_done
2016-06-16 05:12:42 -04:00
```
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/todos/mark_as_done"
2016-06-16 05:12:42 -04:00
```