Google Tasks Tasks Tasks API

The Tasks Tasks API from Google Tasks — 4 operation(s) for tasks tasks.

GitHub OpenAPI

Operations 8

PATCH /tasks/v1/lists/{tasklist}/tasks/{task} Patch tasks #
PUT /tasks/v1/lists/{tasklist}/tasks/{task} Update tasks #
DELETE /tasks/v1/lists/{tasklist}/tasks/{task} Delete tasks #
GET /tasks/v1/lists/{tasklist}/tasks/{task} Get tasks #
POST /tasks/v1/lists/{tasklist}/tasks/{task}/move Move tasks #
GET /tasks/v1/lists/{tasklist}/tasks List tasks #
POST /tasks/v1/lists/{tasklist}/tasks Insert tasks #
POST /tasks/v1/lists/{tasklist}/clear Clear tasks #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/google-tasks:google-tasks-tasks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

google-tasks-tasks-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Google Tasks API
  version: v1
  description: Generated from Google's published Discovery document for Google Tasks API (tasks v1, revision 20261110). 8 operation(s).
  contact:
    name: Google
    url: https://developers.google.com/
  termsOfService: https://developers.google.com/terms
servers:
- url: https://tasks.googleapis.com
tags:
- name: Tasks
paths:
  /tasks/v1/lists/{tasklist}/tasks/{task}:
    patch:
      operationId: tasks.tasks.patch
      summary: Patch tasks
      description: Updates the specified task. This method supports patch semantics.
      parameters:
      - name: tasklist
        in: path
        required: true
        description: Task list identifier.
        schema:
          type: string
      - name: task
        in: path
        required: true
        description: Task identifier.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Task'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/tasks
      - apiKey: []
      tags:
      - Tasks
    put:
      operationId: tasks.tasks.update
      summary: Update tasks
      description: Updates the specified task.
      parameters:
      - name: tasklist
        in: path
        required: true
        description: Task list identifier.
        schema:
          type: string
      - name: task
        in: path
        required: true
        description: Task identifier.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Task'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/tasks
      - apiKey: []
      tags:
      - Tasks
    delete:
      operationId: tasks.tasks.delete
      summary: Delete tasks
      description: Deletes the specified task from the task list. If the task is assigned, both the assigned task and the original task (in Docs, Chat Spaces) are deleted. To delete the assigned task only, navigate to the assignment surface and unassign the task from there.
      parameters:
      - name: tasklist
        in: path
        required: true
        description: Task list identifier.
        schema:
          type: string
      - name: task
        in: path
        required: true
        description: Task identifier.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/tasks
      - apiKey: []
      tags:
      - Tasks
    get:
      operationId: tasks.tasks.get
      summary: Get tasks
      description: Returns the specified task.
      parameters:
      - name: tasklist
        in: path
        required: true
        description: Task list identifier.
        schema:
          type: string
      - name: task
        in: path
        required: true
        description: Task identifier.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/tasks
        - https://www.googleapis.com/auth/tasks.readonly
      - apiKey: []
      tags:
      - Tasks
  /tasks/v1/lists/{tasklist}/tasks/{task}/move:
    post:
      operationId: tasks.tasks.move
      summary: Move tasks
      description: Moves the specified task to another position in the destination task list. If the destination list is not specified, the task is moved within its current list. This can include putting it as a child task under a new parent and/or move it to a different position among its sibling tasks. A user can have up to 2,000 subtasks per task.
      parameters:
      - name: tasklist
        in: path
        required: true
        description: Task list identifier.
        schema:
          type: string
      - name: task
        in: path
        required: true
        description: Task identifier.
        schema:
          type: string
      - name: destinationTasklist
        in: query
        required: false
        description: Optional. Destination task list identifier. If set, the task is moved from tasklist to the destinationTasklist list. Otherwise the task is moved within its current list.
        schema:
          type: string
      - name: parent
        in: query
        required: false
        description: 'Optional. New parent task identifier. If the task is moved to the top level, this parameter is omitted. The task set as parent must exist in the task list and can not be hidden. Exceptions: 1. Assigned and repeating tasks cannot be set as parent tasks (have subtasks), or be moved under a parent task (become subtasks). 2. Tasks that are both completed and hidden cannot be nested, so the parent field must be empty.'
        schema:
          type: string
      - name: previous
        in: query
        required: false
        description: 'Optional. New previous sibling task identifier. If the task is moved to the first position among its siblings, this parameter is omitted. The task set as previous must exist in the task list and can not be hidden. Exceptions: 1. Tasks that are both completed and hidden can only be moved to position 0, so the previous field must be empty.'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/tasks
      - apiKey: []
      tags:
      - Tasks
  /tasks/v1/lists/{tasklist}/tasks:
    get:
      operationId: tasks.tasks.list
      summary: List tasks
      description: Returns all tasks in the specified task list. Doesn't return assigned tasks by default (from Docs, Chat Spaces). A user can have up to 20,000 non-hidden tasks per list and up to 100,000 tasks in total at a time.
      parameters:
      - name: tasklist
        in: path
        required: true
        description: Task list identifier.
        schema:
          type: string
      - name: completedMax
        in: query
        required: false
        description: Optional. Upper bound for a task's completion date (as a RFC 3339 timestamp) to filter by. The default is not to filter by completion date.
        schema:
          type: string
      - name: completedMin
        in: query
        required: false
        description: Optional. Lower bound for a task's completion date (as a RFC 3339 timestamp) to filter by. The default is not to filter by completion date.
        schema:
          type: string
      - name: dueMax
        in: query
        required: false
        description: Optional. Upper bound for a task's due date (as a RFC 3339 timestamp) to filter by. The default is not to filter by due date.
        schema:
          type: string
      - name: dueMin
        in: query
        required: false
        description: Optional. Lower bound for a task's due date (as a RFC 3339 timestamp) to filter by. The default is not to filter by due date.
        schema:
          type: string
      - name: maxResults
        in: query
        required: false
        description: 'Optional. Maximum number of tasks returned on one page. The default is 20 (max allowed: 100).'
        schema:
          format: int32
          type: integer
      - name: pageToken
        in: query
        required: false
        description: Optional. Token specifying the result page to return.
        schema:
          type: string
      - name: showAssigned
        in: query
        required: false
        description: Optional. Flag indicating whether tasks assigned to the current user are returned in the result. The default is False.
        schema:
          type: boolean
      - name: showCompleted
        in: query
        required: false
        description: Optional. Flag indicating whether completed tasks are returned in the result. Note that showHidden must also be True to show tasks completed in first party clients, such as the web UI and Google's mobile apps. The default is True.
        schema:
          type: boolean
      - name: showDeleted
        in: query
        required: false
        description: Optional. Flag indicating whether deleted tasks are returned in the result. The default is False.
        schema:
          type: boolean
      - name: showHidden
        in: query
        required: false
        description: Optional. Flag indicating whether hidden tasks are returned in the result. The default is False.
        schema:
          type: boolean
      - name: updatedMin
        in: query
        required: false
        description: Optional. Lower bound for a task's last modification time (as a RFC 3339 timestamp) to filter by. The default is not to filter by last modification time.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tasks'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/tasks
        - https://www.googleapis.com/auth/tasks.readonly
      - apiKey: []
      tags:
      - Tasks
    post:
      operationId: tasks.tasks.insert
      summary: Insert tasks
      description: Creates a new task on the specified task list. Tasks assigned from Docs or Chat Spaces cannot be inserted from Tasks Public API; they can only be created by assigning them from Docs or Chat Spaces. A user can have up to 20,000 non-hidden tasks per list and up to 100,000 tasks in total at a time.
      parameters:
      - name: tasklist
        in: path
        required: true
        description: Task list identifier.
        schema:
          type: string
      - name: parent
        in: query
        required: false
        description: Optional. Parent task identifier. If the task is created at the top level, this parameter is omitted. An assigned task cannot be a parent task, nor can it have a parent. Setting the parent to an assigned task results in failure of the request.
        schema:
          type: string
      - name: previous
        in: query
        required: false
        description: Optional. Previous sibling task identifier. If the task is created at the first position among its siblings, this parameter is omitted.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Task'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/tasks
      - apiKey: []
      tags:
      - Tasks
  /tasks/v1/lists/{tasklist}/clear:
    post:
      operationId: tasks.tasks.clear
      summary: Clear tasks
      description: Clears all completed tasks from the specified task list. The affected tasks will be marked as 'hidden' and no longer be returned by default when retrieving all tasks for a task list.
      parameters:
      - name: tasklist
        in: path
        required: true
        description: Task list identifier.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
        4XX:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: 'Client error (google.rpc.Status: INVALID_ARGUMENT, PERMISSION_DENIED, NOT_FOUND ...)'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleRpcError'
          description: Error response (google.rpc.Status)
      security:
      - oauth2:
        - https://www.googleapis.com/auth/tasks
      - apiKey: []
      tags:
      - Tasks
components:
  schemas:
    SpaceInfo:
      description: Information about the Chat Space where a task was assigned from.
      type: object
      properties:
        space:
          type: string
          readOnly: true
          description: Output only. The Chat space where this task originates from. The format is "spaces/{space}".
    AssignmentInfo:
      description: Information about the source of the task assignment (Document, Chat Space).
      type: object
      properties:
        surfaceType:
          description: Output only. The type of surface this assigned task originates from. Currently limited to DOCUMENT or SPACE.
          type: string
          readOnly: true
          enum:
          - CONTEXT_TYPE_UNSPECIFIED
          - GMAIL
          - DOCUMENT
          - SPACE
        spaceInfo:
          $ref: '#/components/schemas/SpaceInfo'
          description: Output only. Information about the Chat Space where this task originates from. This field is read-only.
        linkToTask:
          readOnly: true
          description: Output only. An absolute link to the original task in the surface of assignment (Docs, Chat spaces, etc.).
          type: string
        driveResourceInfo:
          $ref: '#/components/schemas/DriveResourceInfo'
          description: Output only. Information about the Drive file where this task originates from. Currently, the Drive file can only be a document. This field is read-only.
    Tasks:
      type: object
      properties:
        etag:
          type: string
          description: ETag of the resource.
        nextPageToken:
          description: Token used to access the next page of this result.
          type: string
        items:
          items:
            $ref: '#/components/schemas/Task'
          description: Collection of tasks.
          type: array
        kind:
          type: string
          description: Type of the resource. This is always "tasks#tasks".
    DriveResourceInfo:
      description: Information about the Drive resource where a task was assigned from (the document, sheet, etc.).
      type: object
      properties:
        resourceKey:
          description: Output only. Resource key required to access files shared via a shared link. Not required for all files. See also developers.google.com/drive/api/guides/resource-keys.
          type: string
          readOnly: true
        driveFileId:
          type: string
          readOnly: true
          description: Output only. Identifier of the file in the Drive API.
    GoogleRpcError:
      type: object
      description: The error envelope every Google API returns.
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
            status:
              type: string
            details:
              type: array
              items:
                type: object
    Task:
      properties:
        completed:
          type: string
          description: Completion date of the task (as a RFC 3339 timestamp). This field is omitted if the task has not been completed.
        selfLink:
          type: string
          description: Output only. URL pointing to this task. Used to retrieve, update, or delete this task.
          readOnly: true
        id:
          description: Task identifier.
          type: string
        webViewLink:
          type: string
          readOnly: true
          description: Output only. An absolute link to the task in the Google Tasks Web UI.
        parent:
          description: Output only. Parent task identifier. This field is omitted if it is a top-level task. Use the "move" method to move the task under a different parent or to the top level. A parent task can never be an assigned task (from Chat Spaces, Docs). This field is read-only.
          readOnly: true
          type: string
        notes:
          description: 'Notes describing the task. Tasks assigned from Google Docs cannot have notes. Optional. Maximum length allowed: 8192 characters.'
          type: string
        links:
          description: Output only. Collection of links. This collection is read-only.
          type: array
          readOnly: true
          items:
            properties:
              link:
                type: string
                description: The URL.
              description:
                description: The description (might be empty).
                type: string
              type:
                description: Type of the link, e.g. "email", "generic", "chat_message", "keep_note".
                type: string
            type: object
        kind:
          description: Output only. Type of the resource. This is always "tasks#task".
          readOnly: true
          type: string
        status:
          description: Status of the task. This is either "needsAction" or "completed".
          type: string
        etag:
          description: ETag of the resource.
          type: string
        due:
          description: Scheduled date for the task (as an RFC 3339 timestamp). Optional. This represents the day that the task should be done, or that the task is visible on the calendar grid. It doesn't represent the deadline of the task. Only date information is recorded; the time portion of the timestamp is discarded when setting this field. It isn't possible to read or write the time that a task is scheduled for using the API.
          type: string
        updated:
          type: string
          readOnly: true
          description: Output only. Last modification time of the task (as a RFC 3339 timestamp).
        position:
          type: string
          description: Output only. String indicating the position of the task among its sibling tasks under the same parent task or at the top level. If this string is greater than another task's corresponding position string according to lexicographical ordering, the task is positioned after the other task under the same parent task (or at the top level). Use the "move" method to move the task to another position.
          readOnly: true
        hidden:
          description: Flag indicating whether the task is hidden. This is the case if the task had been marked completed when the task list was last cleared. The default is False. This field is read-only.
          type: boolean
        title:
          type: string
          description: 'Title of the task. Maximum length allowed: 1024 characters.'
        deleted:
          description: Flag indicating whether the task has been deleted. For assigned tasks this field is read-only. They can only be deleted by calling tasks.delete, in which case both the assigned task and the original task (in Docs or Chat Spaces) are deleted. To delete the assigned task only, navigate to the assignment surface and unassign the task from there. The default is False.
          type: boolean
        assignmentInfo:
          $ref: '#/components/schemas/AssignmentInfo'
          description: Output only. Context information for assigned tasks. A task can be assigned to a user, currently possible from surfaces like Docs and Chat Spaces. This field is populated for tasks assigned to the current user and identifies where the task was assigned from. This field is read-only.
      type: object
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: key
      description: API key; accepted by methods that do not need user data.
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/tasks.readonly: View your tasks
            https://www.googleapis.com/auth/tasks: Create, edit, organize, and delete all your tasks
externalDocs:
  url: https://developers.google.com/workspace/tasks/
x-provenance:
  method: harvested
  publisher: Google
  source: https://tasks.googleapis.com/$discovery/rest?version=v1
  note: converted by discovery-to-openapi.py from Google's Discovery document (revision 20261110)