todoist.yaml

openapi: 3.1.0
info:
  title: Todoist_REST_V2
  summary: Todoist for ChatGPT
  description: Todoist REST API v2 for ChatGPT Actions
  termsOfService: https://doist.com/terms-of-service
  contact: 
    name: Todoist Developer
    url: https://developer.todoist.com/
  version: 1.1.0
  x-definition-date: 2023-11-16
  x-definition-author: aaddrick
  x-definition-author-reddit: u/aaddrick
  x-definition-site: https://github.com/aaddrick/GPT-Actions/blob/main/Todoist/REST/V2/README.md

servers: 
  - url: https://api.todoist.com/rest/v2
    description: Todoist REST API v2 server URL
paths:
  /projects:
    get:
      summary: Get all projects
      description: |
        Returns JSON-encoded array containing all user projects.
        
        A successful response has 200 OK status and application/json Content-Type.
      
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/?shell#get-all-projects
      operationId: getAllProjects
      tags:
        - Projects
      security: 
        - api_key: []
      responses: 
        '200':
          description: An array of all projects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
              example: 
                summary: Example response
                value:
                  id: 220474322
                  name: Inbox
                  comment_count: 10
                  order: 0
                  color: grey
                  is_shared: false
                  is_favorite: false
                  is_inbox_project: true
                  is_team_inbox: false
                  view_style: list
                  url: https://todoist.com/showProject?id=220474322
                  parent_id: null
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
    post:
      summary: Create a new project
      x-speakeasy-entity-operation: Project#create
      description: |
        Creates a new project and returns it as a JSON object.

        A successful response has 200 OK status and application/json Content-Type.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#create-a-new-project
      operationId: createProject
      tags:
        - Projects
      security:
        - api_key: []
      parameters:
        - in: query
          name: name
          schema:
            type: string
          required: true
          description: Name of the project
        - in: query
          name: parent_id
          schema:
            type: string
          required: false
          description: Parent project ID
        - in: query
          name: color
          schema:
            type: string
          required: false
          description: The color of the project icon. Refer to the name column in the Colors guide for more info. https://developer.todoist.com/guides/#colors
        - in: query
          name: is_favorite
          schema:
            type: boolean
          required: false
          description: Whether the project is a favorite (a true or false value).
        - in: query
          name: view_style
          schema:
            type: string
          required: false
          description: A string value (either list or board, default is list). This determines the way the project is displayed within the Todoist clients.
      responses:
        '200':
          description: Project created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
              example: 
                summary: Example response
                value:
                  id: 2203306141
                  name: Shopping List
                  comment_count: 0
                  color: charcoal
                  is_shared: false
                  order: 1
                  is_favorite: true
                  is_inbox_project: true
                  is_team_inbox: false
                  view_style: list
                  url: https://todoist.com/showProject?id=2203306141
                  parent_id: null
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'

  /projects/{projectId}:
    get:
      summary: Get a project
      x-speakeasy-entity-operation: Project#read
      description: |
        Returns a JSON object containing a project object related to the given ID.

        A successful response has 200 OK status and application/json Content-Type.
      
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/?shell#get-a-project
      operationId: getProject
      tags:
        - Projects
      security: 
        - api_key: []
      parameters:
        - in: path
          name: projectId
          x-speakeasy-match: id
          schema:
            type: string
          required: true
          description: Project ID.
      responses: 
        '200':
          description: Requested project returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'                  
              example: 
                summary: Example response
                value:
                  id: 2203306141
                  name: Shopping List
                  comment_count: 0
                  color: charcoal
                  is_shared: false
                  order: 1
                  is_favorite: true
                  is_inbox_project: true
                  is_team_inbox: false
                  view_style: list
                  url: https://todoist.com/showProject?id=2203306141
                  parent_id: null
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
    post:
      summary: Update a project
      x-speakeasy-entity-operation: Project#update
      description: |
        Returns a JSON object containing the updated project object.

        A successful response has 200 OK status and application/json Content-Type.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/?shell#update-a-project
      operationId: updateProject
      tags:
        - Projects
      security:
        - api_key: []
      parameters:
        - in: path
          name: projectId
          x-speakeasy-match: id
          schema:
            type: string
          required: true
          description: Project ID.
        - in: query
          name: name
          schema:
            type: string
          required: false
          description: Name of the project
        - in: query
          name: color
          schema:
            type: string
          required: false
          description: The color of the project icon. Refer to the name column in the Colors guide for more info. https://developer.todoist.com/guides/#colors
        - in: query
          name: is_favorite
          schema:
            type: boolean
          required: false
          description: Whether the project is a favorite (a true or false value).
        - in: query
          name: view_style
          schema:
            type: string
          required: false
          description: A string value (either list or board, default is list). This determines the way the project is displayed within the Todoist clients.
      responses:
        '200':
          description: Project updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
              example: 
                summary: Example response
                value:
                  id: 2203306141
                  name: Things to buy
                  comment_count: 0
                  color: charcoal
                  is_shared: false
                  order: 1
                  is_favorite: true
                  is_inbox_project: true
                  is_team_inbox: false
                  view_style: list
                  url: https://todoist.com/showProject?id=2203306141
                  parent_id: null
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
    delete: 
      summary: Delete a project
      x-speakeasy-entity-operation: Project#delete
      description: |
        Deletes a project.

        A successful response has 204 No Content status and an empty body.
      
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/?shell#delete-a-project
      operationId: deleteProject
      tags:
        - Projects
      security: 
        - api_key: []
      parameters:
        - in: path
          name: projectId
          x-speakeasy-match: id
          schema:
            type: string
          required: true
          description: Project ID.
      responses: 
        '204':
          description: Project deleted.
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'

  /projects/{projectId}/collaborators:
    get:
      summary: Get all project collaborators
      description: |
        Returns JSON-encoded array containing all collaborators of a shared project.

        A successful response has 200 OK status and application/json Content-Type.
      
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/?shell#get-all-collaborators
      operationId: getAllCollaborators
      tags:
        - Projects
      security: 
        - api_key: []
      parameters:
          - in: path
            name: projectId
            schema:
              type: string
            required: true
            description: Project ID.
      responses: 
        '200':
          description: A list of collaborators.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Collaborator'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'

  /sections:
    get:
      summary: Get all sections
      description: |
        Returns a JSON array of all sections.

        A successful response has 200 OK status and application/json Content-Type.
      
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#get-all-sections
      operationId: getAllSections
      tags:
        - Sections
      security: 
        - api_key: []
      parameters:
          - in: query
            name: project_id
            schema:
              type: string
            required: false
            description: Project ID.
      responses: 
        '200':
          description: An array of all sections.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Section'
              example: 
                summary: Example response
                value:
                  id: 7025
                  project_id: 2203306141
                  order: 1
                  name: Groceries
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
                
    post:
      summary: Create a new section
      description: |
        Creates a new section and returns it as a JSON object.

        A successful response has 200 OK status and application/json Content-Type.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#create-a-new-section
      operationId: createSection
      tags:
        - Sections
      security:
        - api_key: []
      parameters:
        - in: query
          name: project_id
          schema:
            type: string
          required: true
          description: Project ID this section should belong to
        - in: query
          name: name
          schema:
            type: string
          required: true
          description: Section name
        - in: query
          name: order
          schema:
            type: integer
          required: false
          description: Order among other sections in a project
      responses:
        '200':
          description: Section created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Section'
              example: 
                summary: Example response
                value:
                  id: 7025
                  project_id: 2203306141
                  order: 1
                  name: Groceries
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
  
  /sections/{sectionId}:
    get:
      summary: Get single section
      description: |
        Returns a single section as a JSON object.

        A successful response has 200 OK status and application/json Content-Type.
      
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#get-a-single-section
      operationId: getSingleSection
      tags:
        - Sections
      security: 
        - api_key: []
      parameters:
          - in: path
            name: sectionId
            schema:
              type: string
            required: true
            description: Section ID.
      responses: 
        '200':
          description: Section retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Section'
              example: 
                summary: Example response
                value:
                  id: 7025
                  project_id: 2203306141
                  order: 1
                  name: Groceries
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
    post:
      summary: Update a section name
      description: |
        Returns the updated section as a JSON object.

        A successful response has 200 OK status and application/json Content-Type.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#update-a-section
      operationId: updateSection
      tags:
        - Sections
      security: 
        - api_key: []
      parameters:
          - in: path
            name: sectionId
            schema:
              type: string
            required: true
            description: Section ID.
          - in: query
            name: name
            schema:
              type: string
            required: true
            description: Section name.
      responses: 
        '200':
          description: Section name updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Section'
              example: 
                summary: Example response
                value:
                  id: 7025
                  project_id: 2203306141
                  order: 1
                  name: Supermarket
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
    delete: 
        summary: Delete a section
        description: |
          Deletes a section.

          A successful response has 204 No Content status and an empty body.
        
        externalDocs: 
          description: Documentation at link below
          url: https://developer.todoist.com/rest/v2/#delete-a-section
        operationId: deleteSection
        tags:
          - Sections
        security: 
          - api_key: []
        parameters:
          - in: path
            name: sectionId
            schema:
              type: string
            required: true
            description: Section ID.
        responses: 
          '204':
            description: Section deleted.
          default:
            description: Unexpected error
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/ErrorModel'
    
  /tasks:
    get:
      summary: Get active tasks
      description: |
        Returns a JSON-encoded array containing all active tasks.

        A successful response has 200 OK status and application/json Content-Type.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#get-active-tasks
      operationId: getActiveTasks
      tags:
        - Tasks
      security:
        - api_key: []
      parameters:
        - in: query
          name: project_id
          schema:
            type: string
          required: false
          description: Filter tasks by project ID.
        - in: query
          name: section_id
          schema:
            type: string
          required: false
          description: Filter tasks by section ID.
        - in: query
          name: label
          schema:
            type: string
          required: false
          description: Filter tasks by label name.
        - in: query
          name: filter
          schema:
            type: string
          required: false
          description: Filter by any supported filter.
        - in: query
          name: lang
          schema:
            type: string
          required: false
          description: IETF language tag defining what language the filter is written in, if it differs from the default English.
        - in: query
          name: ids
          schema:
            type: array
            items:
              type: integer
          required: false
          description: A list of the task IDs to retrieve, this should be a comma-separated list.
      responses:
        '200':
          description: List of active tasks.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
              example: 
                summary: Example response
                value: 
                  - creator_id: "2671355"
                    created_at: "2019-12-11T22:36:50.000000Z"
                    assignee_id: "2671362"
                    assigner_id: "2671355"
                    comment_count: 10
                    is_completed: false
                    content: "Buy Milk"
                    description: ""
                    due: 
                      date: "2016-09-01"
                      is_recurring: false
                      datetime: "2016-09-01T12:00:00.000000Z"
                      string: "tomorrow at 12"
                      timezone: "Europe/Moscow"
                    duration: null
                    id: "2995104339"
                    labels: ["Food", "Shopping"]
                    order: 1
                    priority: 1
                    project_id: "2203306141"
                    section_id: "7025"
                    parent_id: "2995104589"
                    url: "https://todoist.com/showTask?id=2995104339"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
    post:
      x-speakeasy-entity-operation: Task#create
      summary: Create a new task
      description: |
        Creates a new task and returns it as a JSON object.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#create-a-new-task
      operationId: createTask
      tags:
        - Tasks
      security:
        - api_key: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              x-speakeasy-entity: Task
              properties:
                content:
                  type: string
                  description: Task content. This value may contain markdown-formatted text and hyperlinks.
                description:
                  type: string
                  description: A description for the task. This value may contain markdown-formatted text and hyperlinks.
                project_id:
                  type: string
                  description: Task project ID. If not set, the task is put in the user's Inbox.
                section_id:
                  type: string
                  description: ID of the section to put the task into.
                parent_id:
                  type: string
                  description: Parent task ID.
                order:
                  type: integer
                  description: Non-zero integer value used by clients to sort tasks under the same parent.
                labels:
                  type: array
                  items:
                    type: string
                  description: The task's labels (a list of names that may represent either personal or shared labels).
                priority:
                  type: integer
                  description: Task priority from 1 (normal) to 4 (urgent).
                due_string:
                  type: string
                  description: Human-defined task due date (ex. "next Monday," "Tomorrow"). Value is set using local (not UTC) time.
                due_date:
                  type: string
                  description: Specific date in YYYY-MM-DD format relative to the user's timezone.
                due_datetime:
                  type: string
                  description: Specific date and time in RFC3339 format in UTC.
                due_lang:
                  type: string
                  description: 2-letter code specifying the language in case due_string is not written in English.
                assignee_id:
                  type: string
                  description: The responsible user ID (only applies to shared tasks).
                duration:
                  type: integer
                  x-speakeasy-name-override: duration_amount
                  description: A positive (greater than zero) integer for the amount of duration_unit the task will take. If specified, you must define a duration_unit.
                duration_unit:
                  type: string
                  description: The unit of time that the duration field above represents. Must be either minute or day. If specified, duration must be defined as well.
            example:
              content: "Buy Milk"
              description: "Milk to be bought from local store"
              project_id: "2203306141"
              labels: ["Shopping", "Urgent"]
              priority: 4
              due_string: "tomorrow at 12"
      responses:
        '200':
          description: Task created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
              example: 
                creator_id: "2671355"
                created_at: "2019-12-11T22:36:50.000000Z"
                assignee_id: null
                assigner_id: null
                comment_count: 0
                is_completed: false
                content: "Buy Milk"
                description: ""
                due: 
                  date: "2016-09-01"
                  is_recurring: false
                  datetime: "2016-09-01T12:00:00.000000Z"
                  string: "tomorrow at 12"
                  timezone: "Europe/Moscow"
                duration: null
                id: "2995104339"
                labels: []
                order: 1
                priority: 4
                project_id: "2203306141"
                section_id: null
                parent_id: null
                url: "https://todoist.com/showTask?id=2995104339"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'

  /tasks/{taskId}:
    get:
      summary: Get an active task
      x-speakeasy-entity-operation: Task#read
      description: |
        Returns a single active (non-completed) task by ID as a JSON object.

        A successful response has 200 OK status and application/json Content-Type.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#get-an-active-task
      operationId: getActiveTask
      tags:
        - Tasks
      security:
        - api_key: []
      parameters:
        - in: path
          name: taskId
          x-speakeasy-match: id
          schema:
            type: string
          required: true
          description: The ID of the task to retrieve.
      responses:
        '200':
          description: Task details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
              example: 
                summary: Example response
                value:
                  creator_id: "2671355"
                  created_at: "2019-12-11T22:36:50.000000Z"
                  assignee_id: "2671362"
                  assigner_id: "2671355"
                  comment_count: 10
                  is_completed: false
                  content: "Buy Milk"
                  description: ""
                  due: 
                    date: "2016-09-01"
                    is_recurring: false
                    datetime: "2016-09-01T12:00:00.000000Z"
                    string: "tomorrow at 12"
                    timezone: "Europe/Moscow"
                  duration: null
                  id: "2995104339"
                  labels: ["Food", "Shopping"]
                  order: 1
                  priority: 1
                  project_id: "2203306141"
                  section_id: "7025"
                  parent_id: "2995104589"
                  url: "https://todoist.com/showTask?id=2995104339"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
    post:
      x-speakeasy-entity-operation: Task#update
      summary: Update a task
      description: |
        Updates a specified task and returns it as a JSON object.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#update-a-task
      operationId: updateTask
      tags:
        - Tasks
      security:
        - api_key: []
      parameters:
        - in: path
          name: taskId
          required: true
          x-speakeasy-match: id
          description: The ID of the task to update.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  description: Task content. This value may contain markdown-formatted text and hyperlinks.
                description:
                  type: string
                  description: A description for the task. This value may contain markdown-formatted text and hyperlinks.
                labels:
                  type: array
                  items:
                    type: string
                  description: The task's labels (a list of names that may represent either personal or shared labels).
                priority:
                  type: integer
                  description: Task priority from 1 (normal) to 4 (urgent).
                due_string:
                  type: string
                  description: Human-defined task due date (ex. "next Monday," "Tomorrow"). Value is set using local (not UTC) time.
                due_date:
                  type: string
                  description: Specific date in YYYY-MM-DD format relative to the user's timezone.
                due_datetime:
                  type: string
                  description: Specific date and time in RFC3339 format in UTC.
                due_lang:
                  type: string
                  description: 2-letter code specifying the language in case due_string is not written in English.
                assignee_id:
                  type: string
                  description: The responsible user ID or null to unset (for shared tasks).
                duration:
                  type: integer
                  x-speakeasy-name-override: duration_amount
                  description: A positive integer for the task duration, or null to unset. If specified, you must define a duration_unit.
                duration_unit:
                  type: string
                  description: The unit of time for the duration. Must be either 'minute' or 'day'.
            example:
              content: "Buy Coffee"
              description: "Coffee needed for the office"
              labels: ["Office", "Urgent"]
              priority: 2
              due_string: "tomorrow at 9 AM"
      responses:
        '200':
          description: Task updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
              example: 
                creator_id: "2671355"
                created_at: "2019-12-11T22:36:50.000000Z"
                assignee_id: "2671362"
                assigner_id: "2671355"
                comment_count: 10
                is_completed: false
                content: "Buy Coffee"
                description: ""
                due: 
                  date: "2016-09-01"
                  is_recurring: false
                  datetime: "2016-09-01T12:00:00.000000Z"
                  string: "tomorrow at 12"
                  timezone: "Europe/Moscow"
                duration: null
                id: "2995104339"
                labels: ["Food", "Shopping"]
                order: 1
                priority: 1
                project_id: "2203306141"
                section_id: "7025"
                parent_id: "2995104589"
                url: "https://todoist.com/showTask?id=2995104339"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'

    delete:
      summary: Delete a task
      x-speakeasy-entity-operation: Task#delete
      description: |
        Deletes a task. 

        A successful response has 204 No Content status and an empty body.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#delete-a-task
      operationId: deleteTask
      tags:
        - Tasks
      security:
        - api_key: []
      parameters:
        - in: path
          name: taskId
          x-speakeasy-match: id
          schema:
            type: string
          required: true
          description: The ID of the task to delete.
      responses:
        '204':
          description: Task successfully deleted. The response is empty.
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'


  /tasks/{taskId}/close:
    post:
      summary: Close a task
      description: |
        Closes a task. Regular tasks are marked complete and moved to history, along with their subtasks. Tasks with recurring due dates will be scheduled to their next occurrence.

        A successful response has 204 No Content status and an empty body.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#close-a-task
      operationId: closeTask
      tags:
        - Tasks
      security:
        - api_key: []
      parameters:
        - in: path
          name: taskId
          schema:
            type: integer
          required: true
          description: The ID of the task to close.
      responses:
        '204':
          description: Task successfully closed. The response is empty.
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
  /tasks/{taskId}/reopen:
    post:
      summary: Reopen a task
      description: |
        Reopens a task. Any ancestor items or sections will also be marked as uncomplete and restored from history. The reinstated items and sections will appear at the end of the list within their parent, after any previously active items.

        A successful response has 204 No Content status...
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#reopen-a-task
      operationId: reopenTask
      tags:
        - Tasks
      security:
        - api_key: []
      parameters:
        - in: path
          name: taskId
          schema:
            type: integer
          required: true
          description: The ID of the task to reopen.
      responses:
        '204':
          description: Task successfully reopened. The response is empty.
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'

  /comments:
    get:
      summary: Get all comments
      description: |
        Returns a JSON-encoded array of all comments for a given task_id or project_id. Note that one of task_id or project_id arguments is required.

        A successful response has 200 OK status and application/json Content-Type.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#get-all-comments
      operationId: getAllComments
      tags:
        - Comments
      security:
        - api_key: []
      parameters:
        - in: query
          name: project_id
          schema:
            type: string
          required: false
          description: ID of the project used to filter comments. task_id or project_id required
        - in: query
          name: task_id
          schema:
            type: string
          required: false
          description: ID of the task used to filter comments. task_id or project_id required
      responses:
        '200':
          description: List of all comments.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Comment'
              example: 
                summary: Example response
                value: 
                  - content: "Need one bottle of milk"
                    id: "2992679862"
                    posted_at: "2016-09-22T07:00:00.000000Z"
                    project_id: null
                    task_id: "2995104339"
                    attachment:
                      file_name: "File.pdf"
                      file_type: "application/pdf"
                      file_url: "https://cdn-domain.tld/path/to/file.pdf"
                      resource_type: "file"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
    post:
      summary: Create a new comment
      description: |
        Creates a new comment on a project or task and returns it as a JSON object. Note that one of task_id or project_id arguments is required.

        A successful response has 200 OK status and application/json Content-Type.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#create-a-new-comment
      operationId: createComment
      tags:
        - Comments
      security:
        - api_key: []
      parameters:
        - in: query
          name: task_id
          required: false
          description: Comment's task ID (for task comments). task_id or project_id required
          schema:
            type: string
        - in: query
          name: project_id
          required: false
          description: Comment's project ID (for project comments). task_id or project_id required
          schema:
            type: string
        - in: query
          name: content
          required: true
          description: Comment content. This value may contain markdown-formatted text and hyperlinks.
          schema:
            type: string
        - in: query
          name: attachment
          required: false
          description: Object for attachment object.
          schema:
            type: object
            properties:
              resource_type:
                type: string
              file_url:
                type: string
              file_type:
                type: string
              file_name:
                type: string

      responses:
        '200':
          description: Comment created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
              example: 
                summary: Example response
                value:
                  content: "Need one bottle of milk"
                  id: "2992679862"
                  posted_at: "2016-09-22T07:00:00.000000Z"
                  project_id: null
                  task_id: "2995104339"
                  attachment: 
                    file_name: "File.pdf"
                    file_type: "application/pdf"
                    file_url: "https://s3.amazonaws.com/domorebetter/Todoist+Setup+Guide.pdf"
                    resource_type: "file"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'

  /comments/{comment_id}:
    get:
      summary: Get a comment
      description: |
        Returns a single comment as a JSON object.

        A successful response has 200 OK status and application/json Content-Type.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#get-a-comment
      operationId: getComment
      tags:
        - Comments
      security:
        - api_key: []
      parameters:
        - in: path
          name: comment_id
          schema:
            type: integer
          required: true
          description: The ID of the comment to retrieve.
      responses:
        '200':
          description: Comment details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
              example: 
                summary: Example response
                value:
                  content: "Need one bottle of milk"
                  id: "2992679862"
                  posted_at: "2016-09-22T07:00:00.000000Z"
                  project_id: null
                  task_id: "2995104339"
                  attachment:
                    file_name: "File.pdf"
                    file_type: "application/pdf"
                    file_url: "https://s3.amazonaws.com/domorebetter/Todoist+Setup+Guide.pdf"
                    resource_type: "file"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
    post:
      summary: Update a comment
      description: |
        Updates a comment and returns it as a JSON object.

        A successful response has 200 OK status and application/json Content-Type.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#update-a-comment
      operationId: updateComment
      tags:
        - Comments
      security:
        - api_key: []
      parameters:
        - in: path
          name: comment_id
          required: true
          description: The ID of the comment to update.
          schema:
            type: string
        - in: query
          name: content
          required: true
          description: New content for the comment. This value may contain markdown-formatted text and hyperlinks.
          schema:
            type: string
      responses:
        '200':
          description: Comment updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
              example: 
                summary: Example response
                value:
                  content: "Need two bottles of milk"
                  id: "2992679862"
                  posted_at: "2016-09-22T07:00:00.000000Z"
                  project_id: null
                  task_id: "2995104339"
                  attachment:
                    file_name: "File.pdf"
                    file_type: "application/pdf"
                    file_url: "https://s3.amazonaws.com/domorebetter/Todoist+Setup+Guide.pdf"
                    resource_type: "file"
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
    delete:
      summary: Delete a comment
      description: |
        Deletes a comment.

        A successful response has 204 No Content status and an empty body.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#delete-a-comment
      operationId: deleteComment
      tags:
        - Comments
      security:
        - api_key: []
      parameters:
        - in: path
          name: comment_id
          schema:
            type: integer
          required: true
          description: The ID of the comment to delete.
      responses:
        '204':
          description: Comment successfully deleted. The response is empty.
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'

  /labels:
    get:
      summary: Get all personal labels
      description: |
        Returns a JSON-encoded array containing all user labels.

        A successful response has 200 OK status and application/json Content-Type.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#get-all-personal-labels
      operationId: getAllPersonalLabels
      tags:
        - Labels
      security:
        - api_key: []
      responses:
        '200':
          description: List of all user labels.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Label'
              example: 
                summary: Example response
                value: 
                  - id: "2156154810"
                    name: "Food"
                    color: "charcoal"
                    order: 1
                    is_favorite: false
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
    post:
      summary: Create a new personal label
      description: |
        Creates a new personal label and returns its object as JSON.

        A successful response has 200 OK status and application/json Content-Type.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#create-a-new-personal-label
      operationId: createPersonalLabel
      tags:
        - Labels
      security:
        - api_key: []
      parameters:
        - in: query
          name: name
          required: true
          description: Name of the label.
          schema:
            type: string
        - in: query
          name: order
          required: false
          description: Label order.
          schema:
            type: integer
        - in: query
          name: color
          required: false
          description: The color of the label icon. Refer to the name column in the Colors guide for more info.
          schema:
            type: string
        - in: query
          name: is_favorite
          required: false
          description: Whether the label is a favorite (a true or false value).
          schema:
            type: boolean
      responses:
        '200':
          description: Label created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
              example: 
                summary: Example response
                value:
                  id: "2156154810"
                  name: "Food"
                  color: "charcoal"
                  order: 1
                  is_favorite: false
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'

  /labels/{label_id}:
    get:
      summary: Get a personal label
      description: |
        Returns a personal label by ID.

        A successful response has 200 OK status and application/json Content-Type.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#get-a-personal-label
      operationId: getPersonalLabel
      tags:
        - Labels
      security:
        - api_key: []
      parameters:
        - in: path
          name: label_id
          schema:
            type: integer
          required: true
          description: The ID of the label to retrieve.
      responses:
        '200':
          description: Label details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
              example: 
                summary: Example response
                value:
                  id: "2156154810"
                  name: "Food"
                  color: "charcoal"
                  order: 1
                  is_favorite: false
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
    post:
      summary: Update a personal label
      description: |
        Returns the updated label.

        A successful response has 200 OK status and application/json Content-Type.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#update-a-personal-label
      operationId: updatePersonalLabel
      tags:
        - Labels
      security:
        - api_key: []
      parameters:
        - in: path
          name: label_id
          required: true
          description: The ID of the label to update.
          schema:
            type: string
        - in: query
          name: name
          required: false
          description: New name of the label.
          schema:
            type: string
        - in: query
          name: order
          required: false
          description: Number that is used by clients to sort the list of labels.
          schema:
            type: integer
        - in: query
          name: color
          required: false
          description: The color of the label icon. Refer to the name column in the Colors guide for more info.
          schema:
            type: string
        - in: query
          name: is_favorite
          required: false
          description: Whether the label is a favorite (a true or false value).
          schema:
            type: boolean
      responses:
        '200':
          description: Label updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Label'
              example: 
                summary: Example response
                value:
                  id: "2156154810"
                  name: "Drinks"
                  color: "charcoal"
                  order: 1
                  is_favorite: false
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
    delete:
      summary: Delete a personal label
      description: |
        Deletes a personal label, all instances of the label will be removed from tasks.

        A successful response has 204 No Content status and an empty body.
      externalDocs: 
        description: Documentation at link below
        url: https://developer.todoist.com/rest/v2/#delete-a-personal-label
      operationId: deletePersonalLabel
      tags:
        - Labels
      security:
        - api_key: []
      parameters:
        - in: path
          name: label_id
          schema:
            type: integer
          required: true
          description: The ID of the label to delete.
      responses:
        '204':
          description: Label successfully deleted. The response is empty.
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorModel'

components:
  schemas:
    Project:
      type: object
      x-speakeasy-entity: Project
      properties:
        id:
          type: string
          description: Project ID.
        name:
          type: string
          description: Project name.
        color:
          type: string
          description: The color of the project icon. Refer to the name column in the Colors guide for more info.
        parent_id:
          type: 
            - string
            - 'null'
          description: ID of parent project (will be null for top-level projects).
        order:
          type: integer
          description: Project position under the same parent (read-only, will be 0 for inbox and team inbox projects).
        comment_count:
          type: integer
          description: Number of project comments.
        is_shared:
          type: boolean
          description: Whether the project is shared (read-only, a true or false value).
        is_favorite:
          type: boolean
          description: Whether the project is a favorite (a true or false value).
        is_inbox_project:
          type: boolean
          description: Whether the project is the user's Inbox (read-only).
        is_team_inbox:
          type: boolean
          description: Whether the project is the Team Inbox (read-only).
        view_style:
          type: string
          description: A string value (either list or board). This determines the way the project is displayed within the Todoist clients.
        url:
          type: string
          description: URL to access this project in the Todoist web or mobile applications. 

    Collaborator:
      type: object
      properties:
        id:
          type: string
          description: Collaborator's user ID
        name:
          type: string
          description: Collaborator's name
        email:
          type: string
          description: Collaborator's email

    Section:
      type: object
      properties:
        id:
          type: string
          description: Section ID
        project_id:
          type: string
          description: ID of the project section belongs to
        order:
          type: integer
          description: Section position among other sections from the same project
        name:
          type: string
          description: Section name

    Task:
      type: object
      x-speakeasy-entity: Task
      properties:
        id:
          type: string
          description: Task ID.
        project_id:
          type: string
          description: Task's project ID (read-only).
        section_id:
          type: 
            - string
            - 'null'
          description: ID of section task belongs to (read-only, will be null when the task has no parent section).
        content:
          type: string
          description: Task content. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the Text Formatting article in the Help Center.
        description:
          type: string
          description: A description for the task. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the Text Formatting article in the Help Center.
        is_completed:
          type: boolean
          description: Flag to mark completed tasks.
        labels:
          type: array
          items:
            type: string
            description: The task's labels (a list of names that may represent either personal or shared labels).
        parent_id:
          type: 
            - string
            - 'null'
          description: ID of parent task (read-only, will be null for top-level tasks).
        order:
          type: integer
          description: Position under the same parent or project for top-level tasks (read-only).
        priority:
          type: integer
          description: Task priority from 1 (normal, default value) to 4 (urgent).
        due:
          type: 
            - object
            - 'null'
          properties:
            dueObject:
              $ref: '#/components/schemas/Due'
          description: Object representing task due date/time, or null if no date is set.
        url:
          type: string
          description: URL to access this task in the Todoist web or mobile applications (read-only).
        comment_count:
          type: integer
          description: Number of task comments (read-only).
        created_at:
          type: string
          description: The date when the task was created (read-only).
        creator_id:
          type: string
          description: The ID of the user who created the task (read-only).
        assignee_id:
          type: 
            - string
            - 'null'
          description: The responsible user ID (will be null if the task is unassigned).
        assigner_id:
          type: 
            - string
            - 'null'
          description: The ID of the user who assigned the task (read-only, will be null if the task is unassigned).
        duration:
          type: 
            - object
            - 'null'
          properties:
            durationObject:
              $ref: '#/components/schemas/Duration'
          description: Object representing a task's duration, including a positive integer for the amount of time and the unit of time (minute or day). The object will be null if the task has no duration.

    Due:
      type: object
      required:
      - string
      - date
      - is_recurring
      properties:
        string:
          type: string
          description: Human defined date in arbitrary format.
        date:
          type: string
          format: date
          description: Date in format YYYY-MM-DD corrected to user's timezone.
        is_recurring:
          type: boolean
          description: Whether the task has a recurring due date.
        datetime:
          type: string
          format: date-time
          description: Only returned if exact due time set (i.e. it's not a whole-day task), date and time in RFC3339 format in UTC.
        timezone:
          type: string
          description: Only returned if exact due time set, user's timezone definition either in tzdata-compatible format ("Europe/Berlin") or as a string specifying east of UTC offset as "UTC±HH:MM" (i.e. "UTC-01:00").

    Duration:
      type: object
      properties:
        amount:
          type: 
            - integer
            - 'null'
          description: A positive (greater than zero) integer for the amount of duration_unit the task will take, or null to unset. If specified, you must define a duration_unit.
        unit: 
          type: 
            - string
            - 'null'
          description: The unit of time that the duration field above represents, or null to unset. Must be either minute or day. If specified, duration must be defined as well.

    Comment:
      type: object
      properties:
        id:
          type: string
          description: Comment ID.
        task_id:
          type: 
            - string
            - 'null'
          description: Comment's task ID (will be null if the comment belongs to a project).
        project_id:
          type: 
            - string
            - 'null'
          description: Comment's project ID (will be null if the comment belongs to a task).
        posted_at:
          type: string
          format: date-time
          description: Date and time when comment was added, in RFC3339 format in UTC.
        content:
          type: string
          description: Comment content. This value may contain markdown-formatted text and hyperlinks. Details on markdown support can be found in the Text Formatting article in the Help Center.
        attachment:
          type: 
            - object
            - 'null'
          description: Attachment file metadata (will be null if there is no attachment). Format varies depending on the type of attachment, as detailed in the Sync API documentation.
      
    Label:
      type: object
      properties:
        id:
          type: string
          description: Label ID.
        name:
          type: string
          description: Label name.
        color:
          type: string
          description: The color of the label icon. Refer to the name column in the Colors guide for more info.
        order:
          type: integer
          description: Number used by clients to sort list of labels.
        is_favorite:
          type: boolean
          description: Whether the label is a favorite (a true or false value).

        
    ErrorModel:
      type: object
      required:
      - message
      - code
      properties:
        message:
          type: string
        code:
          type: integer
          minimum: 100
          maximum: 600
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
      bearerFormat: JWT