Use this API to list to-do items, mark them as done, and create a to-do item for an issue or a merge request.

Create a to-do item for an issuable

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

Creates a to-do item for the current user on a specified issuable. If a to-do item already exists for the user on that issuable, returns a 304 status code.

Parameters

NameTypeDescription
id
Path, required		StringThe ID or URL-encoded path of the project owned by the authenticated user
issue_iid
Path, required		IntegerThe internal ID of an issuable

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesTodo
400Bad Request—
404Not Found—

Create a to-do item for an issuable

POST /api/v4/projects/{id}/merge_requests/{merge_request_iid}/todo

Creates a to-do item for the current user on a specified issuable. If a to-do item already exists for the user on that issuable, returns a 304 status code.

Parameters

NameTypeDescription
id
Path, required		StringThe ID or URL-encoded path of the project owned by the authenticated user
merge_request_iid
Path, required		IntegerThe internal ID of an issuable

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesTodo
400Bad Request—
404Not Found—

List all to-do items

GET /api/v4/todos

Lists all to-do items. 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.

Parameters

NameTypeDescription
page
Query		IntegerCurrent page number
Default: 1
Example: 1
per_page
Query		IntegerNumber of items per page
Default: 20
Example: 20
action
Query		StringThe action to be filtered
Allowed values: assigned, review_requested, mentioned, build_failed, marked, approval_required, unmergeable, directly_addressed, member_access_requested, review_submitted, ssh_key_expired, ssh_key_expiring_soon, transfer_failed, merge_train_removed
author_id
Query		IntegerThe ID of an author
project_id
Query		IntegerThe ID of a project
group_id
Query		IntegerThe ID of a group
state
Query		StringThe state of the to-do item
Allowed values: pending, done
type
Query		StringThe type of to-do item
Allowed values: Commit, Issue, WorkItem, MergeRequest, DesignManagement::Design, AlertManagement::Alert, Namespace, Project, Key, WikiPage::Meta

Responses

CodeDescriptionSchema
200OKAPIEntitiesTodo
400Bad Request—

Mark all to-do items as done

POST /api/v4/todos/mark_as_done

Marks all pending to-do items for the current user as done. It returns the HTTP status code 204 with an empty response.

Responses

CodeDescriptionSchema
201Created—
400Bad Request—

Mark a to-do item as done

POST /api/v4/todos/{id}/mark_as_done

Marks a to-do item for the current user as done.

Parameters

NameTypeDescription
id
Path, required		IntegerThe ID of to-do item

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesTodo
400Bad Request—
404Not Found—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesCustomAttribute

PropertyTypeDescription
keyStringExample: foo
valueStringExample: bar

APIEntitiesNamespaceBasic

PropertyTypeDescription
avatar_urlStringExample: https://example.com/avatar/12345
full_pathStringExample: group/my_project
idInteger (int64)Example: 2
kindStringExample: project
nameStringExample: project
parent_idInteger (int64)Example: 1
pathStringExample: my_project
web_urlStringExample: https://example.com/group/my_project

APIEntitiesProjectIdentity

PropertyTypeDescription
created_atString (date-time)Example: 2020-05-07T04:27:17.016Z
descriptionStringExample: desc
idInteger (int64)Example: 1
nameStringExample: project1
name_with_namespaceStringExample: John Doe / project1
pathStringExample: project1
path_with_namespaceStringExample: namespace1/project1

APIEntitiesTodo

PropertyTypeDescription
action_nameStringExample: assigned
authorAPIEntitiesUserBasic—
bodyStringExample: Task description
created_atString (date-time)Example: 2016-06-17T07:52:35.225Z
groupAPIEntitiesNamespaceBasic—
idInteger (int64)—
projectAPIEntitiesProjectIdentity—
stateStringExample: pending
targetObject—
target_typeStringExample: Issue
target_urlStringExample: http://example.com/foo/bar/-/issues/1
updated_atString (date-time)Example: 2016-06-17T07:52:35.225Z

APIEntitiesUserBasic

PropertyTypeDescription
avatar_pathStringExample: /user/avatar/28/The-Big-Lebowski-400-400.png
avatar_urlStringExample: https://gravatar.com/avatar/1
custom_attributesArray of APIEntitiesCustomAttribute—
idInteger (int64)Example: 1
lockedBoolean—
nameStringExample: Administrator
public_emailStringExample: john@example.com
stateStringExample: active
usernameStringExample: admin
web_urlStringExample: https://gitlab.example.com/root
←
REST API / Terraform
REST API / Unleash
→