Height Task Forms API
The Task Forms API from Height — 2 operation(s) for task forms.
OpenAPI Specification
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