Microsoft

Microsoft Graph: To Do and Planner tasks

Manage Microsoft To Do task lists, tasks, checklist items and linked resources, and Planner plans, buckets and tasks. This listing is one area of Microsoft…

Productivity & workspace#openapi

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

Manage Microsoft To Do task lists, tasks, checklist items and linked resources, and Planner plans, buckets and tasks.

This listing is one area of Microsoft Graph, the single REST API for Microsoft 365, Outlook, OneDrive, Teams and Microsoft Entra ID. It holds 157 of the area's requests, the most direct ones first, generated from Microsoft's own OpenAPI description of Graph v1.0. The other areas (mail, calendar, files, Teams, users and more) are listed separately on the Microsoft page.

Get an access token

  1. Sign in to the Microsoft Entra admin center and open App registrations > New registration. For a quick test, the Graph Explorer signs you in and shows a token without registering anything.
  2. Under API permissions, add the Microsoft Graph permissions this area needs, for example: Tasks.Read, Tasks.ReadWrite, Group.ReadWrite.All (Planner). Delegated permissions act as the signed-in user; application permissions act as the app itself and need an administrator's consent.
  3. Under Certificates & secrets, create a client secret (keep it out of shared collections).
  4. Get a token from https://login.microsoftonline.com/ /oauth2/v2.0/token: the authorization-code flow for a user, or grant_type=client_credentials with scope=https://graph.microsoft.com/.default for an app. Send it as Authorization: Bearer .

Using these requests

  • Base URL: https://graph.microsoft.com/v1.0. /me/... paths act on the signed-in user; with an application token use /users/{id or userPrincipalName}/... instead.
  • Shape responses with OData query parameters: $select (fields), $filter, $orderby, $top, $expand and $search (some need the ConsistencyLevel: eventual header). Long lists are paged: follow @odata.nextLink.
  • Combine up to 20 requests in one call with POST /$batch.

Common errors

StatusCodeWhat to do
401InvalidAuthenticationTokenThe token is missing, expired or for another resource: get a new one for https://graph.microsoft.com.
403Authorization_RequestDenied / ErrorAccessDeniedAdd the permission listed in the request's docs and grant consent.
404ResourceNotFound / itemNotFoundCheck the id; ids from another user or tenant are not found.
429TooManyRequestsThrottled: wait the Retry-After seconds, then retry.

Docs: To Do and Planner tasks overview · Permissions reference · Throttling

Endpoints 157

Todo

  • GETGet todo/me/todoRepresents the To Do services available to a user.
  • DELETEDelete todo/me/todo
  • PATCHUpdate todo/me/todo

Todo: lists

  • GETList lists/me/todo/listsGet a list of the todoTaskList objects and their properties.
  • POSTCreate list/me/todo/listsCreate a new lists object.
  • GETTrack changes to lists (delta)/me/todo/lists/delta()Get a set of todoTaskList resources that have been added, deleted, or removed in Microsoft To Do. A delta function call for todoTaskList is similar to a GET…
  • GETGet list/me/todo/lists/:todoTaskList-idRead the properties and relationships of a todoTaskList object.
  • DELETEDelete list/me/todo/lists/:todoTaskList-idDeletes a todoTaskList object.
  • PATCHUpdate list/me/todo/lists/:todoTaskList-idUpdate the properties of a todoTaskList object.
  • GETList tasks/me/todo/lists/:todoTaskList-id/tasksGet the todoTask resources from the tasks navigation property of a specified todoTaskList.
  • POSTCreate task/me/todo/lists/:todoTaskList-id/tasksCreate a new task object in a specified todoTaskList.
  • GETList extensions/me/todo/lists/:todoTaskList-id/extensionsThe collection of open extensions defined for the task list. Nullable.
  • POSTCreate extension/me/todo/lists/:todoTaskList-id/extensions
  • GETTrack changes to tasks (delta)/me/todo/lists/:todoTaskList-id/tasks/delta()Get a set of todoTask resources that have been added, deleted, or updated in a specified todoTaskList. A delta function call for todoTask resources in a…
  • GETGet task/me/todo/lists/:todoTaskList-id/tasks/:todoTask-idRead the properties and relationships of a todoTask object.
  • DELETEDelete task/me/todo/lists/:todoTaskList-id/tasks/:todoTask-idDelete a todoTask object.
  • PATCHUpdate task/me/todo/lists/:todoTaskList-id/tasks/:todoTask-idUpdate the properties of a todoTask object.
  • GETGet extension/me/todo/lists/:todoTaskList-id/extensions/:extension-idThe collection of open extensions defined for the task list. Nullable.
  • DELETEDelete extension/me/todo/lists/:todoTaskList-id/extensions/:extension-id
  • PATCHUpdate extension/me/todo/lists/:todoTaskList-id/extensions/:extension-id
  • GETList extensions/me/todo/lists/:todoTaskList-id/tasks/:todoTask-id/extensionsThe collection of open extensions defined for the task. Nullable.
  • POSTCreate extension/me/todo/lists/:todoTaskList-id/tasks/:todoTask-id/extensions
  • GETList attachments/me/todo/lists/:todoTaskList-id/tasks/:todoTask-id/attachmentsGet a list of the taskFileAttachment objects and their properties. The contentBytes property will not be returned in the response. Use the Get attachment API…
  • POSTCreate attachment/me/todo/lists/:todoTaskList-id/tasks/:todoTask-id/attachmentsAdd a new taskFileAttachment object to a todoTask. This operation limits the size of the attachment you can add to under 3 MB. If the size of the file…
  • GETList checklist items/me/todo/lists/:todoTaskList-id/tasks/:todoTask-id/checklistItemsGet the checklistItem resources associated to a todoTask from the checklistItems navigation property.
  • POSTCreate checklist item/me/todo/lists/:todoTaskList-id/tasks/:todoTask-id/checklistItemsCreate a new checklistItem object.
  • GETList linked resources/me/todo/lists/:todoTaskList-id/tasks/:todoTask-id/linkedResourcesGet information of one or more items in a partner application, based on which a specified task was created. The information is represented in a linkedResource…
  • POSTCreate linked resource/me/todo/lists/:todoTaskList-id/tasks/:todoTask-id/linkedResourcesCreate a linkedResource object to associate a specified task with an item in a partner application. For example, you can associate a task with an email item…
  • GETList attachment sessions/me/todo/lists/:todoTaskList-id/tasks/:todoTask-id/attachmentSessions

Planner

  • GETGet planner/planner
  • PATCHUpdate planner/planner
  • GETGet planner/me/plannerEntry-point to the Planner resource that might exist for a user. Read-only.
  • DELETEDelete planner/me/planner
  • PATCHUpdate planner/me/planner

Planner: plans

  • GETList plans/planner/plansGet a list of plannerPlan objects.
  • POSTCreate plan/planner/plansCreate a new plannerPlan object.
  • GETGet plan/planner/plans/:plannerPlan-idRetrieve the properties and relationships of a plannerplan object.
  • DELETEDelete plan/planner/plans/:plannerPlan-idDelete a plannerPlan object.
  • PATCHUpdate plan/planner/plans/:plannerPlan-idUpdate the properties of a plannerPlan object.
  • GETList tasks/planner/plans/:plannerPlan-id/tasksRetrieve a list of plannerTask objects associated with a plannerPlan object.
  • POSTCreate task/planner/plans/:plannerPlan-id/tasks
  • GETList buckets/planner/plans/:plannerPlan-id/bucketsRetrieve a list of plannerBucket objects contained by a plannerPlan object.
  • POSTCreate bucket/planner/plans/:plannerPlan-id/buckets
  • GETList details/planner/plans/:plannerPlan-id/detailsRetrieve the properties and relationships of a plannerPlanDetails object.
  • DELETEDelete details/planner/plans/:plannerPlan-id/details
  • PATCHUpdate details/planner/plans/:plannerPlan-id/detailsUpdate the properties of plannerplandetails object.
  • GETGet task/planner/plans/:plannerPlan-id/tasks/:plannerTask-idRead-only. Nullable. Collection of tasks in the plan.
  • DELETEDelete task/planner/plans/:plannerPlan-id/tasks/:plannerTask-id
  • PATCHUpdate task/planner/plans/:plannerPlan-id/tasks/:plannerTask-id
  • GETGet bucket/planner/plans/:plannerPlan-id/buckets/:plannerBucket-idRead-only. Nullable. Collection of buckets in the plan.
  • DELETEDelete bucket/planner/plans/:plannerPlan-id/buckets/:plannerBucket-id
  • PATCHUpdate bucket/planner/plans/:plannerPlan-id/buckets/:plannerBucket-id
  • GETList details/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/detailsRead-only. Nullable. More details about the task.
  • DELETEDelete details/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/details
  • PATCHUpdate details/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/details
  • GETList tasks/planner/plans/:plannerPlan-id/buckets/:plannerBucket-id/tasksRead-only. Nullable. The collection of tasks in the bucket.
  • POSTCreate task/planner/plans/:plannerPlan-id/buckets/:plannerBucket-id/tasks
  • GETGet bucket task board format/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/bucketTaskBoardFormatRead-only. Nullable. Used to render the task correctly in the task board view when grouped by bucket.
  • DELETEDelete bucket task board format/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/bucketTaskBoardFormat
  • PATCHUpdate bucket task board format/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/bucketTaskBoardFormat
  • GETGet progress task board format/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/progressTaskBoardFormatRead-only. Nullable. Used to render the task correctly in the task board view when grouped by progress.
  • DELETEDelete progress task board format/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/progressTaskBoardFormat
  • PATCHUpdate progress task board format/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/progressTaskBoardFormat
  • GETGet assigned to task board format/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/assignedToTaskBoardFormatRead-only. Nullable. Used to render the task correctly in the task board view when grouped by assignedTo.
  • DELETEDelete assigned to task board format/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/assignedToTaskBoardFormat
  • PATCHUpdate assigned to task board format/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/assignedToTaskBoardFormat
  • GETGet task/planner/plans/:plannerPlan-id/buckets/:plannerBucket-id/tasks/:plannerTask-idRead-only. Nullable. The collection of tasks in the bucket.
  • DELETEDelete task/planner/plans/:plannerPlan-id/buckets/:plannerBucket-id/tasks/:plannerTask-id
  • PATCHUpdate task/planner/plans/:plannerPlan-id/buckets/:plannerBucket-id/tasks/:plannerTask-id
  • GETList plans/me/planner/plansRetrieve a list of plannerplan objects shared with a user object.
  • POSTCreate plan/me/planner/plans
  • GETGet plan/me/planner/plans/:plannerPlan-idRead-only. Nullable. Returns the plannerTasks assigned to the user.
  • DELETEDelete plan/me/planner/plans/:plannerPlan-id
  • PATCHUpdate plan/me/planner/plans/:plannerPlan-id
  • GETList tasks/me/planner/plans/:plannerPlan-id/tasksRead-only. Nullable. Collection of tasks in the plan.
  • POSTCreate task/me/planner/plans/:plannerPlan-id/tasks
  • GETList buckets/me/planner/plans/:plannerPlan-id/bucketsRead-only. Nullable. Collection of buckets in the plan.
  • POSTCreate bucket/me/planner/plans/:plannerPlan-id/buckets
  • GETList details/me/planner/plans/:plannerPlan-id/detailsRead-only. Nullable. Extra details about the plan.
  • DELETEDelete details/me/planner/plans/:plannerPlan-id/details
  • PATCHUpdate details/me/planner/plans/:plannerPlan-id/details
  • GETGet task/me/planner/plans/:plannerPlan-id/tasks/:plannerTask-idRead-only. Nullable. Collection of tasks in the plan.
  • DELETEDelete task/me/planner/plans/:plannerPlan-id/tasks/:plannerTask-id
  • PATCHUpdate task/me/planner/plans/:plannerPlan-id/tasks/:plannerTask-id
  • GETGet bucket/me/planner/plans/:plannerPlan-id/buckets/:plannerBucket-idRead-only. Nullable. Collection of buckets in the plan.
  • DELETEDelete bucket/me/planner/plans/:plannerPlan-id/buckets/:plannerBucket-id
  • PATCHUpdate bucket/me/planner/plans/:plannerPlan-id/buckets/:plannerBucket-id
  • GETList details/me/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/detailsRead-only. Nullable. More details about the task.
  • DELETEDelete details/me/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/details
  • PATCHUpdate details/me/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/details
  • GETList tasks/me/planner/plans/:plannerPlan-id/buckets/:plannerBucket-id/tasksRead-only. Nullable. The collection of tasks in the bucket.
  • POSTCreate task/me/planner/plans/:plannerPlan-id/buckets/:plannerBucket-id/tasks
  • GETGet bucket task board format/me/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/bucketTaskBoardFormatRead-only. Nullable. Used to render the task correctly in the task board view when grouped by bucket.
  • DELETEDelete bucket task board format/me/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/bucketTaskBoardFormat
  • PATCHUpdate bucket task board format/me/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/bucketTaskBoardFormat
  • GETGet progress task board format/me/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/progressTaskBoardFormatRead-only. Nullable. Used to render the task correctly in the task board view when grouped by progress.
  • DELETEDelete progress task board format/me/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/progressTaskBoardFormat
  • PATCHUpdate progress task board format/me/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/progressTaskBoardFormat
  • GETGet assigned to task board format/me/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/assignedToTaskBoardFormatRead-only. Nullable. Used to render the task correctly in the task board view when grouped by assignedTo.
  • DELETEDelete assigned to task board format/me/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/assignedToTaskBoardFormat
  • PATCHUpdate assigned to task board format/me/planner/plans/:plannerPlan-id/tasks/:plannerTask-id/assignedToTaskBoardFormat

Planner: tasks

  • GETList tasks/planner/tasksRetrieve a list of plannertask objects.
  • POSTCreate task/planner/tasksCreate a new plannerTask.
  • GETGet task/planner/tasks/:plannerTask-idRetrieve the properties and relationships of plannerTask object.
  • DELETEDelete task/planner/tasks/:plannerTask-idDelete a plannerTask object.
  • PATCHUpdate task/planner/tasks/:plannerTask-idUpdate the properties of plannerTask object.
  • GETList details/planner/tasks/:plannerTask-id/detailsRetrieve the properties and relationships of a plannerTaskDetails object.
  • DELETEDelete details/planner/tasks/:plannerTask-id/details
  • PATCHUpdate details/planner/tasks/:plannerTask-id/detailsUpdate the properties of plannerTaskDetails object.
  • GETGet bucket task board format/planner/tasks/:plannerTask-id/bucketTaskBoardFormatRetrieve the properties and relationships of plannerBucketTaskBoardTaskFormat object.
  • DELETEDelete bucket task board format/planner/tasks/:plannerTask-id/bucketTaskBoardFormat
  • PATCHUpdate bucket task board format/planner/tasks/:plannerTask-id/bucketTaskBoardFormatUpdate the properties of a plannerBucketTaskBoardTaskFormat object.
  • GETGet progress task board format/planner/tasks/:plannerTask-id/progressTaskBoardFormatRetrieve the properties and relationships of plannerProgressTaskBoardTaskFormat object.
  • DELETEDelete progress task board format/planner/tasks/:plannerTask-id/progressTaskBoardFormat
  • PATCHUpdate progress task board format/planner/tasks/:plannerTask-id/progressTaskBoardFormatUpdate the properties of plannerProgressTaskBoardTaskFormat object.
  • GETGet assigned to task board format/planner/tasks/:plannerTask-id/assignedToTaskBoardFormatRetrieve the properties and relationships of a plannerAssignedToTaskBoardTaskFormat object.
  • DELETEDelete assigned to task board format/planner/tasks/:plannerTask-id/assignedToTaskBoardFormat
  • PATCHUpdate assigned to task board format/planner/tasks/:plannerTask-id/assignedToTaskBoardFormatUpdate the properties of plannerAssignedToTaskBoardTaskFormat object.
  • GETList tasks/me/planner/tasksRetrieve a list of plannertask objects assigned to a User.
  • POSTCreate task/me/planner/tasks
  • GETGet task/me/planner/tasks/:plannerTask-idRead-only. Nullable. Returns the plannerPlans shared with the user.
  • DELETEDelete task/me/planner/tasks/:plannerTask-id
  • PATCHUpdate task/me/planner/tasks/:plannerTask-id
  • GETList details/me/planner/tasks/:plannerTask-id/detailsRead-only. Nullable. More details about the task.
  • DELETEDelete details/me/planner/tasks/:plannerTask-id/details
  • PATCHUpdate details/me/planner/tasks/:plannerTask-id/details
  • GETGet bucket task board format/me/planner/tasks/:plannerTask-id/bucketTaskBoardFormatRead-only. Nullable. Used to render the task correctly in the task board view when grouped by bucket.
  • DELETEDelete bucket task board format/me/planner/tasks/:plannerTask-id/bucketTaskBoardFormat
  • PATCHUpdate bucket task board format/me/planner/tasks/:plannerTask-id/bucketTaskBoardFormat
  • GETGet progress task board format/me/planner/tasks/:plannerTask-id/progressTaskBoardFormatRead-only. Nullable. Used to render the task correctly in the task board view when grouped by progress.
  • DELETEDelete progress task board format/me/planner/tasks/:plannerTask-id/progressTaskBoardFormat
  • PATCHUpdate progress task board format/me/planner/tasks/:plannerTask-id/progressTaskBoardFormat
  • GETGet assigned to task board format/me/planner/tasks/:plannerTask-id/assignedToTaskBoardFormatRead-only. Nullable. Used to render the task correctly in the task board view when grouped by assignedTo.
  • DELETEDelete assigned to task board format/me/planner/tasks/:plannerTask-id/assignedToTaskBoardFormat
  • PATCHUpdate assigned to task board format/me/planner/tasks/:plannerTask-id/assignedToTaskBoardFormat

Planner: buckets

  • GETList buckets/planner/bucketsRetrieve a list of plannerbucket objects.
  • POSTCreate bucket/planner/bucketsCreate a new plannerBucket object.
  • GETGet bucket/planner/buckets/:plannerBucket-idRetrieve the properties and relationships of a plannerBucket object.
  • DELETEDelete bucket/planner/buckets/:plannerBucket-idDelete plannerBucket.
  • PATCHUpdate bucket/planner/buckets/:plannerBucket-idUpdate the properties of plannerbucket object.
  • GETList tasks/planner/buckets/:plannerBucket-id/tasksRetrieve a list of plannerTask objects associated to a plannerBucket object.
  • POSTCreate task/planner/buckets/:plannerBucket-id/tasks
  • GETGet task/planner/buckets/:plannerBucket-id/tasks/:plannerTask-idRead-only. Nullable. The collection of tasks in the bucket.
  • DELETEDelete task/planner/buckets/:plannerBucket-id/tasks/:plannerTask-id
  • PATCHUpdate task/planner/buckets/:plannerBucket-id/tasks/:plannerTask-id
  • GETList details/planner/buckets/:plannerBucket-id/tasks/:plannerTask-id/detailsRead-only. Nullable. More details about the task.
  • DELETEDelete details/planner/buckets/:plannerBucket-id/tasks/:plannerTask-id/details
  • PATCHUpdate details/planner/buckets/:plannerBucket-id/tasks/:plannerTask-id/details
  • GETGet bucket task board format/planner/buckets/:plannerBucket-id/tasks/:plannerTask-id/bucketTaskBoardFormatRead-only. Nullable. Used to render the task correctly in the task board view when grouped by bucket.
  • DELETEDelete bucket task board format/planner/buckets/:plannerBucket-id/tasks/:plannerTask-id/bucketTaskBoardFormat
  • PATCHUpdate bucket task board format/planner/buckets/:plannerBucket-id/tasks/:plannerTask-id/bucketTaskBoardFormat
  • GETGet progress task board format/planner/buckets/:plannerBucket-id/tasks/:plannerTask-id/progressTaskBoardFormatRead-only. Nullable. Used to render the task correctly in the task board view when grouped by progress.
  • DELETEDelete progress task board format/planner/buckets/:plannerBucket-id/tasks/:plannerTask-id/progressTaskBoardFormat
  • PATCHUpdate progress task board format/planner/buckets/:plannerBucket-id/tasks/:plannerTask-id/progressTaskBoardFormat
  • GETGet assigned to task board format/planner/buckets/:plannerBucket-id/tasks/:plannerTask-id/assignedToTaskBoardFormatRead-only. Nullable. Used to render the task correctly in the task board view when grouped by assignedTo.
  • DELETEDelete assigned to task board format/planner/buckets/:plannerBucket-id/tasks/:plannerTask-id/assignedToTaskBoardFormat
  • PATCHUpdate assigned to task board format/planner/buckets/:plannerBucket-id/tasks/:plannerTask-id/assignedToTaskBoardFormat

API details

Base URL
https://graph.microsoft.com/v1.0
Authentication
OAuth 2.0 (authorization code, client credentials flows)
Operations
157 operations on 61 pathsGET 61PATCH 39DELETE 38POST 19
Main resources
Planner: plans 67Planner: tasks 34Todo: lists 26Planner: buckets 22Planner 5Todo 3
Description format
OpenAPI 3.0.4, API version v1.0

How to test the Microsoft Graph: To Do and Planner tasks in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Microsoft Graph: To Do and Planner tasks collection, without the publisher's secrets.
  3. Add your credentialsThis API uses OAuth 2.0 (authorization code, client credentials flows). Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Get todo” (GET /me/todo), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Microsoft Graph: To Do and Planner tasks?

Manage Microsoft To Do task lists, tasks, checklist items and linked resources, and Planner plans, buckets and tasks. This listing is one area of Microsoft… It is listed under Productivity & workspace and has 157 endpoints.

Who publishes the Microsoft Graph: To Do and Planner tasks?

It is listed from Microsoft's public API description (an OpenAPI document), not published by Microsoft on Swastik Codes. Anyone who controls microsoft.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Microsoft Graph: To Do and Planner tasks?

Requests go to https://graph.microsoft.com/v1.0. Endpoint paths are added to this base URL.

How do I authenticate with the Microsoft Graph: To Do and Planner tasks?

With OAuth 2.0 (authorization code, client credentials flows).

How many endpoints does the Microsoft Graph: To Do and Planner tasks have?

157 operations on 61 paths (61 GET, 39 PATCH, 38 DELETE, 19 POST). The largest groups are Planner: plans, Planner: tasks, Todo: lists, Planner: buckets.

Is forking the Microsoft Graph: To Do and Planner tasks free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.