openapi: 3.0.3
info:
  title: Ping Task Assistant
  description: A plugin that allows the user to create, delegate and manage tasks using ChatGPT.
  version: 'v1'
servers:
  - url: https://public-api.ping.tm/chatgpt
paths:
  /context:
    get:
      operationId: getContext
      summary: Get user's projects, contacts and tags that can used to recognize project name and assignee while adding a task. You can call it once and remember values for further user input.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getContextResponse'
  /tasks:
    get:
      operationId: getTasks
      summary: Get the list of tasks. Use markdown to bold parameter values. Don't show task IDs because they are for internal use only.
      parameters:
        - in: query
          name: assigneeid
          schema:
            type: string
          required: false
          description: The ID of the assignee to filter tasks.
        - in: query
          name: projectid
          schema:
            type: string
          required: false
          description: The ID of the project to filter tasks.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getTasksResponse'
    post:
      operationId: addTask
      summary: Adds a task. Show all details of the added task as a list of parameters. Use markdown to bold parameter names.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/addTaskRequest'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/task'
  /tasks/delegated:
    post:
      operationId: confirmDelegatedTask
      summary: Confirms a delegated task. Don't list the details of confirmed task because user already seen them.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/addTaskRequest'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/task'
  /projects:
    post:
      operationId: createProject
      summary: Creates a project with specified name.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createProjectRequest'
      responses:
        "200":
          description: Project created successfully.
          content: 
            application/json:
              schema:
                $ref: '#/components/schemas/project'
    put:
      operationId: createProjectFromTask
      summary: Creates a project from a task. User can't create project from a task belonging to other project.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createProjectFromTaskRequest'
      responses:
        "200":
          description: Project created successfully.
        "404":
          description: Task not found
  /tasks/{id}:
    get:
      operationId: getTask
      summary: Gets task parameters.
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: The ID of the task.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/task'
        "404":
          description: Task not found
    put:
      operationId: editTask
      summary: Edits a task.
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: The ID of the task.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/editTaskRequest'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/task'
        "404":
          description: Task not found
    delete:
      operationId: deleteTask
      summary: Delete a recently added task. User can't delete tasks created more than 5 minutes ago.
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: The ID of the task.
      responses:
        "200":
          description: OK
        "400":
          description: Cannot delete task created more than 5 minutes ago.
        "404":
          description: Task not found
  /tasks/{id}/tags/{tagId}:
    put:
      operationId: addTag
      summary: Adds the tag to the task.
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: The ID of the task.
        - in: path
          name: tagId
          schema:
            type: string
          required: true
          description: The ID of the tag.
      responses:
        "200":
          description: OK
        "404":
          description: Task not found
    delete:
      operationId: removeTag
      summary: Removes the tag from the task.
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: The ID of the task.
        - in: path
          name: tagId
          schema:
            type: string
          required: true
          description: The ID of the tag.
      responses:
        "200":
          description: OK
        "404":
          description: Task not found
components:
  schemas:
    getTasksResponse:
      type: object
      properties:
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/task'
        exceededTaskLimit:
          type: boolean
          description: Indicates if the total number of tasks exceeds the limit of 30. User needs to filter by project or assignee to see everything he needs.
    getContextResponse:
      type: object
      properties:
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/assignee'
        projects:
          type: array
          items:
            $ref: '#/components/schemas/project'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/tag'
    addTaskRequest:
      type: object
      required:
        - title
      properties:
        title:
          type: string
          description: The title of the task. Should clearly state what needs to be done.
        description:
          type: string
          description: The description of the task. The more detailed description of what needs to be done.
        tagIds:
          type: array
          description: List of tag ids to be added to the task.
          items:
            type: string
            description: The ID of the tag.
        assigneeId:
          type: string
          description: The ID of the assignee. The assignee of the task. Use users contact list to populate this field. Get users' contacts from getContext function. If nothing matches, set value to null. If there are more than one match, ask user to select one.
        projectTaskId:
          type: string
          description: The ID of the project task. Recognize a project from the user input, even if they don't explicitly state that they want to assign it to a project. Get users' projects from getContext function. Assign a project only if there is a high confidence match. Otherwise set value to null.
        deadline:
          type: string
          format: date
          description: The deadline for the task completion. Deadline has only date part, not time.
        reminder:
          type: string
          format: date-time
          description: The reminder represents the date and time when I want to be reminded about the task.
    createProjectRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: The name of creating project.
    createProjectFromTaskRequest:
      type: object
      required:
        - taskId
      properties:
        taskId:
          type: string
          description: The ID of the task to create project from.
    editTaskRequest:
      type: object
      properties:
        title:
          type: string
          description: The new title of the task.
        description:
          type: string
          description: The new description of the task.
        assigneeId:
          type: string
          description: The ID of the assignee. The assignee of the task. Use users contact list to populate this field. Get users' contacts from getContext function. If nothing matches, set value to null. If there are more than one match, ask user to select one.
        projectTaskId:
          type: string
          description: The ID of the project task. Get users' projects from getContext function. If nothing matches, set value to null.
        deadline:
          type: string
          format: date
          description: The new deadline for the task completion. Deadline has only date part, not time.
        reminder:
          type: string
          format: date-time
          description: The new reminder represents the date and time when user wants to be reminded about the task. Reminder has both date and time. If time is not specified, use only date part.
    project:
      type: object
      properties:
        id:
          type: string
          description: The ID of the project task.
        name:
          type: string
          description: The name of the project task.
      description: The project task to which other tasks can be assigned.
    assignee:
      type: object
      properties:
        id:
          type: string
          description: The ID of the assignee.
        name:
          type: string
          description: The name of the assignee.
      description: The person who can be assigned to a task.
    tag:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          description: The ID of the tag.
        name:
          type: string
          description: The name of the tag.
      description: The tag which can be added to the task.
    task:
      type: object
      description: The task details.
      properties:
        id:
          type: string
          description: The ID of the task. For internal use only.
        url:
          type: string
          description: The URL to the task details. Allows user to open and manage the task within the application.
        title:
          type: string
          description: The title of the task. Display the task title as a link to its details using markdown.
        description:
          type: string
          description: The description of the task.
        tags:
          type: array
          description: Tags added to the task.
          items:
            $ref: '#/components/schemas/tag'
        assignee:
          $ref: '#/components/schemas/assignee'
        project:
          $ref: '#/components/schemas/project'
        deadline:
          type: string
          format: date
          description: The deadline for the task completion.
        reminder:
          type: string
          format: date-time
          description: The reminder represents the date and time when user wants to be reminded about the task.
        isblocked:
          type: boolean
          description: Information on whether this task can be done, or if it is blocked by another task in the project.
        isproject:
          type: boolean
          description: Information on whether this task is a project and if other tasks can be assigned to it. For internal use only.
        createdtime:
          type: string
          format: date-time
          description: The date and time when the task was created. In UTC.