Microsoft Planner Task Details API

openapi: 3.1.0
info:
  title: Microsoft Planner Microsoft Graph Planner Buckets Task Details API
  description: The Microsoft Graph Planner API enables programmatic access to Planner resources in Microsoft 365. You can create and manage plans, tasks, and buckets to organize work, assign tasks to users, and track progress within groups. Plans are contained by Microsoft 365 groups, and tasks are organized into buckets within plans. This API covers the v1.0 stable endpoint for basic (non-premium) Planner operations.
  version: 1.0.0
  contact:
    name: Microsoft Graph Support
    url: https://developer.microsoft.com/en-us/graph/support
    email: graphsdksupport@microsoft.com
  license:
    name: Microsoft APIs Terms of Use
    url: https://docs.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
  termsOfService: https://docs.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
  x-apisguru-categories:
  - collaboration
  - project-management
  x-logo:
    url: https://docs.microsoft.com/en-us/media/logos/logo-ms-social.png
servers:
- url: https://graph.microsoft.com/v1.0
  description: Microsoft Graph v1.0 production endpoint
security:
- oauth2:
  - Tasks.Read
  - Tasks.ReadWrite
  - Group.Read.All
  - Group.ReadWrite.All
tags:
- name: Task Details
  description: Operations for managing additional task details
  externalDocs:
    url: https://learn.microsoft.com/en-us/graph/api/resources/plannertaskdetails?view=graph-rest-1.0
paths:
  /planner/tasks/{task-id}/details:
    parameters:
    - $ref: '#/components/parameters/TaskId'
    get:
      operationId: getTaskDetails
      summary: Microsoft Planner Get Task Details
      description: Retrieve the properties and relationships of a plannerTaskDetails object.
      tags:
      - Task Details
      responses:
        '200':
          description: The task details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlannerTaskDetails'
              examples:
                Gettaskdetails200Example:
                  summary: Default getTaskDetails 200 response
                  x-microcks-default: true
                  value:
                    '@odata.etag': example_value
                    id: abc123
                    description: A sample description.
                    checklist: {}
                    references: {}
                    previewType: automatic
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateTaskDetails
      summary: Microsoft Planner Update Task Details
      description: Update the properties of a plannerTaskDetails object. Requires the If-Match header with the last known ETag value.
      tags:
      - Task Details
      parameters:
      - $ref: '#/components/parameters/IfMatch'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlannerTaskDetailsUpdate'
            examples:
              UpdatetaskdetailsRequestExample:
                summary: Default updateTaskDetails request
                x-microcks-default: true
                value:
                  description: A sample description.
                  checklist: {}
                  references: {}
                  previewType: automatic
      responses:
        '200':
          description: The updated task details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlannerTaskDetails'
              examples:
                Updatetaskdetails200Example:
                  summary: Default updateTaskDetails 200 response
                  x-microcks-default: true
                  value:
                    '@odata.etag': example_value
                    id: abc123
                    description: A sample description.
                    checklist: {}
                    references: {}
                    previewType: automatic
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    PlannerChecklistItem:
      type: object
      description: A checklist item on a Planner task
      properties:
        '@odata.type':
          type: string
          const: microsoft.graph.plannerChecklistItem
          example: example_value
        isChecked:
          type: boolean
          description: Whether the item is checked (completed)
          example: true
        lastModifiedBy:
          $ref: '#/components/schemas/IdentitySet'
          readOnly: true
        lastModifiedDateTime:
          type: string
          format: date-time
          description: The date and time the item was last modified
          readOnly: true
          example: '2026-01-15T10:30:00Z'
        orderHint:
          type: string
          description: Hint used to order items in the checklist
          example: example_value
        title:
          type: string
          description: Title of the checklist item
          example: Example Title
    PlannerTaskDetailsUpdate:
      type: object
      description: Request body for updating task details
      properties:
        description:
          type: string
          example: A sample description.
        checklist:
          $ref: '#/components/schemas/PlannerChecklistItems'
        references:
          $ref: '#/components/schemas/PlannerExternalReferences'
        previewType:
          type: string
          enum:
          - automatic
          - noPreview
          - checklist
          - description
          - reference
          example: automatic
    Identity:
      type: object
      description: Represents an identity of an actor
      properties:
        displayName:
          type: string
          description: The display name of the identity
          example: example_value
        id:
          type: string
          description: The unique identifier of the identity
          example: abc123
    PlannerTaskDetails:
      type: object
      description: Represents the additional information about a task, including description, checklist items, and external references.
      properties:
        '@odata.etag':
          type: string
          description: The ETag of the resource
          readOnly: true
          example: example_value
        id:
          type: string
          description: The unique identifier for the task details
          readOnly: true
          example: abc123
        description:
          type: string
          description: Description of the task
          example: A sample description.
        checklist:
          $ref: '#/components/schemas/PlannerChecklistItems'
          description: The collection of checklist items on the task
        references:
          $ref: '#/components/schemas/PlannerExternalReferences'
          description: The collection of references on the task
        previewType:
          type: string
          description: The type of preview shown on the task
          enum:
          - automatic
          - noPreview
          - checklist
          - description
          - reference
          example: automatic
    ODataError:
      type: object
      description: OData error response
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: The error code
            message:
              type: string
              description: A human-readable error message
            innerError:
              type: object
              properties:
                request-id:
                  type: string
                date:
                  type: string
                  format: date-time
          example: example_value
    PlannerChecklistItems:
      type: object
      description: A collection of checklist items on a task. Each key is a GUID identifying the checklist item, and the value is a plannerChecklistItem.
      additionalProperties:
        $ref: '#/components/schemas/PlannerChecklistItem'
    PlannerExternalReferences:
      type: object
      description: A collection of references on a task. Each key is a URL-encoded URL of the reference, and the value is a plannerExternalReference.
      additionalProperties:
        $ref: '#/components/schemas/PlannerExternalReference'
    PlannerExternalReference:
      type: object
      description: An external reference attached to a Planner task
      properties:
        '@odata.type':
          type: string
          const: microsoft.graph.plannerExternalReference
          example: example_value
        alias:
          type: string
          description: A name alias for the reference
          example: example_value
        lastModifiedBy:
          $ref: '#/components/schemas/IdentitySet'
          readOnly: true
        lastModifiedDateTime:
          type: string
          format: date-time
          description: The date and time the reference was last modified
          readOnly: true
          example: '2026-01-15T10:30:00Z'
        previewPriority:
          type: string
          description: Hint used to set the relative priority order in which the reference will be shown as a preview on the task
          example: example_value
        type:
          type: string
          description: The type of the reference (e.g., PowerPoint, Word, Excel, Other)
          example: example_value
    IdentitySet:
      type: object
      description: A set of identities associated with various events for a resource
      properties:
        application:
          $ref: '#/components/schemas/Identity'
        device:
          $ref: '#/components/schemas/Identity'
        user:
          $ref: '#/components/schemas/Identity'
  parameters:
    TaskId:
      name: task-id
      in: path
      required: true
      description: The unique identifier of the plannerTask (28 characters, case-sensitive)
      schema:
        type: string
    IfMatch:
      name: If-Match
      in: header
      required: true
      description: The last known ETag value for the resource. Required for PATCH and DELETE operations. Planner uses ETags for optimistic concurrency control.
      schema:
        type: string
  responses:
    Forbidden:
      description: Forbidden. The caller does not have sufficient permissions, or a service-defined limit has been exceeded (e.g., MaximumTasksInProject, MaximumBucketsInProject).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    PreconditionFailed:
      description: Precondition failed. The If-Match ETag value does not match the current version of the resource. Read the resource again to obtain the latest ETag.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    Conflict:
      description: Conflict. The request conflicts with the current state of the resource due to a concurrent modification.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    Unauthorized:
      description: Unauthorized. The request requires a valid OAuth 2.0 access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    BadRequest:
      description: Bad request. The request body or parameters are invalid. Common causes include incorrect types for open properties, invalid order hint formats, or logically inconsistent data such as a start date after a due date.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization with Microsoft identity platform
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes:
            Tasks.Read: Read user Planner tasks
            Tasks.ReadWrite: Read and write user Planner tasks
            Tasks.Read.All: Read all Planner tasks (admin)
            Tasks.ReadWrite.All: Read and write all Planner tasks (admin)
            Group.Read.All: Read all groups
            Group.ReadWrite.All: Read and write all groups
externalDocs:
  description: Microsoft Graph Planner API documentation
  url: https://learn.microsoft.com/en-us/graph/api/resources/planner-overview?view=graph-rest-1.0