1---
2stage: Plan
3group: Project Management
4info: 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
5---
6
7# GitLab To-Do List API **(FREE)**
8
9Interact with [to-do items](../user/todos.md) using the REST API.
10
11## Get a list of to-do items
12
13Returns a list of to-do items. When no filter is applied, it
14returns all pending to-do items for the current user. Different filters allow the
15user to refine the request.
16
17```plaintext
18GET /todos
19```
20
21Parameters:
22
23| Attribute | Type | Required | Description |
24| --------- | ---- | -------- | ----------- |
25| `action` | string | no | The action to be filtered. Can be `assigned`, `mentioned`, `build_failed`, `marked`, `approval_required`, `unmergeable`, `directly_addressed` or `merge_train_removed`. |
26| `author_id` | integer | no | The ID of an author |
27| `project_id` | integer | no | The ID of a project |
28| `group_id` | integer | no | The ID of a group |
29| `state` | string | no | The state of the to-do item. Can be either `pending` or `done` |
30| `type` | string | no | The type of to-do item. Can be either `Issue`, `MergeRequest`, `Commit`, `Epic`, `DesignManagement::Design` or `AlertManagement::Alert` |
31
32```shell
33curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/todos"
34```
35
36Example Response:
37
38```json
39[
40  {
41    "id": 102,
42    "project": {
43      "id": 2,
44      "name": "Gitlab Ce",
45      "name_with_namespace": "Gitlab Org / Gitlab Ce",
46      "path": "gitlab-foss",
47      "path_with_namespace": "gitlab-org/gitlab-foss"
48    },
49    "author": {
50      "name": "Administrator",
51      "username": "root",
52      "id": 1,
53      "state": "active",
54      "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
55      "web_url": "https://gitlab.example.com/root"
56    },
57    "action_name": "marked",
58    "target_type": "MergeRequest",
59    "target": {
60      "id": 34,
61      "iid": 7,
62      "project_id": 2,
63      "title": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
64      "description": "Et ea et omnis illum cupiditate. Dolor aspernatur tenetur ducimus facilis est nihil. Quo esse cupiditate molestiae illo corrupti qui quidem dolor.",
65      "state": "opened",
66      "created_at": "2016-06-17T07:49:24.419Z",
67      "updated_at": "2016-06-17T07:52:43.484Z",
68      "target_branch": "tutorials_git_tricks",
69      "source_branch": "DNSBL_docs",
70      "upvotes": 0,
71      "downvotes": 0,
72      "author": {
73        "name": "Maxie Medhurst",
74        "username": "craig_rutherford",
75        "id": 12,
76        "state": "active",
77        "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon",
78        "web_url": "https://gitlab.example.com/craig_rutherford"
79      },
80      "assignee": {
81        "name": "Administrator",
82        "username": "root",
83        "id": 1,
84        "state": "active",
85        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
86        "web_url": "https://gitlab.example.com/root"
87      },
88      "source_project_id": 2,
89      "target_project_id": 2,
90      "labels": [],
91      "draft": false,
92      "work_in_progress": false,
93      "milestone": {
94        "id": 32,
95        "iid": 2,
96        "project_id": 2,
97        "title": "v1.0",
98        "description": "Assumenda placeat ea voluptatem voluptate qui.",
99        "state": "active",
100        "created_at": "2016-06-17T07:47:34.163Z",
101        "updated_at": "2016-06-17T07:47:34.163Z",
102        "due_date": null
103      },
104      "merge_when_pipeline_succeeds": false,
105      "merge_status": "cannot_be_merged",
106      "user_notes_count": 7
107    },
108    "target_url": "https://gitlab.example.com/gitlab-org/gitlab-foss/-/merge_requests/7",
109    "body": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
110    "state": "pending",
111    "created_at": "2016-06-17T07:52:35.225Z",
112    "updated_at": "2016-06-17T07:52:35.225Z"
113  },
114  {
115    "id": 98,
116    "project": {
117      "id": 2,
118      "name": "Gitlab Ce",
119      "name_with_namespace": "Gitlab Org / Gitlab Ce",
120      "path": "gitlab-foss",
121      "path_with_namespace": "gitlab-org/gitlab-foss"
122    },
123    "author": {
124      "name": "Maxie Medhurst",
125      "username": "craig_rutherford",
126      "id": 12,
127      "state": "active",
128      "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon",
129      "web_url": "https://gitlab.example.com/craig_rutherford"
130    },
131    "action_name": "assigned",
132    "target_type": "MergeRequest",
133    "target": {
134      "id": 34,
135      "iid": 7,
136      "project_id": 2,
137      "title": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
138      "description": "Et ea et omnis illum cupiditate. Dolor aspernatur tenetur ducimus facilis est nihil. Quo esse cupiditate molestiae illo corrupti qui quidem dolor.",
139      "state": "opened",
140      "created_at": "2016-06-17T07:49:24.419Z",
141      "updated_at": "2016-06-17T07:52:43.484Z",
142      "target_branch": "tutorials_git_tricks",
143      "source_branch": "DNSBL_docs",
144      "upvotes": 0,
145      "downvotes": 0,
146      "author": {
147        "name": "Maxie Medhurst",
148        "username": "craig_rutherford",
149        "id": 12,
150        "state": "active",
151        "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon",
152        "web_url": "https://gitlab.example.com/craig_rutherford"
153      },
154      "assignee": {
155        "name": "Administrator",
156        "username": "root",
157        "id": 1,
158        "state": "active",
159        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
160        "web_url": "https://gitlab.example.com/root"
161      },
162      "source_project_id": 2,
163      "target_project_id": 2,
164      "labels": [],
165      "draft": false,
166      "work_in_progress": false,
167      "milestone": {
168        "id": 32,
169        "iid": 2,
170        "project_id": 2,
171        "title": "v1.0",
172        "description": "Assumenda placeat ea voluptatem voluptate qui.",
173        "state": "active",
174        "created_at": "2016-06-17T07:47:34.163Z",
175        "updated_at": "2016-06-17T07:47:34.163Z",
176        "due_date": null
177      },
178      "merge_when_pipeline_succeeds": false,
179      "merge_status": "cannot_be_merged",
180      "user_notes_count": 7
181    },
182    "target_url": "https://gitlab.example.com/gitlab-org/gitlab-foss/-/merge_requests/7",
183    "body": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
184    "state": "pending",
185    "created_at": "2016-06-17T07:49:24.624Z",
186    "updated_at": "2016-06-17T07:49:24.624Z"
187  }
188]
189```
190
191## Mark a to-do item as done
192
193Marks a single pending to-do item given by its ID for the current user as done. The
194to-do item marked as done is returned in the response.
195
196```plaintext
197POST /todos/:id/mark_as_done
198```
199
200Parameters:
201
202| Attribute | Type | Required | Description |
203| --------- | ---- | -------- | ----------- |
204| `id` | integer | yes | The ID of to-do item |
205
206```shell
207curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/todos/130/mark_as_done"
208```
209
210Example Response:
211
212```json
213{
214    "id": 102,
215    "project": {
216      "id": 2,
217      "name": "Gitlab Ce",
218      "name_with_namespace": "Gitlab Org / Gitlab Ce",
219      "path": "gitlab-foss",
220      "path_with_namespace": "gitlab-org/gitlab-foss"
221    },
222    "author": {
223      "name": "Administrator",
224      "username": "root",
225      "id": 1,
226      "state": "active",
227      "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
228      "web_url": "https://gitlab.example.com/root"
229    },
230    "action_name": "marked",
231    "target_type": "MergeRequest",
232    "target": {
233      "id": 34,
234      "iid": 7,
235      "project_id": 2,
236      "title": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
237      "description": "Et ea et omnis illum cupiditate. Dolor aspernatur tenetur ducimus facilis est nihil. Quo esse cupiditate molestiae illo corrupti qui quidem dolor.",
238      "state": "opened",
239      "created_at": "2016-06-17T07:49:24.419Z",
240      "updated_at": "2016-06-17T07:52:43.484Z",
241      "target_branch": "tutorials_git_tricks",
242      "source_branch": "DNSBL_docs",
243      "upvotes": 0,
244      "downvotes": 0,
245      "author": {
246        "name": "Maxie Medhurst",
247        "username": "craig_rutherford",
248        "id": 12,
249        "state": "active",
250        "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon",
251        "web_url": "https://gitlab.example.com/craig_rutherford"
252      },
253      "assignee": {
254        "name": "Administrator",
255        "username": "root",
256        "id": 1,
257        "state": "active",
258        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
259        "web_url": "https://gitlab.example.com/root"
260      },
261      "source_project_id": 2,
262      "target_project_id": 2,
263      "labels": [],
264      "draft": false,
265      "work_in_progress": false,
266      "milestone": {
267        "id": 32,
268        "iid": 2,
269        "project_id": 2,
270        "title": "v1.0",
271        "description": "Assumenda placeat ea voluptatem voluptate qui.",
272        "state": "active",
273        "created_at": "2016-06-17T07:47:34.163Z",
274        "updated_at": "2016-06-17T07:47:34.163Z",
275        "due_date": null
276      },
277      "merge_when_pipeline_succeeds": false,
278      "merge_status": "cannot_be_merged",
279      "subscribed": true,
280      "user_notes_count": 7
281    },
282    "target_url": "https://gitlab.example.com/gitlab-org/gitlab-foss/-/merge_requests/7",
283    "body": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
284    "state": "done",
285    "created_at": "2016-06-17T07:52:35.225Z",
286    "updated_at": "2016-06-17T07:52:35.225Z"
287}
288```
289
290## Mark all to-do items as done
291
292Marks all pending to-do items for the current user as done. It returns the HTTP status code `204` with an empty response.
293
294```plaintext
295POST /todos/mark_as_done
296```
297
298```shell
299curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/todos/mark_as_done"
300```
301