Height Lists API
Tasks belong to one list. To create tasks, it's necessary to know in which list you want to create them.
OpenAPI Specification
openapi: 3.0.3
info:
title: Height APP Activities Lists 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: Lists
description: Tasks belong to one list. To create tasks, it's necessary to know in which list you want to create them.
paths:
/lists:
post:
tags:
- Lists
summary: Create a list
operationId: createList
x-codeSamples:
- lang: JavaScript
label: SDK
source: "const height = new Height({secretKey: 'secret_your-key'});\n\nheight.lists.create({\n name: 'My List',\n type: 'list',\n // ...\n});"
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateListRequest'
required: true
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ListObject'
get:
tags:
- Lists
summary: List all lists
operationId: listAllLists
x-codeSamples:
- lang: JavaScript
label: SDK
source: 'const height = new Height({secretKey: ''secret_your-key''});
height.lists.all();'
description: Use this endpoint to retrieve all the lists of the workspace. Only lists shared with the entire workspace will be returned.
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ListAllResponse'
/lists/{id}:
put:
tags:
- Lists
summary: Update a list
operationId: updateList
x-codeSamples:
- lang: JavaScript
label: SDK
source: 'const height = new Height({secretKey: ''secret_your-key''});
height.lists.update({...});'
parameters:
- name: id
in: path
description: The unique id of the list (UUIDv4)
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateListRequest'
required: true
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ListObject'
components:
schemas:
ListObject:
type: object
description: Tasks belong to one list. To create tasks, it's necessary to know in which list you want to create them.
required:
- id
- model
- type
- key
- description
- url
- appearance
properties:
id:
type: string
format: uuid
description: The unique id of the list (UUIDv4)
model:
type: string
example: list
enum:
- list
description: The model is always `list`
type:
type: string
description: '- `list`: a list that contains tasks. You can only create tasks in this type of list directly.
- `smartlist`: a smart list use filters to find tasks across different lists
- `user`: a special smart list that displays tasks assigned to a user
- `inbox`: a special smart list to display recent conversations
- `search`: a special smart list to search tasks'
enum:
- list
- smartlist
- user
- inbox
- search
key:
type: string
description: "The unique key of your list is used as their url.\n\nIf the key is `general`, the url will be: `https://your-workspace.height.app/general`\n\nKeys need to respect these rules: \n\n- valid characters are: lower-case letters, dashes and numbers\n- needs to start with a lower-case letter\n- key is unique across the workspace"
description:
type: string
description: The description of the list. It can be an empty string.
url:
type: string
description: The url of the list.
appearance:
type: object
required:
- iconUrl
properties:
iconUrl:
type: string
description: URL of the list icon
hue:
type:
- 'null'
- number
description: 'hue of the list color '
UpdateListRequest:
type: object
properties:
name:
type: string
description:
type: string
appearance:
type: object
properties:
icon:
type: string
description: the name of the icon e.g. listCircles, listBug.
hue:
type: number
required:
- icon
visualization:
type: string
enum:
- list
- kanban
- calendar
- gantt
- conversation
- figma
archivedAt:
type: string
description: string representing a date the list was archived at, in the form of an ISO 8601 date (e.g. 2011-04-11T10:20:30Z).
format: date-time
FiltersObject:
type: object
description: See FiltersObject.ts
CreateListRequest:
oneOf:
- $ref: '#/components/schemas/CreateNormalListRequest'
- $ref: '#/components/schemas/CreateSmartListRequest'
CreateNormalListRequest:
type: object
description: Create a list
required:
- name
- type
properties:
name:
type: string
type:
type: string
enum:
- list
- smartlist
description:
type: string
appearance:
type: object
required:
- icon
properties:
icon:
type: string
enum:
- list
- listCircles
- listTriangle
- listSquare
- listLines
- listRectangles
- listCircle
- listRocket
- listMushroom
- listBolt
- listBug
- listFlower
- listThumbsUp
- listTarget
- listSparkle
- listMedal
- listFlag
hue:
description: 'Hue is between 0 and 360 and used to determine the color.
If `null`, the list has no color.'
type:
- 'null'
- number
minimum: 0
maximum: 360
visualization:
description: visualization string (optional, default = list) list or kanban
default: list
type: string
enum:
- list
- kanban
ListAllResponse:
type: object
required:
- lists
properties:
list:
type: array
items:
$ref: '#/components/schemas/ListObject'
CreateSmartListRequest:
type: object
description: Create a smartlist
required:
- name
- type
- filters
properties:
name:
type: string
type:
type: string
enum:
- list
- smartlist
description:
type: string
filters:
$ref: '#/components/schemas/FiltersObject'
appearance:
type: object
required:
- icon
properties:
icon:
type: string
enum:
- list
- listCircles
- listTriangle
- listSquare
- listLines
- listRectangles
- listCircle
- listRocket
- listMushroom
- listBolt
- listBug
- listFlower
- listThumbsUp
- listTarget
- listSparkle
- listMedal
- listFlag
hue:
description: 'Hue is between 0 and 360 and used to determine the color.
If `null`, the list has no color.'
type:
- 'null'
- number
minimum: 0
maximum: 360
visualization:
description: visualization string (optional, default = list) list or kanban
default: list
type: string
enum:
- list
- kanban
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