openapi: 3.0.3
info:
  title: Height APP Activities Task Forms 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: Task Forms
paths:
  /taskForms/:id/answers:
    post:
      tags:
      - Task Forms
      summary: Create a task from a public task form
      operationId: createTaskFromTaskForm
      description: ❌ Task forms have a set number of questions, so it is impossible to set some attributes for a task using this endpoint
      x-codeSamples:
      - lang: JavaScript
        label: SDK
        source: 'const height = new Height({secretKey: ''secret_your-key''});


          height.taskForms.createTask({...});'
      parameters:
      - name: id
        in: path
        description: task form id
        required: true
        schema:
          type: string
          format: uuid
      - name: asBot
        in: query
        description: Only allowed for public task forms, and required if not authenticated
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskFromTaskFormRequest'
        required: true
      responses:
        '201':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskObject'
  /taskForms/:urlKey:
    get:
      tags:
      - Task Forms
      summary: Get a task form
      operationId: getTaskForm
      x-codeSamples:
      - lang: JavaScript
        label: SDK
        source: 'const height = new Height({secretKey: ''secret_your-key''});


          height.taskForms.get({...});'
      parameters:
      - name: urlKey
        in: path
        required: true
        schema:
          type: string
      - name: keyType
        in: query
        description: One of key or urlKey, defaulting to id
        schema:
          type: string
          enum:
          - key
          - urlKey
      - name: include
        in: query
        schema:
          type: array
          items:
            type: string
            description: Task form include type. Valid values are "RestrictedUsers", "RestrictedLists", "FieldTemplates", "SubtaskForms", "Questions", and "Fields".
            enum:
            - RestrictedUsers
            - RestrictedLists
            - FieldTemplates
            - SubtaskForms
            - Questions
            - Fields
        description: Array of task form includes
      - name: archived
        in: query
        schema:
          type: boolean
          description: only look for archived or unarchived forms
      - name: draft
        in: query
        schema:
          type: boolean
          description: only look for archived or unarchived forms
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskFormObject'
components:
  schemas:
    TaskFormObject:
      description: Uncertain typed. Height team did't provide schema for Task Form.
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The ID of the task form.
          example: c91896fb-cb00-4122-9e13-5ea3f760f3a4
        model:
          type: string
          description: always "taskForm"
          enum:
          - taskForm
        version:
          type: integer
          description: The version of the task form.
          example: 2
        key:
          type: string
          description: The key of the task form.
          example: JfsPVS9NxJ
        urlKey:
          type: string
          description: The URL key of the task form.
          example: ryNw67fFHJCd
        url:
          type: string
          description: The URL of the task form.
          example: https://height.app/u28gpe10d5/?taskForm=Task-submission-ryNw67fFHJCd
        name:
          type: string
          description: The name of the task form.
          example: Task submission
        taskFormDescription:
          type: string
          description: The description of the task form.
          example: ''
        disabledReason:
          type:
          - 'null'
          - string
          nullable: true
          description: The reason why the task form is disabled.
          example: null
        archived:
          type: boolean
          description: Flag to indicate whether the task form is archived.
          example: false
        draft:
          type: boolean
          description: Flag to indicate whether the task form is a draft.
          example: false
        publicAccess:
          type: string
          description: The type of public access for the task form.
          example: readonly
        listIds:
          type: array
          items:
            type: string
            format: uuid
          description: The IDs of the lists associated with the task form.
          example:
          - baa40cc6-240f-4df2-a01b-22476876d61e
        parentTaskId:
          type:
          - 'null'
          - string
          nullable: true
          format: uuid
          description: The ID of the parent task.
          example: null
        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.'
        questions:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                description: The ID of the question.
                example: b842f01d-8dfa-40cf-884d-1b2b95d8b6fb
              fieldId:
                type: string
                description: The ID of the field.
                example: name
              value:
                type: string
                description: The value of the question.
                example: Task Name
              required:
                type: boolean
                description: Flag to indicate whether the question is required.
                example: true
              placeholder:
                type: string
                nullable: true
                description: The placeholder for the question.
                example: Name
              restrictedLabelIds:
                type: array
                items:
                  type: string
                  format: uuid
                description: The IDs of the restricted labels for the question.
                example: []
              multipleLabels:
                type: boolean
                description: Flag to indicate whether the question accepts multiple labels.
                example: true
            description: The list of questions in the task form.
          example:
          - id: b842f01d-8dfa-40cf-884
    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.
    CreateTaskFromTaskFormRequest:
      type: object
      properties:
        answers:
          type: array
          items:
            type: object
            properties:
              questionId:
                type: string
                format: uuid
                description: The id of the task form question
              name:
                type: string
                description: The name of the task - required when the question is for the task name
              status:
                type: string
                description: The id of the status of the task - required when the question is for the task status
              assigneesIds:
                type: array
                items:
                  type: string
                  format: uuid
                description: The ids of the assignees of the task - required when the question is for the task assignees.
              listIds:
                type: array
                items:
                  type: string
                  format: uuid
                description: The ids of the lists of the task - required when the question is for the lists
                example:
                - d8dff420-ddbe-4afc-8837-f493e922be7b
                - 2f2abf80-0a87-4d68-9241-fcc41f427c91
              description:
                type: string
                description: The description of the string. Accepts markdown. Required when the question is for the description
              field:
                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 }'
                description: TaskField Attributes (optional) Required to belong to the attribute associated with the question. See the Task Object for specifications
          description: Array of question responses
      required:
      - questionId
  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