todos.md 9.52 KB
Newer Older
1
# Todos API
2

3
> [Introduced][ce-3188] in GitLab 8.10.
4 5 6 7

## Get a list of todos

Returns a list of todos. When no filter is applied, it returns all pending todos
8
for the current user. Different filters allow the user to precise the request.
9 10 11 12 13 14 15 16 17

```
GET /todos
```

Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
18
| `action` | string | no | The action to be filtered. Can be `assigned`, `mentioned`, `build_failed`, `marked`, `approval_required`, `unmergeable` or `directly_addressed`. |
19 20
| `author_id` | integer | no | The ID of an author |
| `project_id` | integer | no | The ID of a project |
21
| `group_id` | integer | no | The ID of a group |
22
| `state` | string | no | The state of the todo. Can be either `pending` or `done` |
23
| `type` | string | no | The type of a todo. Can be either `Issue` or `MergeRequest` |
24 25

```bash
26
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/todos
27 28 29 30 31 32 33
```

Example Response:

```json
[
  {
34
    "id": 102,
35
    "project": {
36 37 38 39 40
      "id": 2,
      "name": "Gitlab Ce",
      "name_with_namespace": "Gitlab Org / Gitlab Ce",
      "path": "gitlab-ce",
      "path_with_namespace": "gitlab-org/gitlab-ce"
41 42
    },
    "author": {
43 44 45
      "name": "Administrator",
      "username": "root",
      "id": 1,
46
      "state": "active",
47
      "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
48
      "web_url": "https://gitlab.example.com/root"
49
    },
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70
    "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",
71
        "web_url": "https://gitlab.example.com/craig_rutherford"
72 73 74 75 76 77 78
      },
      "assignee": {
        "name": "Administrator",
        "username": "root",
        "id": 1,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
79
        "web_url": "https://gitlab.example.com/root"
80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
      },
      "source_project_id": 2,
      "target_project_id": 2,
      "labels": [],
      "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
      },
96
      "merge_when_pipeline_succeeds": false,
97 98 99 100 101 102
      "merge_status": "cannot_be_merged",
      "subscribed": true,
      "user_notes_count": 7
    },
    "target_url": "https://gitlab.example.com/gitlab-org/gitlab-ce/merge_requests/7",
    "body": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
103
    "state": "pending",
104
    "created_at": "2016-06-17T07:52:35.225Z"
105 106
  },
  {
107
    "id": 98,
108
    "project": {
109 110 111 112 113
      "id": 2,
      "name": "Gitlab Ce",
      "name_with_namespace": "Gitlab Org / Gitlab Ce",
      "path": "gitlab-ce",
      "path_with_namespace": "gitlab-org/gitlab-ce"
114 115
    },
    "author": {
116 117 118
      "name": "Maxie Medhurst",
      "username": "craig_rutherford",
      "id": 12,
119
      "state": "active",
120
      "avatar_url": "http://www.gravatar.com/avatar/a0d477b3ea21970ce6ffcbb817b0b435?s=80&d=identicon",
121
      "web_url": "https://gitlab.example.com/craig_rutherford"
122
    },
123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143
    "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",
144
        "web_url": "https://gitlab.example.com/craig_rutherford"
145 146 147 148 149 150 151
      },
      "assignee": {
        "name": "Administrator",
        "username": "root",
        "id": 1,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
152
        "web_url": "https://gitlab.example.com/root"
153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168
      },
      "source_project_id": 2,
      "target_project_id": 2,
      "labels": [],
      "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
      },
169
      "merge_when_pipeline_succeeds": false,
170 171 172 173 174 175
      "merge_status": "cannot_be_merged",
      "subscribed": true,
      "user_notes_count": 7
    },
    "target_url": "https://gitlab.example.com/gitlab-org/gitlab-ce/merge_requests/7",
    "body": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
176
    "state": "pending",
177
    "created_at": "2016-06-17T07:49:24.624Z"
178 179 180 181 182 183
  }
]
```

## Mark a todo as done

184 185
Marks a single pending todo given by its ID for the current user as done. The
todo marked as done is returned in the response.
186 187

```
188
POST /todos/:id/mark_as_done
189 190 191 192 193 194 195 196 197
```

Parameters:

| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer | yes | The ID of a todo |

```bash
198
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/todos/130/mark_as_done
199 200 201 202 203 204
```

Example Response:

```json
{
205 206 207 208 209 210 211 212 213 214 215 216 217 218
    "id": 102,
    "project": {
      "id": 2,
      "name": "Gitlab Ce",
      "name_with_namespace": "Gitlab Org / Gitlab Ce",
      "path": "gitlab-ce",
      "path_with_namespace": "gitlab-org/gitlab-ce"
    },
    "author": {
      "name": "Administrator",
      "username": "root",
      "id": 1,
      "state": "active",
      "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
219
      "web_url": "https://gitlab.example.com/root"
220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241
    },
    "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",
242
        "web_url": "https://gitlab.example.com/craig_rutherford"
243 244 245 246 247 248 249
      },
      "assignee": {
        "name": "Administrator",
        "username": "root",
        "id": 1,
        "state": "active",
        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
250
        "web_url": "https://gitlab.example.com/root"
251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266
      },
      "source_project_id": 2,
      "target_project_id": 2,
      "labels": [],
      "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
      },
267
      "merge_when_pipeline_succeeds": false,
268 269 270 271 272 273 274 275
      "merge_status": "cannot_be_merged",
      "subscribed": true,
      "user_notes_count": 7
    },
    "target_url": "https://gitlab.example.com/gitlab-org/gitlab-ce/merge_requests/7",
    "body": "Dolores in voluptatem tenetur praesentium omnis repellendus voluptatem quaerat.",
    "state": "done",
    "created_at": "2016-06-17T07:52:35.225Z"
276 277 278 279 280
}
```

## Mark all todos as done

281
Marks all pending todos for the current user as done. It returns the HTTP status code `204` with an empty response.
282 283

```
284
POST /todos/mark_as_done
285 286 287
```

```bash
288
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/todos/mark_as_done
289 290 291
```

[ce-3188]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3188