Skip to main content
API docs by Redocly

Height APP API (1.0.0)

Download OpenAPI specification:Download

E-mail: gil@beomjun.kr License: MIT

Unofficial Open API 3.1 specification for Height App API. This is not affiliated with Height team.

Height official API Docs

Authentication

The Height API uses API keys to authenticate requests. You can view your API key in the Height settings under API.

Authentication to the API is performed via the Authorization header. All API requests should be made over HTTPs.

i.e. Get your workspace.

curl https://api.height.app/workspace \
  -H "Authorization: api-key secret_1234"

Third-party applications must connect to the Height API using OAuth2.

See OAuth Apps on Height for more information.

Object formats

All objects have a unique id (UUID v4) and a model attribute to distinguish the model type.

e.g. a task object.

{
  "id": "123e4567-e89b-12d3-a456-426655440000",
  "model": "task",
  "name": "Fix bug",
  "index": 1,
  "status": "backLog",
  [...]
}

Date formats

Every date uses the ISO format e.g.

"2019-11-07T17:00:00.000Z"

Real-time

Any change that you make to the API will be pushed to every user in real-time: i.e. creating tasks or messages.

Rate limits

To 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.

Height allows up to 120 requests/min, but we have stricter limits on these endpoints:

  • POST /activities: 60 requests/min
  • POST /tasks: 60 requests/min

Lists

Tasks belong to one list. To create tasks, it's necessary to know in which list you want to create them.

Create a list

Authorizations:
apiKey
Request Body schema: application/json
One of
name
required
string
type
required
string
Enum: "list" "smartlist"
description
string
object
visualization
string
Default: "list"
Enum: "list" "kanban"

visualization string (optional, default = list) list or kanban

Responses

Request samples

Content type
application/json
Example
{
  • "name": "string",
  • "type": "list",
  • "description": "string",
  • "appearance": {
    },
  • "visualization": "list"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "model": "list",
  • "type": "list",
  • "key": "string",
  • "description": "string",
  • "url": "string",
  • "appearance": {
    }
}

List all lists

Use this endpoint to retrieve all the lists of the workspace. Only lists shared with the entire workspace will be returned.

Authorizations:
apiKey

Responses

Request samples 

const height = new Height({secretKey: 'secret_your-key'});

height.lists.all();

Response samples

Content type
application/json
[
  • {
    }
]

Update a list

Authorizations:
apiKey
path Parameters
id
required
string <uuid>

The unique id of the list (UUIDv4)

Request Body schema: application/json
name
string
description
string
object
visualization
string
Enum: "list" "kanban" "calendar" "gantt" "conversation" "figma"
archivedAt
string <date-time>

string representing a date the list was archived at, in the form of an ISO 8601 date (e.g. 2011-04-11T10:20:30Z).

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "appearance": {
    },
  • "visualization": "list",
  • "archivedAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "model": "list",
  • "type": "list",
  • "key": "string",
  • "description": "string",
  • "url": "string",
  • "appearance": {
    }
}

Tasks

Create a task

Authorizations:
apiKey
query Parameters
realtime
boolean

(defaults to true) - use false when migrating tasks

notifyUsers
boolean

(defaults to true) - use false when migrating tasks

Request Body schema: application/json
name
required
string
listIds
required
Array of strings <uuid> non-empty

An array of UUIDs (one or more)

description
string
status
string
assigneesIds
Array of strings <uuid>

An array of UUIDs of the users assigned to the task (optional).

parentTaskId
string <uuid>

The UUID of the parent task (optional).

Array of objects
object

Inserts the task at the right place in the list.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "listIds": [
    ],
  • "description": "string",
  • "status": "string",
  • "assigneesIds": [
    ],
  • "parentTaskId": "2506db93-67fe-4ab8-a809-f4aa6ed8a0f4",
  • "fields": [
    ],
  • "orderIntent": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "model": "task",
  • "index": 0,
  • "listIds": [
    ],
  • "name": "string",
  • "description": "string",
  • "status": "string",
  • "assigneesIds": [
    ],
  • "fields": [
    ],
  • "deleted": true,
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "deletedByUserId": "b4e2eaa0-43ed-4edc-af60-733b4b4b5cbd",
  • "completed": true,
  • "completedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdUserId": "ea7e097f-834f-4fa5-87fc-4730a5fb67fe",
  • "lastActivityAt": "2019-08-24T14:15:22Z",
  • "url": "string",
  • "trashedAt": "2019-08-24T14:15:22Z",
  • "trashedByUserId": "6e322b0d-77cc-443e-9b8b-40a723fc244b",
  • "parentTaskId": "2506db93-67fe-4ab8-a809-f4aa6ed8a0f4"
}

Patch multiples tasks

Authorizations:
apiKey
Request Body schema: application/json
Array of objects
Array
taskIds
required
Array of strings <uuid>

Array of task ids, either UUIDs or task numbers

required
Array of PatchTasksNameEffect (object) or PatchTasksDescriptionEffect (object) or PatchTasksStatusEffect (object) or PatchTasksDeletedEffect (object) or PatchTasksParentTaskEffect (object) or PatchTasksAssigneesEffect (object) or PatchTasksListsEffect (object) or PatchTasksFieldsEffect (object) or PatchTasksMoveToTrashEffect (object) or PatchTasksOutOfTrashEffect (object)

Responses

Request samples

Content type
application/json
{
  • "patches": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Search tasks

Authorizations:
apiKey
query Parameters
filters
string
Example: filters={"status":{"values":["backLog","inProgress"]},"assigneeId":{"values":["123e4567-e89b-12d3-a456-426655440000"]},"completed":{"values":[false]},"lastActivityAt":{"values":[],"gt":{"date":"2019-11-07T17:00:00.000Z"}}}

JSON object with filters

Responses

Request samples 

const height = new Height({secretKey: 'secret_your-key'});

const request: SearchTasksRequest = {};
height.tasks.search(request);

Response samples

Content type
application/json
{
  • "list": [
    ]
}

Get a task

Authorizations:
apiKey
path Parameters
id
required
string <uuid>

task index (number) or task id (UUID)

query Parameters
include
string
Enum: "Assignees" "CreatedByUser" "CompletedByUser" "DeletedByUser" "Subscribers" "Fields.User" "Lists" "Status" "Mentions" "NotificationsSubscription" "ParentTasks" "SubtaskIds"

What you wish to include with the task.

Responses

Request samples 

const height = new Height({secretKey: 'secret_your-key'});

height.tasks.get({...});

Response samples

Content type
application/json
{
  • "id": "string",
  • "model": "task",
  • "index": 0,
  • "listIds": [
    ],
  • "name": "string",
  • "description": "string",
  • "status": "string",
  • "assigneesIds": [
    ],
  • "fields": [
    ],
  • "deleted": true,
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "deletedByUserId": "b4e2eaa0-43ed-4edc-af60-733b4b4b5cbd",
  • "completed": true,
  • "completedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdUserId": "ea7e097f-834f-4fa5-87fc-4730a5fb67fe",
  • "lastActivityAt": "2019-08-24T14:15:22Z",
  • "url": "string",
  • "trashedAt": "2019-08-24T14:15:22Z",
  • "trashedByUserId": "6e322b0d-77cc-443e-9b8b-40a723fc244b",
  • "parentTaskId": "2506db93-67fe-4ab8-a809-f4aa6ed8a0f4"
}

Update a single task

Authorizations:
apiKey
path Parameters
id
required
string <uuid>

task index (number) or task id (UUID)

Request Body schema: application/json
name
required
string
listIds
Array of strings <uuid>
description
string
status
string

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
Array of strings <uuid>
parentTaskId
string <uuid>
Array of objects

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "listIds": [
    ],
  • "description": "string",
  • "status": "string",
  • "assigneesIds": [
    ],
  • "parentTaskId": "2506db93-67fe-4ab8-a809-f4aa6ed8a0f4",
  • "fields": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "model": "task",
  • "index": 0,
  • "listIds": [
    ],
  • "name": "string",
  • "description": "string",
  • "status": "string",
  • "assigneesIds": [
    ],
  • "fields": [
    ],
  • "deleted": true,
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "deletedByUserId": "b4e2eaa0-43ed-4edc-af60-733b4b4b5cbd",
  • "completed": true,
  • "completedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdUserId": "ea7e097f-834f-4fa5-87fc-4730a5fb67fe",
  • "lastActivityAt": "2019-08-24T14:15:22Z",
  • "url": "string",
  • "trashedAt": "2019-08-24T14:15:22Z",
  • "trashedByUserId": "6e322b0d-77cc-443e-9b8b-40a723fc244b",
  • "parentTaskId": "2506db93-67fe-4ab8-a809-f4aa6ed8a0f4"
}

Move tasks

Not working. https://www.notion.so/Move-tasks-0e612add3e09400bacc6119c8129fa67

Authorizations:
apiKey
Request Body schema: application/json
taskIds
required
Array of strings <uuid>
sourceId
required
string <uuid>

UUID of list or parent task of tasks

required
object

Responses

Request samples

Content type
application/json
{
  • "taskIds": [
    ],
  • "sourceId": "797f5a94-3689-4ac8-82fd-d749511ea2b2",
  • "orderIntent": {
    }
}

Activities

Activities can be messages, status updates of the task or integration updates (i.e. GitHub).

Post a message

Authorizations:
apiKey
Request Body schema: application/json
taskId
required
string <uuid>
type
required
string
Enum: "comment" "description"
message
required
string

Mentions

Height supports multiple types of mentions, with each their own format:

User mention: @user_<userId>

Group mention: @group_<groupId>

Task mention: T-<taskIndex>

List mention: #<listKey>

Responses

Request samples

Content type
application/json
{
  • "taskId": "e6e9d88a-9b63-468a-aec3-b7a11de27af8",
  • "type": "comment",
  • "message": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "model": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "taskId": "e6e9d88a-9b63-468a-aec3-b7a11de27af8",
  • "createdUserId": "ea7e097f-834f-4fa5-87fc-4730a5fb67fe",
  • "type": "comment",
  • "message": "string",
  • "oldValue": "string",
  • "newValue": "string",
  • "reactjis": [
    ],
  • "readUserIds": [
    ],
  • "url": "string"
}

List activities and messages

Authorizations:
apiKey
query Parameters
taskId
string <uuid>

Either the task unique id (UUID), or the task unique index (the 123 of T-123).

Responses

Request samples 

const height = new Height({secretKey: 'secret_your-key'});

height.activities.get({...});

Response samples

Content type
application/json
{
  • "list": [
    ]
}

Field templates

Field templates define what attributes look like. To create tasks with custom attributes, it's important to know which field templates are available.

Task forms

Users

Get all users

Authorizations:
apiKey

Responses

Request samples 

const height = new Height({secretKey: 'secret_your-key'});

height.users.all();

Response samples

Content type
application/json
{
  • "list": [
    ]
}

Get a user

Authorizations:
apiKey
path Parameters
id
required
string <uuid>

Responses

Request samples 

const height = new Height({secretKey: 'secret_your-key'});

height.users.get({...});

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "model": "user",
  • "state": "enabled",
  • "email": "string",
  • "username": "string",
  • "firstname": "string",
  • "lastname": "string",
  • "access": "member",
  • "createdAt": "2023-02-18T10:15:00Z",
  • "pictureUrl": "https://example.com/user.jpg"
}

Get the current user

Authorizations:
apiKey

Responses

Request samples 

const height = new Height({secretKey: 'secret_your-key'});

height.users.me();

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "model": "user",
  • "state": "enabled",
  • "email": "string",
  • "username": "string",
  • "firstname": "string",
  • "lastname": "string",
  • "access": "member",
  • "createdAt": "2023-02-18T10:15:00Z",
  • "pictureUrl": "https://example.com/user.jpg"
}

Groups

Get all groups

Authorizations:
apiKey

Responses

Request samples 

const height = new Height({secretKey: 'secret_your-key'});

height.groups.all();

Response samples

Content type
application/json
{
  • "list": [
    ]
}

Security log events

Workspace

Retrieve the workspace

Authorizations:
apiKey

Responses

Request samples 

const height = new Height({secretKey: 'secret_your-key'});

height.workspace.get();

Response samples

Content type
application/json
{}

Search

Webhooks

OAuth

Height uses the authorization code grant flow (see the OAuth2 spec ) in which an application should send the user to Height’s authorization endpoint to ask for permission to access their Height workspace. If granted, the app will receive a redirect with a code that can be exchanged for an access token. This token can be used in the Authorization header to make Height API calls on behalf of the user.

Field Templates

List all field templates

Authorizations:
apiKey

Responses

Request samples 

const height = new Height({secretKey: 'secret_your-key'});

height.fieldTemplates.all();

Response samples

Content type
application/json
{
  • "list": [
    ]
}

Create an option for a field template

This endpoint adds an option to a select or labels field template.

Authorizations:
apiKey
path Parameters
id
required
string <uuid>

field template id (UUID)

Request Body schema: application/json
value
required
string
hue
number

number between 0 and 360 (optional)

Responses

Request samples

Content type
application/json
{
  • "value": "string",
  • "hue": 0
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "model": "fieldTemplate",
  • "name": "string",
  • "type": "text",
  • "labelSets": [
    ],
  • "labels": [
    ],
  • "archive": true
}

Update or delete an option for a field template

This endpoint updates or deletes an option to a select or labels field template.

The field template must be unlocked to use this endpoint. Locking and unlocking field templates is an enterprise feature.

Authorizations:
apiKey
path Parameters
id
required
string <uuid>
optionId
required
string <uuid>
Request Body schema: application/json
value
required
string
hue
number

number between 0 and 360 (optional)

deleted
boolean

Responses

Request samples

Content type
application/json
{
  • "value": "string",
  • "hue": 0,
  • "deleted": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "model": "fieldTemplate",
  • "name": "string",
  • "type": "text",
  • "labelSets": [
    ],
  • "labels": [
    ],
  • "archive": true
}

Task Forms

Create a task from a public task form

❌ Task forms have a set number of questions, so it is impossible to set some attributes for a task using this endpoint

Authorizations:
apiKey
path Parameters
id
required
string <uuid>

task form id

query Parameters
asBot
boolean

Only allowed for public task forms, and required if not authenticated

Request Body schema: application/json
Array of objects

Array of question responses

Array
questionId
string <uuid>

The id of the task form question

name
string

The name of the task - required when the question is for the task name

status
string

The id of the status of the task - required when the question is for the task status

assigneesIds
Array of strings <uuid>

The ids of the assignees of the task - required when the question is for the task assignees.

listIds
Array of strings <uuid>

The ids of the lists of the task - required when the question is for the lists

description
string

The description of the string. Accepts markdown. Required when the question is for the description

object

TaskField Attributes (optional) Required to belong to the attribute associated with the question. See the Task Object for specifications

Responses

Request samples

Content type
application/json
{
  • "answers": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "model": "task",
  • "index": 0,
  • "listIds": [
    ],
  • "name": "string",
  • "description": "string",
  • "status": "string",
  • "assigneesIds": [
    ],
  • "fields": [
    ],
  • "deleted": true,
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "deletedByUserId": "b4e2eaa0-43ed-4edc-af60-733b4b4b5cbd",
  • "completed": true,
  • "completedAt": "2019-08-24T14:15:22Z",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "createdUserId": "ea7e097f-834f-4fa5-87fc-4730a5fb67fe",
  • "lastActivityAt": "2019-08-24T14:15:22Z",
  • "url": "string",
  • "trashedAt": "2019-08-24T14:15:22Z",
  • "trashedByUserId": "6e322b0d-77cc-443e-9b8b-40a723fc244b",
  • "parentTaskId": "2506db93-67fe-4ab8-a809-f4aa6ed8a0f4"
}

Get a task form

Authorizations:
apiKey
path Parameters
urlKey
required
string
query Parameters
keyType
string
Enum: "key" "urlKey"

One of key or urlKey, defaulting to id

include
Array of strings
Items Enum: "RestrictedUsers" "RestrictedLists" "FieldTemplates" "SubtaskForms" "Questions" "Fields"

Array of task form includes

archived
boolean

only look for archived or unarchived forms

draft
boolean

only look for archived or unarchived forms

Responses

Request samples 

const height = new Height({secretKey: 'secret_your-key'});

height.taskForms.get({...});

Response samples

Content type
application/json
{
  • "id": "c91896fb-cb00-4122-9e13-5ea3f760f3a4",
  • "model": "taskForm",
  • "version": 2,
  • "key": "JfsPVS9NxJ",
  • "urlKey": "ryNw67fFHJCd",
  • "url": "https://height.app/u28gpe10d5/?taskForm=Task-submission-ryNw67fFHJCd",
  • "name": "Task submission",
  • "taskFormDescription": "",
  • "disabledReason": null,
  • "archived": false,
  • "draft": false,
  • "publicAccess": "readonly",
  • "listIds": [
    ],
  • "parentTaskId": null,
  • "status": "string",
  • "questions": [
    ]
}

Security Log Events

List all security log event objects

Authorizations:
apiKey

Responses

Request samples 

const height = new Height({secretKey: 'secret_your-key'});

height.securityLogEvents.all();

Response samples

Content type
application/json
{
  • "list": [
    ]
}