Height Tasks API

openapi: 3.0.3
info:
  title: Height APP Activities Tasks API
  description: "Unofficial Open API 3.1 specification for [Height App API](https://www.notion.so/API-documentation-643aea5bf01742de9232e5971cb4afda). This is not affiliated with Height team.\n\n---\n# Authentication\n\nThe Height API uses API keys to authenticate requests. **You can view your API key in the Height settings under API**.\n\nAuthentication to the API is performed via the `Authorization` header. All API requests should be made over HTTPs.\n\ni.e. Get your workspace.\n\n```bash\ncurl https://api.height.app/workspace \\\n  -H \"Authorization: api-key secret_1234\"\n```\n\nThird-party applications must connect to the Height API using [OAuth2](https://www.notion.so/API-documentation-643aea5bf01742de9232e5971cb4afda). \n\nSee [OAuth Apps on Height](https://www.notion.so/OAuth-Apps-on-Height-a8ebeab3f3f047e3857bd8ce60c2f640) for more information.\n\n# Object formats\n\nAll objects have a unique `id` ([UUID v4](https://en.m.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random))) and a `model` attribute to distinguish the model type.\n\ne.g. a task object.\n\n```json\n{\n  \"id\": \"123e4567-e89b-12d3-a456-426655440000\",\n  \"model\": \"task\",\n  \"name\": \"Fix bug\",\n  \"index\": 1,\n  \"status\": \"backLog\",\n  [...]\n}\n```\n\n# Date formats\n\nEvery date uses the ISO format e.g.\n\n```js\n\"2019-11-07T17:00:00.000Z\"\n```\n\n# Real-time\n\nAny change that you make to the API will be pushed to every user in real-time: i.e. creating tasks or messages.\n\n# Rate limits\n\nTo keep incoming traffic under control and maintain a great experience for all our users, our API is behind a rate limiter. Users who send many requests in quick succession may see error responses that show up as status code 429.\n\nHeight allows up to 120 requests/min, but we have stricter limits on these endpoints:\n\n- `POST /activities`: 60 requests/min\n- `POST /tasks`: 60 requests/min"
  contact:
    email: gil@beomjun.kr
  license:
    name: MIT
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
- url: https://api.height.app
security:
- apiKey: []
tags:
- name: Tasks
paths:
  /tasks:
    post:
      tags:
      - Tasks
      summary: Create a task
      operationId: createTask
      x-codeSamples:
      - lang: JavaScript
        label: SDK
        source: 'const height = new Height({secretKey: ''secret_your-key''});


          height.tasks.create({...});'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
        required: true
      responses:
        '201':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskObject'
      parameters:
      - name: realtime
        in: query
        description: (defaults to true) - use false when migrating tasks
        schema:
          type: boolean
      - name: notifyUsers
        in: query
        description: (defaults to true) - use false when migrating tasks
        schema:
          type: boolean
    patch:
      tags:
      - Tasks
      summary: Patch multiples tasks
      operationId: patchTasks
      x-codeSamples:
      - lang: JavaScript
        label: SDK
        source: 'const height = new Height({secretKey: ''secret_your-key''});


          height.tasks.patch({...});'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchTasksRequest'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PatchTasksResponse'
    get:
      tags:
      - Tasks
      summary: Search tasks
      operationId: searchTasks
      x-codeSamples:
      - lang: JavaScript
        label: SDK
        source: 'const height = new Height({secretKey: ''secret_your-key''});


          const request: SearchTasksRequest = {};

          height.tasks.search(request);'
      parameters:
      - name: filters
        in: query
        description: JSON object with filters
        example: '{"status":{"values":["backLog","inProgress"]},"assigneeId":{"values":["123e4567-e89b-12d3-a456-426655440000"]},"completed":{"values":[false]},"lastActivityAt":{"values":[],"gt":{"date":"2019-11-07T17:00:00.000Z"}}}'
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchTasksResponse'
  /tasks/:id:
    get:
      tags:
      - Tasks
      summary: Get a task
      operationId: getTask
      x-codeSamples:
      - lang: JavaScript
        label: SDK
        source: 'const height = new Height({secretKey: ''secret_your-key''});


          height.tasks.get({...});'
      parameters:
      - name: id
        in: path
        description: task index (number) or task id (UUID)
        required: true
        schema:
          type: string
          format: uuid
      - name: include
        in: query
        description: What you wish to include with the task.
        schema:
          type: string
          enum:
          - Assignees
          - CreatedByUser
          - CompletedByUser
          - DeletedByUser
          - Subscribers
          - Fields.User
          - Lists
          - Status
          - Mentions
          - NotificationsSubscription
          - ParentTasks
          - SubtaskIds
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskObject'
    patch:
      tags:
      - Tasks
      summary: Update a single task
      operationId: updateTask
      x-codeSamples:
      - lang: JavaScript
        label: SDK
        source: 'const height = new Height({secretKey: ''secret_your-key''});


          height.tasks.update({...});'
      parameters:
      - name: id
        in: path
        description: task index (number) or task id (UUID)
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaskRequest'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskObject'
  /tasks/move:
    put:
      tags:
      - Tasks
      summary: Move tasks
      description: Not working. https://www.notion.so/Move-tasks-0e612add3e09400bacc6119c8129fa67
      operationId: moveTasks
      x-codeSamples:
      - lang: JavaScript
        label: SDK
        source: 'const height = new Height({secretKey: ''secret_your-key''});


          height.tasks.move({...});'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MoveTasksRequest'
        required: true
      responses:
        '200':
          description: Successful operation
components:
  schemas:
    CreateTaskRequest:
      type: object
      required:
      - name
      - listIds
      properties:
        name:
          type: string
        listIds:
          type: array
          items:
            type: string
            format: uuid
          minItems: 1
          description: An array of UUIDs (one or more)
        description:
          type: string
        status:
          type: string
        assigneesIds:
          type: array
          items:
            type: string
            format: uuid
          description: An array of UUIDs of the users assigned to the task (optional).
        parentTaskId:
          type: string
          format: uuid
          description: The UUID of the parent task (optional).
        fields:
          type: array
          items:
            type: object
            required:
            - fieldTemplateId
            properties:
              fieldTemplateId:
                type: string
                format: uuid
                description: The id of the appropriate field template
              value:
                type: string
                description: 'For text fields: the text value of the field. For select fields: the id of the selected option'
              date:
                type: string
                format: date-time
                description: 'For date fields: the date value of the field'
              labels:
                type: array
                items:
                  type: string
                description: 'For labels fields: the labels of the field'
              linkedTasks:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    index:
                      type: number
                description: 'For linkedTasks fields: the tasks to be linked, in the format: { "id": "UUID", "index": number }'
        orderIntent:
          type: object
          description: Inserts the task at the right place in the list.
          properties:
            intent:
              type: string
              enum:
              - start
              - end
              - before
              - after
            taskId:
              type: string
              format: uuid
              description: (only used for before and after intent)
    PatchTasksRequest:
      type: object
      description: Patch multiples tasks
      properties:
        patches:
          type: array
          items:
            type: object
            required:
            - taskIds
            - effects
            properties:
              taskIds:
                type: array
                description: Array of task ids, either UUIDs or task numbers
                items:
                  type: string
                  format: uuid
              effects:
                type: array
                items:
                  oneOf:
                  - $ref: '#/components/schemas/PatchTasksNameEffect'
                  - $ref: '#/components/schemas/PatchTasksDescriptionEffect'
                  - $ref: '#/components/schemas/PatchTasksStatusEffect'
                  - $ref: '#/components/schemas/PatchTasksDeletedEffect'
                  - $ref: '#/components/schemas/PatchTasksParentTaskEffect'
                  - $ref: '#/components/schemas/PatchTasksAssigneesEffect'
                  - $ref: '#/components/schemas/PatchTasksListsEffect'
                  - $ref: '#/components/schemas/PatchTasksFieldsEffect'
                  - $ref: '#/components/schemas/PatchTasksMoveToTrashEffect'
                  - $ref: '#/components/schemas/PatchTasksOutOfTrashEffect'
    PatchTasksListsEffect:
      type: object
      description: Update lists
      properties:
        type:
          type: string
          enum:
          - lists
        listIds:
          type: array
          items:
            type: object
            properties:
              add:
                type: array
                items:
                  type: string
                  format: uuid
              remove:
                type: array
                items:
                  type: string
                  format: uuid
          description: An array of UUIDs
    MoveTasksRequest:
      type: object
      properties:
        taskIds:
          type: array
          items:
            type: string
            format: uuid
        sourceId:
          type: string
          description: UUID of list or parent task of tasks
          format: uuid
        orderIntent:
          type: object
          properties:
            intent:
              type: string
              enum:
              - start
              - end
              - before
              - after
            taskId:
              type: string
              description: UUID (only used for before and after intent)
              format: uuid
      required:
      - taskIds
      - sourceId
      - orderIntent
    UpdateTaskRequest:
      type: object
      properties:
        name:
          type: string
        listIds:
          type: array
          items:
            type: string
            format: uuid
        description:
          type: string
        status:
          type: string
          description: 'The status of the task.

            - `backLog`

            - `inProgress`

            - `done`

            - and any *UUID* of available statuses. You can find the *UUIDs* through the field template API.'
        assigneesIds:
          type: array
          items:
            type: string
            format: uuid
        parentTaskId:
          type: string
          format: uuid
        fields:
          type: array
          items:
            type: object
            required:
            - fieldTemplateId
            properties:
              fieldTemplateId:
                type: string
                format: uuid
                description: The id of the appropriate field template
              value:
                type: string
                description: 'For text fields: the text value of the field. For select fields: the id of the selected option'
              date:
                type: string
                format: date-time
                description: 'For date fields: the date value of the field'
              labels:
                type: array
                items:
                  type: string
                description: 'For labels fields: the labels of the field'
              linkedTasks:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    index:
                      type: number
                description: 'For linkedTasks fields: the tasks to be linked, in the format: { "id": "UUID", "index": number }'
      required:
      - name
    TaskObject:
      type: object
      required:
      - id
      - model
      - index
      - listIds
      - name
      - description
      - status
      - assigneesIds
      - fields
      - deleted
      - deletedAt
      - deletedByUserId
      - completed
      - completedAt
      - createdAt
      - createdUserId
      - lastActivityAt
      - url
      - trashedAt
      - trashedByUserId
      properties:
        id:
          type: string
          description: The unique id of the task
        model:
          type: string
          enum:
          - task
          description: The model is always `task`
        index:
          type: number
          description: The task index. For example, if the task is T-123, its index is 123.
        listIds:
          type: array
          description: Tasks belong to one or more lists. To create tasks, it's necessary to know in which list you want to create them.
          items:
            type: string
            format: uuid
        name:
          type: string
          description: The name of the task.
        description:
          type: string
          description: The description of the task. It's only retrieved if you use include. See ['Get a task'](https://www.notion.so/Get-a-task-8afda1c08e7f4f07a5c53720710cf24e).
        status:
          type: string
          description: 'The status of the task.

            - `backLog`

            - `inProgress`

            - `done`

            - and any *UUID* of available statuses. You can find the *UUIDs* through the field template API.'
        assigneesIds:
          type: array
          items:
            type: string
            format: uuid
          description: "The assignees of the task. You can find the UUIDs of users through the users API.\n ['List all users'](https://www.notion.so/List-all-users-ea66d04e48534b32927903c4deee58e8)"
          minItems: 1
        fields:
          type: array
          items:
            type: object
            required:
            - fieldTemplateId
            properties:
              fieldTemplateId:
                type: string
                format: uuid
                description: The id of the appropriate field template
              value:
                type: string
                description: 'For text fields: the text value of the field. For select fields: the id of the selected option'
              date:
                type: string
                format: date-time
                description: 'For date fields: the date value of the field'
              labels:
                type: array
                items:
                  type: string
                description: 'For labels fields: the labels of the field'
              linkedTasks:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    index:
                      type: number
                description: 'For linkedTasks fields: the tasks to be linked, in the format: { "id": "UUID", "index": number }'
        deleted:
          type: boolean
          description: If the task was deleted.
        deletedAt:
          type: string
          format: date-time
          description: The date at which the task was deleted.
        deletedByUserId:
          type: string
          format: uuid
          description: The user that deleted the task.
        completed:
          type: boolean
          description: If the status is considered as completed (i.e. `done`), the value will be `true`.
        completedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        createdUserId:
          type: string
          format: uuid
          description: The user that created the task.
        lastActivityAt:
          type: string
          format: date-time
        url:
          type: string
          description: The URL of the task.
        trashedAt:
          type: string
          format: date-time
          description: A timestamp when the task was moved to the trash. Tasks are deleted after 30 days in the trash. This will be null unless the task is currently in the trash or deleted.
        trashedByUserId:
          type: string
          format: uuid
          description: The id of the user that moved the task to the trash
        parentTaskId:
          type: string
          format: uuid
          description: If the task is a subtask of another task, `parentTaskId` will be the id of the parent task.
    PatchTasksMoveToTrashEffect:
      type: object
      description: Move trash to the task
      required:
      - type
      - trashState
      - trashStateEffectAt
      properties:
        type:
          type: string
          enum:
          - trashState
        trashState:
          type: string
          enum:
          - trash
        trashStateEffectAt:
          type: string
          format: date-time
          description: ISO 8601 date-time
    PatchTasksParentTaskEffect:
      type: object
      description: Update parent task
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - parentTask
        parentTaskId:
          type:
          - 'null'
          - string
          format: uuid
          description: The UUID of the parent task (optional).
    PatchTasksStatusEffect:
      type: object
      description: Update status
      required:
      - type
      - status
      properties:
        type:
          type: string
          enum:
          - status
        status:
          description: 'The status of the task.

            - `backLog`

            - `inProgress`

            - `done`

            - and any *UUID* of available statuses. You can find the *UUIDs* through the field template API.'
          type: string
        completedAt:
          type: string
          format: date-time
          description: ISO 8601 date-time
    PatchTasksAssigneesEffect:
      type: object
      description: Update assignees
      required:
      - type
      - assigneesIds
      properties:
        type:
          type: string
          enum:
          - assignees
        assigneesIds:
          type: array
          items:
            type: object
            properties:
              add:
                type: array
                items:
                  type: string
                  format: uuid
              remove:
                type: array
                items:
                  type: string
                  format: uuid
          description: An array of UUIDs of the users assigned to the task (optional).
    PatchTasksOutOfTrashEffect:
      type: object
      description: Move task out of the trash
      required:
      - type
      - trashState
      - trashStateEffectAt
      properties:
        type:
          type: string
          enum:
          - trashState
        trashState:
          type: string
          enum:
          - active
        trashStateEffectAt:
          type: string
          format: date-time
          description: ISO 8601 date-time
    PatchTasksResponse:
      type: object
      properties:
        list:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/TaskObject'
    SearchTasksResponse:
      type: object
      properties:
        list:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/TaskObject'
    PatchTasksDeletedEffect:
      type: object
      description: Update deleted
      required:
      - type
      - deleted
      properties:
        type:
          type: string
          enum:
          - deleted
        deleted:
          type: boolean
    PatchTasksDescriptionEffect:
      type: object
      description: Update description
      required:
      - type
      - description
      properties:
        type:
          type: string
          enum:
          - description
        description:
          type: object
          required:
          - message
          properties:
            message:
              type: string
    PatchTasksFieldsEffect:
      type: object
      description: Update fields
      required:
      - type
      - fieldTemplateId
      - field
      properties:
        type:
          type: string
          enum:
          - fields
        fieldTemplateId:
          type: string
          format: uuid
        field:
          type: object
          properties:
            text:
              type:
              - 'null'
              - string
              description: The value of the field when the template type is text.
            date:
              type:
              - 'null'
              - string
              format: date-time
              description: The value of the field when the template type is date.
            recursion:
              type:
              - 'null'
              - object
              description: 'recursion

                Untyped. Should be documented in [original docs](https://www.notion.so/Update-tasks-53d72cb0059a4e0e81cc2fcbfcbf9d0a)'
            label:
              type: object
              description: The label value of the field when the template type is select.
              properties:
                optionId:
                  type: string
                  format: uuid
            labels:
              type: object
              description: The label values of the field when the template type is labels.
              properties:
                add:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: The ID for the label to add.
                    required:
                    - id
                remove:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: The ID for the label to remove.
                    required:
                    - id
            linkedTasks:
              type: object
              description: The linked tasks value of the field when the template type is linkedTask or reverseLinkedTask.
              properties:
                add:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: The ID for the task to add.
                      index:
                        type: integer
                        description: The index for the task to add.
                    required:
                    - id
                remove:
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: The ID for the task to remove.
                      index:
                        type: integer
                        description: The index for the task to remove.
                    required:
                    - id
        userIds:
          type: object
          description: The user IDs of the field when the template type is users.
          properties:
            add:
              type: array
              items:
                type: string
                format: uuid
                description: The user ID to add.
              required:
              - id
            remove:
              type: array
              items:
                type: string
                format: uuid
                description: The user ID to remove.
              required:
              - id
    PatchTasksNameEffect:
      type: object
      description: Update name
      required:
      - type
      - name
      properties:
        type:
          type: string
          enum:
          - name
        name:
          type: string
  securitySchemes:
    apiKey:
      type: apiKey
      name: Authorization
      description: "The Height API uses API keys to authenticate requests. **You can view your API key in the Height settings under API**.\n ex: `api-key secret_1234`"
      in: header
externalDocs:
  description: Height official API Docs
  url: https://www.notion.so/API-documentation-643aea5bf01742de9232e5971cb4afda