Skip to content

Instantly share code, notes, and snippets.

@ChangJoo-Park

ChangJoo-Park/clickup20.apib

Created March 13, 2020 08:39
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 1 You must be signed in to fork a gist
  • Save ChangJoo-Park/2abe0ec8fbe946eb7782d4856c83f927 to your computer and use it in GitHub Desktop.
Save ChangJoo-Park/2abe0ec8fbe946eb7782d4856c83f927 to your computer and use it in GitHub Desktop.
Download ZIP
clickup20
Raw
clickup20.apib
FORMAT: 1A
HOST: https://api.clickup.com/api/v2
# ClickUp 2.0
Let's make people more productive, together.
Looking for the v1 documentation? Click [here](https://clickup.com/apiv1).
Please use our [feedback board](https://feedback.clickup.com/api-20) to report bugs, feature requests, and collaborate with the community.
## Authentication
There are two ways to authenticate with ClickUp API 2.0, with a personal token or creating an application and authenticating with an OAuth2 flow. Once you receive one of those two tokens, use that in the `Authorization` header of your API requests.
**IMPORTANT** - _If you are creating an application for other's to use, it is highly recommended that you use the OAuth2 flow._
### Personal Token
If you are using the API for personal use, it is safe to use the personal API token. You can find this token in your user settings, under the `Apps` section. At the top of the page you have the option to generate a personal token. These tokens will always begin with `pk_`.
![personal_token](https://attachments3.clickup.com/343f245e-7d27-411d-96d0-9ad3a6f2f8a7/personal_token.png)
If your token becomes compromised, you can regenerate it. However, be aware that any applications that were using the old token will lose access once it has been regenerated.
### OAuth2 Flow
When you want to develop an application that others can use, you must go through the OAuth2 flow so that ever user that uses your application gets assigned an individualized token. This way each user of your application is able to access their own ClickUp resources. If you are unfamiliar with OAuth2, Digital Ocean has put together a great [guide](https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2) that should get you started.
**Note** - _ClickUp uses the authorization code grant type._
#### How To Use the ClickUp OAuth2 Flow
1. **Create An OAuth App** - As an admin, navigate to your team settings and click on the `Integrations` section. Once there, click on the icon that is labeled "ClickUp API" and create a new app. When you create an app, you will be prompted to enter a name, and at least one redirect url. When your app is created, you will be provided with a `client_id` and a `secret`.
2. **Authorization Code** - You must first retrieve an authorization code from your user before you can get an access token for their account.
- To start this process, redirect the user to `https://app.clickup.com/api?client_id={client_id}&redirect_uri={redirect_uri}` with the redirect query parameter set to a redirect uri that you specified when creating the oauth app. The host of the redirect uri must match one of those redirect uris or the request will fail. The protocol will default to https if not provided, and non-ssl redirect uris may not be supported in the future.
- Once the user has accepted or rejected the authorization request, they will be redirected back to the `redirect_uri` with the necessary query parameters for getting an access token.
3. **Access Token** - Once you have retrieved the authorization code in the previous step, you can then use the route `POST /api/v2/oauth/token` with the parameters `client_id`, `secret` , and `code` to get the user access token. This is the token that is used in the `Authorization` header for all requests in the ClickUp API. Skip to the authorization section below for more information on this route.
4. **Token Teams** - When you redirect your user in step 2 of this flow, they will be prompted which teams (workspaces) they want to grant you access to. Therefore in order to access a specific team for the user, you need to ensure that they have given you access. You can use the route `GET /api/v2/team` to see which teams they have authorized you to access. If they have not given you access to the appropriate teams, you can redirect them to the authorization code URL from step 2 at any time to reauthorize your app. Below is a screenshot of what the user sees when they visit this URL.
![token_teams](https://attachments3.clickup.com/49988c04-bf0f-42a5-96cc-82ce213b7f5e/token_teams.png)
## Rate Limiting
The API is rate limited per OAuth token. You will receive a 429 HTTP status code if you exceed the rate limit. The rate limit is 100 requests per minute per token and is subject to change.
## Error Handling
Errors responses will return a non-200 status code and a json err message and error code.
Common errors include:
**`Team not authorized`**: This error is thrown when a team was not authorized by the user for a particular access token. Refer to the `Token Teams` section of the OAuth instructions for more information on how to fix this error. Error codes that are associated with this message include `OAUTH_023`, `OAUTH_026`, `OAUTH_027`, and `OAUTH_029` to `OAUTH_045`
**`Token not found`**: This error is thrown if authorization is revoked by the user, as described in the "Personal Token" section. Error codes that are associated with this message include `OAUTH_019`, `OAUTH_021`, `OAUTH_025`, and `OAUTH_077`
**`Authorization Header Required`**: The authorization token was missing in the `Authorization` http header. `OAUTH_017`
**`Client Not Found`**: The client application was not created correctly. `OAUTH_010`
**`Redirect URI not passed`**: The redirect URI was not present during the OAuth authentication flow. Refer to the section "Create An OAuth App" to resolve this error. `OAUTH_017`
**`Redirect URI does not match the redirect uris of this application`**: The redirect URI must be registered with your client application. Refer to the section "Create An OAuth App" to resolve this error. `OAUTH_007`
## FAQ
> What is `team` in reference to?
Teams is the legacy term for what are now called Workspaces in ClickUp. For compatablitly, the term `team` is still used in this API.
> What `Content-Type` should I use?
When formatting your requests to ClickUp, please always use the content type `application/json`. Using form encoded data is not fully supported and can result in unexpected consequences.
> How are projects and folders related?
Projects are what we used to call folders in ClickUp v1. If you use the first version of the API, the items that are returned to you as projects are the same as folders in the second version of the API. You must use the correct nomenclature depending on the version of the API you are using (`project` for v1 and `folder` for v2) and cannot interchange them.
> Does the access token returned from `POST /api/v2/oauth/token` expire?
The access token does not expire at this time.
> Is it possible to move a task between lists using the API?
It is not possible to move a task between lists at this time. This is a complicated process, however we hope to implement this on the public API in the near future.
> Will tasks created via API generate notifications?
Yes, all actions you take with the public api will trigger all of the same process that would occur through the UI. This includes notifications, websocket messages, webhooks, etc.
> How do I tell who has access to a particular task?
To get a list of team members that have access to a particular task or list, use the routes `GET /api/v2/task/{{task_id}}/member` and `GET /api/v2/list/{{list_id}}/member` under the "Members" section of this documentation.
> How are dates formatted in ClickUp?
ClickUp will always display dates in [Epoch/Unix](https://en.wikipedia.org/wiki/Unix_time) time.
> How are subtasks represented in the API?
Subtasks are identical to tasks in every way. Therefore, you can manipulate subtasks the same way you would update any task with the API. To check if a task object is a subtask or not, locate the `parent` property. If this value is `null` then it is not a subtask, otherwise it will contain the task ID of the subtask's parent.
To create a subtask, use `POST /api/v2/list/:list_id/task` and make sure to set the `parent` property in the body of the request. Similarly, to update or delete existing subtasks, use the routes `PUT /api/v2/task/:task_id` and `DELETE /api/v2/task/:task_id` respectively. To fetch subtasks, get the parent task and add the subtask query param (`GET /api/v2/task/:parent_id?subtasks=true`) or use the search team route with that same query param (`GET /api/v2/team/:team_id/task?subtasks=true`).
## Attachments [/attachment]
To post at attachment to ClickUp, you must send the desired file in a `POST` request to the following route. Uploading attachments to ClickUp is one of the only times that you will not use `Content-Type: application/json`, instead you must send the file in the `multipart/form-data` format. Depending on what language you are building your application in, the method of formatting each request is going to look quite different.
If you are unfamiliar with this request body format, check out this article ([Understanding HTML Form Encoding: URL Encoded and Multipart Forms](https://dev.to/sidthesloth92/understanding-html-form-encoding-url-encoded-and-multipart-forms-3lpa)) which does a great job describing how you would POST an attachment from the browser. It also explains what the raw HTTP request looks like, which is helpful if you are making the request server side.
It is always helpful to test your request before putting it into code with a tool like [Postman](https://www.getpostman.com/). You can easily upload an attachment via `multipart/form-data` with postman by following these [instructions](https://learning.getpostman.com/docs/postman/sending-api-requests/requests/#form-data).
Finally, we have provided an example of how you would post an attachment with `Node.js`:
```
const FormData = require('form-data');
const axios = require('axios');
const fs = require('fs');
const form = new FormData();
form.append('filename', '')
form.append('attachment', fs.createReadStream('./img.png'));
axios({
method: 'post',
url: 'https://api.clickup.com/api/v2/task/123/attachment',
data: form,
headers: {
'content-type': 'multipart/form-data',
}
})
.then(() => console.log('success'))
.catch(() => console.log('fail'));
```
_Note_ - Make sure that your file is named `attachment` otherwise the API will not recognize the file.
### Post Task Attachment [POST /task/{task_id}/attachment]
+ Parameters
+ task_id: 9hv (string)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: multipart/form-data
+ Body
attachment: raw_image_file (file)
filename: example.png (string)
+ Response 200 (application/json)
{
"id": "ac434d4e-8b1c-4571-951b-866b6d9f2ee6.png",
"version": "0",
"date": 1569988578766,
"title": "image.png",
"extension": "png",
"thumbnail_small": "https://attachments-public.clickup.com/ac434d4e-8b1c-4571-951b-866b6d9f2ee6/logo_small.png",
"thumbnail_large": "https://attachments-public.clickup.com/ac434d4e-8b1c-4571-951b-866b6d9f2ee6/logo_small.png",
"url": "https://attachments-public.clickup.com/ac434d4e-8b1c-4571-951b-866b6d9f2ee6/logo_small.png"
}
## Authorization [/oauth]
These are the routes for authing the API and going through the OAuth flow described above. Applications utilizing the personal API token can skip this section.
### Get Access Token [POST /oauth/token{?client_id,client_secret,code}]
+ Parameters
+ client_id (string) - Oauth app client id
+ client_secret (string) - Oauth app client secret
+ code (string) - Code given in redirect url
+ Response 200 (application/json)
{
"access_token": "access token"
}
### Get Authorized User [GET /user]
+ Request
Get the user that belongs to this token
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"user": {
"id": 123,
"username": "John Doe",
"color": "#000000",
"profilePicture": "https://clickup.com/avatar.jpg"
}
}
### Get Authorized Teams [GET /team]
+ Request
Get the authorized teams for this token
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"teams": [
{
"id": "1234",
"name": "My ClickUp Team",
"color": "#000000",
"avatar": "https://clickup.com/avatar.jpg",
"members": [
{
"user": {
"id": 123,
"username": "John Doe",
"color": "#000000",
"profilePicture": "https://clickup.com/avatar.jpg"
}
}
]
}
]
}
## Checklists [/checklist]
### Create Checklist [POST /task/{task_id}/checklist]
+ Parameters
+ task_id: 9hz (string)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "Checklist"
}
+ Response 200 (application/json)
{
"checklist": {
"id": "b955c4dc-b8a8-48d8-a0c6-b4200788a683",
"task_id": "9hz",
"name": "Checklist",
"orderindex": 0,
"resolved": 0,
"unresolved": 0,
"items": []
}
}
### Edit Checklist [PUT /checklist/{checklist_id}]
+ Parameters
+ checklist_id: b955c4dc-b8a8-48d8-a0c6-b4200788a683 (uuid)
+ Request
`position` is the zero-based index of the order you want the checklist to exist on the task. If you want the checklist to be in the first position, pass `{ "position": 0 }`
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "Updated Checklist",
"position": 1
}
+ Response 200 (application/json)
{
"checklist": {
"id": "b955c4dc-b8a8-48d8-a0c6-b4200788a683",
"task_id": "9hz",
"name": "Updated Checklist",
"orderindex": 5,
"resolved": 0
"unresolved": 0,
"items": []
}
}
### Delete Checklist [DELETE /checklist/{checklist_id}]
+ Parameters
+ checklist_id: b955c4dc-b8a8-48d8-a0c6-b4200788a683 (uuid)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{}
### Create Checklist Item [POST /checklist/{checklist_id}/checklist_item]
+ Parameters
+ checklist_id: b955c4dc-b8a8-48d8-a0c6-b4200788a683 (uuid)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "Checklist Item",
"assignee": 183
}
+ Response 200 (application/json)
{
"checklist": {
"id": "b955c4dc-b8a8-48d8-a0c6-b4200788a683",
"task_id": "9hv",
"name": "Checklist",
"date_created": "1567711563204",
"orderindex": 0,
"resolved": 0,
"unresolved": 1,
"items": [
{
"id": "21e08dc8-e491-47f5-9fd8-d1dc4cedcc6f",
"name": "Checklist Item",
"orderindex": 0,
"assignee": {
"id": 183,
"username": "John Doe",
"email": "example@email.com",
"color": "#827718",
"initials": "JK",
"profilePicture": "https://dev-attachments-public.clickup.com/profilePictures/183_nx1.jpg"
},
"resolved": false,
"parent": null,
"date_created": "1567711566859",
"children": []
}
]
}
}
### Edit Checklist Item [PUT /checklist/{checklist_id}/checklist_item/{checklist_item_id}]
+ Parameters
+ checklist_id: b955c4dc-b8a8-48d8-a0c6-b4200788a683 (uuid)
+ checklist_item_id: 21e08dc8-e491-47f5-9fd8-d1dc4cedcc6f (uuid)
+ Request
`parent` is another checklist item that you want to nest the target checklist item underneath.
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "Updated Checklist Item",
"assignee": null,
"resolved": true,
"parent": null
}
+ Response 200 (application/json)
{
"checklist": {
"id": "b955c4dc-b8a8-48d8-a0c6-b4200788a683",
"task_id": "9hv",
"name": "Checklist",
"date_created": "1567711563204",
"orderindex": 0,
"resolved": 1,
"unresolved": 0,
"items": [
{
"id": "21e08dc8-e491-47f5-9fd8-d1dc4cedcc6f",
"name": "Updated Checklist Item",
"orderindex": 0,
"assignee": null,
"resolved": true,
"parent": null,
"date_created": "1567711566859",
"children": []
}
]
}
}
### Delete Checklist Item [DELETE /checklist/{checklist_id}/checklist_item/{checklist_item_id}]
+ Parameters
+ checklist_id: b955c4dc-b8a8-48d8-a0c6-b4200788a683 (uuid)
+ checklist_item_id: 21e08dc8-e491-47f5-9fd8-d1dc4cedcc6f (uuid)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{}
## Comments [/comment]
### Post Task Comment [POST /task/{task_id}/comment]
+ Parameters
+ task_id: 9hz (string)
+ Request
If `notify_all` is true, creation notifications will be sent to everyone including the creator of the comment.
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"comment_text": "Task comment content",
"assignee": 183,
"notify_all": true
}
+ Response 200 (application/json)
{
"id": "458",
"hist_id": "26508",
"date": 1568036964079
}
### Post View Comment [POST /view/{view_id}/comment]
+ Parameters
+ view_id: 3c-105 (string)
+ Request
If `notify_all` is true, creation notifications will be sent to everyone including the creator of the comment.
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"comment_text": "View comment content",
"notify_all": true
}
+ Response 200 (application/json)
{
"id": "459",
"hist_id": "0a45e16e-4e2f-4a9e-99ec-3cf520b87eae",
"date": 1568037065216
}
### Post List Comment [POST /list/{list_id}/comment]
+ Parameters
+ list_id: 124 (number)
+ Request
If `notify_all` is true, creation notifications will be sent to everyone including the creator of the comment.
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"comment_text": "List comment content",
"assignee": 183,
"notify_all": true
}
+ Response 200 (application/json)
{
"id": "462",
"hist_id": "5bbea9ad-7cc3-4038-a8bb-a89ac1337c08",
"date": 1568037341249
}
### Get Task Comments [GET /task/{task_id}/comment]
+ Parameters
+ task_id: 9hz (string)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"comments": [
{
"id": "458",
"comment": [
{
"text": "Task comment content"
}
],
"comment_text": "Task comment content",
"user": {
"id": 183,
"username": "John Doe",
"initials": "JD",
"email": "johndoe@gmail.com",
"color": "#827718",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg"
},
"resolved": false,
"assignee": {
"id": 183,
"username": "John Doe",
"initials": "JD",
"email": "johndoe@gmail.com",
"color": "#827718",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg"
},
"assigned_by": {
"id": 183,
"username": "John Doe",
"initials": "JD",
"email": "johndoe@gmail.com",
"color": "#827718",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg"
},
"reactions": [],
"date": "1568036964079"
}
]
}
### Get View Comments [GET /view/{view_id}/comment]
+ Parameters
+ view_id: 3c-105 (string)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"comments": [
{
"id": "459",
"comment": [
{
"text": "View comment content"
}
],
"comment_text": "View comment content",
"user": {
"id": 183,
"username": "John Doe",
"initials": "JD",
"email": "johndoe@gmail.com",
"color": "#827718",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg"
},
"resolved": false,
"assignee": null,
"assigned_by": null,
"reactions": [],
"date": "1568036964079"
}
]
}
### Get List Comments [GET /list/{list_id}/comment]
+ Parameters
+ list_id: 124 (number)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"comments": [
{
"id": "462",
"comment": [
{
"text": "List comment content"
}
],
"comment_text": "List comment content",
"user": {
"id": 183,
"username": "John Doe",
"initials": "JD",
"email": "johndoe@gmail.com",
"color": "#827718",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg"
},
"resolved": false,
"assignee": {
"id": 183,
"username": "John Doe",
"initials": "JD",
"email": "johndoe@gmail.com",
"color": "#827718",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg"
},
"assigned_by": {
"id": 183,
"username": "John Doe",
"initials": "JD",
"email": "johndoe@gmail.com",
"color": "#827718",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg"
},
"reactions": [],
"date": "1568036964079"
}
]
}
### Update Comment [PUT /comment/{comment_id}]
+ Parameters
+ comment_id: 456 (number)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"comment_text": "Updated comment text"
"assignee": 183,
"resolved": true
}
+ Response 200 (application/json)
{}
### Delete Comment [DELETE /comment/{comment_id}]
+ Parameters
+ comment_id: 456 (number)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{}
## Custom Fields [/fields]
#### Field Types
Below are a list of field types that are available for you to use with the public API. For most use cases, you will use the `string` value to specify a type, such as `drop_down` or `number`. In a few instances, you may be returned an `integer` value. A map to each for each type is provided below.
```json
{
"url": 0,
"drop_down": 1,
"email": 2,
"phone": 3,
"date": 4,
"text": 5,
"checkbox": 6,
"number": 7,
"currency": 8,
"tasks": 9,
"users": 10,
"emoji": 11,
"labels": 13,
"automatic_progress": 14,
"manual_progress": 15,
"short_text": 16
}
```
*Note* - In the ClickUp UI, the `text` is displayed as "Long Text" and `short_text` is displayed as "Text".
#### The Field Object
```json
{
"id": "5dc86497-098d-4bb0-87d6-cf28e43812e7",
"name": "Text Field",
"type": "text",
"type_config": {},
"date_created": "1577378759142",
"hide_from_guests": false
}
```
#### Type Config
The `type_config` property is used to set configurations that are specific to a certain field type.
##### Drop Down
The drop down options exist in the `options` array, their order is determined by their array index. A `placeholder` value (string) and `default` option are available, but are not currently in use on the front end.
```json
{
"name": "My Drop Down Field",
"type": "drop_down",
"type_config": {
"default": 0,
"placeholder": "Select a value",
"options": [
{
"id": "UUID",
"name": "Option 1",
"color": "#FFFFF"
},
{
"id": "UUID",
"name": "Option 2",
"color": "#000000"
}
]
}
}
```
##### Currency
The `default` option is available, but not currently in use by the FE.
```json
{
"name": "My Currency Field",
"type": "currency",
"type_config": {
"precision": 2,
"currency_type": "USD",
"default": 10
}
}
```
##### Emoji
The `code_point` property must be a valid Unicode **emoji** code point value, many times written like `U+1f613`. Please omit the `U+` and only pass the hex value of the code point as a string. The `count` property denotes how many emoji values the rating can hold (min 1, max 5).
```json
{
"name": "My Emoji Rating Field",
"type": "emoji",
"type_config": {
"code_point": "1f613",
"count": 5
}
}
```
##### Labels
Labels is very similar to drop down, except you can set multiple option values.
```json
{
"name": "My Label Field",
"type": "labels",
"type_config": {
"options": [
{
"id": "UUID",
"label": "Label 1",
"color": "#123456"
},
{
"id": "UUID",
"label": "Label 2",
"color": "#FFFFFF"
}
]
}
}
```
##### Automatic Progress
```json
{
"name": "Automatic Progress Bar",
"type": "progress",
"type_config": {
"method": "automatic",
"tracking": {
"subtasks": true,
"assigned_comments": true,
"checklists": true
}
}
}
```
##### Manual Progress
```json
{
"name": "Manual Progress Bar",
"type": "progress",
"type_config": {
"method": "manual",
"start": 0,
"end": 100
}
}
```
#### Field Values
To set a field value on a task use the route `POST /api/v2/{{task_id}}/field/{{field_id}}`. The request will always require the body `{ value: ... }` with the type of value being dependent on what type of field it is.
##### Url
The value must be a string and a valid url
```json
{ "value": "https://clickup.com" }
```
##### Drop Down
The value must be a UUID that matches the drop down option that you retrieve from `type_config`
```json
{ "value": "UUID" }
```
##### Email
The value must be a string and a valid email.
```json
{ "value": "lana@clickup.com" }
```
##### Phone
The value must be a string and a valid phone number with country code.
```json
{ "value": "+1 123 456 7890" }
```
##### Date
The value must be posix
```json
{ "value": 15867095896 }
```
##### Text
The value must be a string
```json
{ "value": "Some text" }
```
##### Checkbox
The value must be a boolean
```json
{ "value": true }
```
##### Number
The value must be a number
```json
{ "value": -28 }
```
##### Currency
The value must be a number.
```json
{ "value": 80000 }
```
##### Tasks
The value must be an object with the following format. The task_ids in `add` will get added to the field, and the task_ids in `rem` will be removed. The user must have access to all of the tasks in the request.
```json
{
"value": {
"add": ["wmq3", "qt15"],
"rem": ["wxm7"]
}
}
```
##### Users
The value must be an object with the following format. The users in `add` will get added to the field, and the users in `rem` will be removed.
```json
{
"value": {
"add": [184, 193],
"rem": [183]
}
}
```
##### Emoji
The value must be an integer that meets the following condition: `0 <= value >= field.type_config.count`.
```json
{
"value": 4
}
```
##### Automatic Progress
Task value is automatically calculated for each task, trying to set a value will error.
##### Manual Progress
If the field is manual progress, the value must be and object with the **current** value of the progress. For example, if your start and end is `10` and `30` respectively, you would need to pass `20` to make the progress bar at `50%`.
```json
{
"value": {
"current": 20
}
}
```
##### Labels
The value must be an object with the following format. The UUID's for each label must come from the field's type_config. Any labels that currently exist will be overridden.
```json
{
"value": ["UUID_1", "UUID_2"]
}
```
### Get Accessible Custom Fields [GET /list/{list_id}/field]
+ Parameters
+ list_id: 123 (number)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Response 200 (application/json)
{
"fields": [
{
"id": "03efda77-c7a0-42d3-8afd-fd546353c2f5",
"name": "Text Field",
"type": "text",
"type_config": {},
"date_created": "1566400407303",
"hide_from_guests": false
},
{
"id": "0a52c486-5f05-403b-b4fd-c512ff05131c",
"name": "Number Field",
"type": "number",
"type_config": {},
"date_created": "1565993269460",
"hide_from_guests": false
},
{
"id": "0c7e8f5c-557b-4128-bf37-29e2fe5bb7f9",
"name": "Label Field",
"type": "labels",
"type_config": {
"options": [{
"id": "fb332c98-d7bc-4ee8-a3bd-b5ffaff98c3c",
"label": "one",
"color": null
},
{
"id": "2b0c058c-2f41-4f61-8fc8-f9ea426e8c0e",
"label": "two",
"color": null
},
{
"id": "75e10f4b-b4cc-4ef9-94dc-230d19ef4fa6",
"label": "three",
"color": null
}
]
},
"date_created": "1558567802303",
"hide_from_guests": false
},
{
"id": "10916331-1903-4026-886f-891f29aa9fb6",
"name": "Checkbox Field",
"type": "checkbox",
"type_config": {},
"date_created": "1562944066529",
"hide_from_guests": false
},
{
"id": "2e3d4145-9a54-4d0a-9446-78ba595b327f",
"name": "Date Field",
"type": "date",
"type_config": {},
"date_created": "1565886951888",
"hide_from_guests": false
},
{
"id": "31b84286-635a-45fd-bbd5-3814fbbb08bb",
"name": "User Field",
"type": "users",
"type_config": {},
"date_created": "1565962775482",
"hide_from_guests": false
},
{
"id": "5cf8a44f-4421-4982-97d7-3e2209be2df4",
"name": "Currency Field",
"type": "currency",
"type_config": {
"default": null,
"precision": 2,
"currency_type": "USD"
},
"date_created": "1565993263347",
"hide_from_guests": false
},
{
"id": "790e5051-7923-43e8-8f05-2e4940557bd8",
"name": "Phone Field",
"type": "phone",
"type_config": {},
"date_created": "1563545189836",
"hide_from_guests": false
},
{
"id": "8551901a-3eca-4193-b691-e0e3c9f94ff3",
"name": "Drop Down Field",
"type": "drop_down",
"type_config": {
"default": 0,
"placeholder": null,
"options": [{
"id": "5f6ce650-cb1d-437d-8373-72578a092510",
"name": "1",
"value": 1,
"type": "numeric",
"orderindex": 0,
"color": null
},
{
"id": "89707879-c4e1-44b9-9cc0-be7c16ee6681",
"name": "2",
"value": 2,
"type": "numeric",
"orderindex": 1,
"color": null
}
]
},
"date_created": "1565993237778",
"hide_from_guests": false
},
{
"id": "9b45e079-f647-4556-bdd9-a7589ccd2530",
"name": "Manual Progress Field",
"type": "manual_progress",
"type_config": {
"end": 100,
"start": 0
},
"date_created": "1565993299379",
"hide_from_guests": false
},
{
"id": "b5be3c35-4fe1-429e-affe-4318de213efe",
"name": "Emoji (Rating) Field",
"type": "emoji",
"type_config": {
"count": 5,
"code_point": "1f383"
},
"date_created": "1565993309955",
"hide_from_guests": false
},
{
"id": "ba0d56f6-f1ba-4015-b726-12c013bb8ac6",
"name": "Automatic Progress Field",
"type": "automatic_progress",
"type_config": {
"tracking": {
"subtasks": true,
"checklists": true,
"assigned_comments": true
},
"complete_on": 3
},
"date_created": "1566405066706",
"hide_from_guests": false
},
{
"id": "decb4a8a-6120-46b0-9cbb-66f3ee1de3c5",
"name": "Email Field",
"type": "email",
"type_config": {},
"date_created": "1565993242649",
"hide_from_guests": false
},
{
"id": "e438e267-4f9f-4b54-b937-cbdb0e0369dd",
"name": "URL Field",
"type": "url",
"type_config": {},
"date_created": "1559001282914",
"hide_from_guests": false
}
]
}
### Set Custom Field Value [POST /task/{task_id}/field/{field_id}]
+ Parameters
+ task_id: 9hv (string)
+ field_id: b955c4dc-b8a8-48d8-a0c6-b4200788a683 (uuid)
+ Request
The accessible fields can be found on the task object from the get task route. This is where you can retrieve the `field_id`.
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"value": 80
}
+ Response 200 (application/json)
{}
### Remove Custom Field Value [DELETE /task/{task_id}/field/{field_id}]
+ Parameters
+ task_id: 9hv (string)
+ field_id: b955c4dc-b8a8-48d8-a0c6-b4200788a683 (uuid)
+ Request
The accessible fields can be found on the task object from the get task route. This is where you can retrieve the `field_id`.
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{}
## Dependencies [/dependency]
### Add Dependency [POST /task/{task_id}/dependency]
+ Parameters
+ task_id: 9hv (string)
+ Request
To create a waiting on dependency, pass the property `depends_on` in the body. To create a blocking dependency, pass the property `dependency_of`. Both can not be passed in the same request.
+ Headers
Authorization: "access_token"
+ Body
{
"depends_on": "9hw"
}
+ Response 200 (application/json)
{}
### Delete Dependency [DELETE /task/{task_id}/dependency{?depends_on,dependency_of}]
+ Parameters
+ task_id: 9hv (string)
+ depends_on: 9hz (string)
+ dependency_of: 9hz (string)
+ Request
One and only one of `depends_on` or `dependency_of` must be passed in the query params.
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{}
## Folders [/folder]
### Create Folder [POST /space/{space_id}/folder]
+ Parameters
+ space_id: 789 (number)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "New Folder Name"
}
+ Response 200 (application/json)
{
"id": "457",
"name": "New Folder Name",
"orderindex": 0,
"override_statuses": false,
"hidden": false,
"space": {
"id": "789",
"name": "Space Name",
"access": true
},
"task_count": "0"
}
### Update Folder [PUT /folder/{folder_id}]
+ Parameters
+ folder_id: 457 (number)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "Updated Folder Name"
}
+ Response 200 (application/json)
{
"id": "457",
"name": "Updated Folder Name",
"orderindex": 0,
"override_statuses": false,
"hidden": false,
"space": {
"id": "789",
"name": "Space Name",
"access": true
},
"task_count": "0"
}
### Delete Folder [DELETE /folder/{folder_id}]
+ Parameters
+ folder_id: 457 (number)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{}
### Get Folders [GET /space/{space_id}/folder{?archived}]
+ Parameters
+ space_id: 789 (number)
+ archived: false (boolean)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
[
{
"id": "457",
"name": "Updated Folder Name",
"orderindex": 0,
"override_statuses": false,
"hidden": false,
"space": {
"id": "789",
"name": "Space Name",
"access": true
},
"task_count": "0",
"lists": []
},
{
"id": "458",
"name": "Second Folder Name",
"orderindex": 1,
"override_statuses": false,
"hidden": false,
"space": {
"id": "789",
"name": "Space Name",
"access": true
},
"task_count": "0",
"lists": []
}
]
### Get Folder [GET /folder/{folder_id}]
+ Parameters
+ folder_id: 457 (number)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"id": "457",
"name": "Updated Folder Name",
"orderindex": 0,
"override_statuses": false,
"hidden": false,
"space": {
"id": "789",
"name": "Space Name",
"access": true
},
"task_count": "0",
"lists": []
}
## Goals [/goals]
### Create Goal [POST /team/{team_id}/goal]
+ Parameters
+ team_id: 512 (number)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "Goal Name",
"due_date": 1568036964079,
"description": "Goal Description",
"multiple_owners": true,
"owners": [183],
"color": "#32a852"
}
+ Response 200 (application/json)
{
"goal": {
"id": "e53a033c-900e-462d-a849-4a216b06d930",
"name": "Goal Name",
"team_id": "512",
"date_created": "1568044355026",
"start_date": null,
"due_date": "1568036964079",
"description": "Goal Description",
"private": false,
"archived": false,
"creator": 183,
"color": "#32a852",
"pretty_id": "6",
"multiple_owners": true,
"folder_id": null,
"members": [],
"owners": [
{
"id": 183,
"username": "John Doe",
"initials": "JD",
"email": "johndoe@gmail.com",
"color": "#827718",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg"
}
],
"key_results": [],
"percent_completed": 0,
"history": [],
"pretty_url": "https://app.clickup.com/512/goals/6"
}
}
### Update Goal [PUT /goal/{goal_id}]
+ Parameters
+ goal_id: e53a033c-900e-462d-a849-4a216b06d930 (uuid)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "Updated Goal Name",
"due_date": 1568036964079,
"description": "Updated Goal Description",
"rem_owners": [183],
"add_owners": [182]
"color": "#32a852"
}
+ Response 200 (application/json)
{
"goal": {
"id": "e53a033c-900e-462d-a849-4a216b06d930",
"name": "Updated Goal Name",
"team_id": "512",
"date_created": "1568044355026",
"start_date": null,
"due_date": "1568036964079",
"description": "Updated Goal Description",
"private": false,
"archived": false,
"creator": 183,
"color": "#32a852",
"pretty_id": "6",
"multiple_owners": true,
"folder_id": null,
"members": [],
"owners": [
{
"id": 182,
"username": "Jane Doe",
"initials": "JD",
"email": "janedoe@gmail.com",
"color": "#827718",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/182_abc.jpg"
}
],
"key_results": [],
"percent_completed": 0,
"history": [],
"pretty_url": "https://app.clickup.com/512/goals/6"
}
}
### Delete Goal [DELETE /goal/{goal_id}]
+ Parameters
+ goal_id: e53a033c-900e-462d-a849-4a216b06d930 (uuid)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Response 200 (application/json)
{}
### Get Goals [GET /team/{team_id}/goal]
+ Parameters
+ team_id: 512 (number)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"goals": [
{
"id": "e53a033c-900e-462d-a849-4a216b06d930",
"name": "Updated Goal Name",
"team_id": "512",
"date_created": "1568044355026",
"start_date": null,
"due_date": "1568036964079",
"description": "Updated Goal Description",
"private": false,
"archived": false,
"creator": 183,
"color": "#32a852",
"pretty_id": "6",
"multiple_owners": true,
"folder_id": null,
"members": [],
"owners": [
{
"id": 182,
"username": "Jane Doe",
"initials": "JD",
"email": "janedoe@gmail.com",
"color": "#827718",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/182_abc.jpg"
}
],
"key_results": [],
"percent_completed": 0,
"history": [],
"pretty_url": "https://app.clickup.com/512/goals/6"
}
],
"folders": [
{
"id": "05921253-7737-44af-a1aa-36fd11244e6f",
"name": "Goal Folder",
"team_id": "512",
"private": true,
"date_created": "1548802674671",
"creator": 182,
"goal_count": 0,
"members": [
{
"id": 182,
"username": "Jane Doe",
"initials": "JD",
"email": "janedoe@gmail.com",
"color": "#827718",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/182_abc.jpg"
}
],
"goals": []
}
]
}
### Get Goal [GET /goal/{goal_id}]
+ Parameters
+ goal_id: e53a033c-900e-462d-a849-4a216b06d930 (uuid)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"goal": {
"id": "e53a033c-900e-462d-a849-4a216b06d930",
"name": "Updated Goal Name",
"team_id": "512",
"date_created": "1568044355026",
"start_date": null,
"due_date": "1568036964079",
"description": "Updated Goal Description",
"private": false,
"archived": false,
"creator": 183,
"color": "#32a852",
"pretty_id": "6",
"multiple_owners": true,
"folder_id": null,
"members": [],
"owners": [
{
"id": 182,
"username": "Jane Doe",
"initials": "JD",
"email": "janedoe@gmail.com",
"color": "#827718",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/182_abc.jpg"
}
],
"key_results": [],
"percent_completed": 0,
"history": [],
"pretty_url": "https://app.clickup.com/512/goals/6"
}
}
### Create Key Result [POST /goal/{goal_id}/key_result]
+ Parameters
+ goal_id: e53a033c-900e-462d-a849-4a216b06d930 (uuid)
+ Request
Key result types can be `number`, `currency`, `boolean`, `percentage`, or `automatic`. The task ID's array and list ID's array can be used to attach resources to the goal.
+ Headers
Authoriation: "access_token"
Content-Type: application/json
+ Body
{
"name": "New Key Result Name",
"owners": [183],
"type": "number",
"steps_start": 0,
"steps_end": 10,
"unit": "km",
"task_ids": [],
"list_ids": []
}
+ Response 200 (application/json)
{
"key_result": {
"id": "947d46ed-8480-49bc-8c57-e569747efe93",
"goal_id": "e53a033c-900e-462d-a849-4a216b06d930",
"name": "New Key Result Name",
"type": "number",
"unit": "km",
"creator": 183,
"date_created": "1568062902048",
"goal_pretty_id": "6",
"percent_completed": null,
"completed": false,
"task_ids": [],
"subcategory_ids": [],
"owners": [
{
"id": 183,
"username": "John Doe",
"email": "example@email.com",
"color": "#827718",
"profilePicture": "https://dev-attachments-public.clickup.com/profilePictures/183_nx1.jpg",
"initials": "JK"
}
],
"last_action": {
"id": "d3183d0f-5cbd-4158-b015-71465f1df269",
"key_result_id": "947d46ed-8480-49bc-8c57-e569747efe93",
"userid": 183,
"date_modified": "1568062902048",
"steps_taken": null,
"note": "Created Key Result",
"steps_before": null,
"steps_current": null
}
}
}
### Edit Key Result [PUT /key_result/{key_result_id}]
+ Parameters
+ key_result_id: 947d46ed-8480-49bc-8c57-e569747efe93 (uuid)
+ Request
All properties available in the create key result route may also be used along with the additional properties below.
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"steps_current": 5,
"note": "Target achieved"
}
+ Response 200 (application/json)
{
"key_result": {
"id": "947d46ed-8480-49bc-8c57-e569747efe93",
"goal_id": "e53a033c-900e-462d-a849-4a216b06d930",
"name": "New Key Result Name",
"type": "number",
"unit": "km",
"creator": 183,
"date_created": "1568062902048",
"goal_pretty_id": "6",
"percent_completed": null,
"completed": false,
"task_ids": [],
"subcategory_ids": [],
"owners": [
{
"id": 183,
"username": "John Doe",
"email": "example@email.com",
"color": "#827718",
"profilePicture": "https://dev-attachments-public.clickup.com/profilePictures/183_nx1.jpg",
"initials": "JK"
}
],
"last_action": {
"id": "e889858b-a023-46cc-968a-cac32fd04c1e",
"key_result_id": "19c7a55e-537e-4bc9-b741-08df05a5bda8",
"userid": 183,
"date_modified": "1568122776851",
"steps_taken": null,
"note": "Target achieved",
"steps_before": null,
"steps_current": null,
"steps_before_float": 0,
"steps_taken_float": 5,
"steps_current_float": null
}
}
}
### Delete Key Result [DELETE /key_result/{key_result_id}]
+ Parameters
+ key_result_id: 947d46ed-8480-49bc-8c57-e569747efe93 (uuid)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{}
## Guests [/guests]
**_Note:_ The following guest routes are only available to enterprise teams**
### Invite Guest To Team [POST /team/{team_id}/guest]
+ Parameters
+ team_id: 333 (number)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"email": "guest@example.com",
"can_edit_tags": true,
"can_see_time_spent": true,
"can_see_time_estimated": true
}
+ Response 200 (application/json)
{
"team": {
"id": "333",
"name": "Team Name",
"color": "#8D00D4",
"avatar": null,
"members": [
// ... existing team members
{
"user": {
"id": 184,
"username": null,
"email": "guest@example.com",
"color": null,
"profilePicture": null,
"initials": "G",
"role": 4,
"last_active": null,
"date_joined": null,
"date_invited": "1583358383412"
},
"invited_by": {
"id": 183,
"color": "#827718",
"username": "Jerry Krusinski",
"email": "jerry@example.com",
"initials": "JK",
"profilePicture": "https://dev-attachments-public.clickup.com/profilePictures/183_nx1.jpg"
},
"can_see_time_spent": true,
"can_see_time_estimated": true,
"can_edit_tags": true
}
]
}
}
### Remove Guest From Team [DELETE /team/{team_id}/guest/{guest_id}]
+ Parameters
+ team_id: 333 (number)
+ guest_id: 403 (number)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"team": {
"id": "333",
"name": "Team Name",
"color": "#8D00D4",
"avatar": null,
"members": [
// ... existing team members
]
}
}
### Get Guest [GET /team/{team_id}/guest/{guest_id}]
+ Parameters
+ team_id: 333 (number)
+ guest_id: 403 (number)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"guest": {
"user": {
"id": 184,
"username": null,
"email": "guest@example.com",
"color": null,
"profilePicture": null,
"initials": "G",
"role": 4,
"last_active": null,
"date_joined": null,
"date_invited": "1583358383412"
},
"invited_by": {
"id": 183,
"color": "#827718",
"username": "Jerry Krusinski",
"email": "jerry@example.com",
"initials": "JK",
"profilePicture": "https://dev-attachments-public.clickup.com/profilePictures/183_nx1.jpg"
},
"can_see_time_spent": true,
"can_see_time_estimated": true,
"can_edit_tags": true,
"shared": {
"tasks": [],
"lists": [],
"folders": []
}
}
}
### Add Guest To Task [POST /task/{task_id}/guest/{guest_id}]
+ Parameters
+ task_id: c04 (string)
+ guest_id: 403 (number)
+ Request
`permisson_level` can be `read`, `comment`, `edit`, or `create`
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"permission_level": "read"
}
+ Response 200 (application/json)
{
"guest": {
"user": {
"id": 184,
"username": null,
"email": "guest@example.com",
"color": null,
"profilePicture": null,
"initials": "G",
"role": 4,
"last_active": null,
"date_joined": null,
"date_invited": "1583358383412"
},
"invited_by": {
"id": 183,
"color": "#827718",
"username": "Jerry Krusinski",
"email": "jerry@example.com",
"initials": "JK",
"profilePicture": "https://dev-attachments-public.clickup.com/profilePictures/183_nx1.jpg"
},
"can_see_time_spent": true,
"can_see_time_estimated": true,
"can_edit_tags": true,
"shared": {
"tasks": [
{
"id": "c04",
"name": "Task Name",
"status": {
"status": "Open",
"color": "#d3d3d3",
"type": "open",
"orderindex": 0
},
"orderindex": "0",
"date_created": "1574718405408",
"date_updated": "1574722145869",
"date_closed": null,
"archived": false,
"creator": {
"id": 183,
"username": "Jerry Krusinski",
"color": "#827718",
"profilePicture": "https://dev-attachments-public.clickup.com/profilePictures/183_nx1.jpg"
},
"assignees": [],
"checklists": [],
"tags": [],
"parent": null,
"priority": {
"id": "1",
"priority": "urgent",
"color": "#f50000",
"orderindex": "1"
},
"due_date": "1508369194377",
"start_date": null,
"points": null,
"time_estimate": null,
"custom_fields": [],
"dependencies": [],
"team_id": "108",
"url": "https://app.clickup.com/t/c04",
"permission_level": "read",
"list": {
"id": "1752",
"name": "Shared with me",
"access": false
},
"folder": {
"id": "1217",
"name": "Shared with me",
"hidden": false,
"access": false
},
"space": {
"id": "380"
}
}
],
"lists": [],
"folders": []
}
}
}
### Remove Guest From Task [DELETE /task/{task_id}/guest/{guest_id}]
+ Parameters
+ task_id: c04 (string)
+ guest_id: 403 (number)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"guest": {
"user": {
"id": 184,
"username": null,
"email": "guest@example.com",
"color": null,
"profilePicture": null,
"initials": "G",
"role": 4,
"last_active": null,
"date_joined": null,
"date_invited": "1583358383412"
},
"invited_by": {
"id": 183,
"color": "#827718",
"username": "Jerry Krusinski",
"email": "jerry@example.com",
"initials": "JK",
"profilePicture": "https://dev-attachments-public.clickup.com/profilePictures/183_nx1.jpg"
},
"can_see_time_spent": true,
"can_see_time_estimated": true,
"can_edit_tags": true,
"shared": {
"tasks": [],
"lists": [],
"folders": []
}
}
}
### Add Guest To List [POST /list/{list_id}/guest/{guest_id}]
+ Parameters
+ list_id: 1427 (number)
+ guest_id: 403 (number)
+ Request
`permisson_level` can be `read`, `comment`, `edit`, or `create`
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"permission_level": "read"
}
+ Response 200 (application/json)
{
"guest": {
"user": {
"id": 184,
"username": null,
"email": "guest@example.com",
"color": null,
"profilePicture": null,
"initials": "G",
"role": 4,
"last_active": null,
"date_joined": null,
"date_invited": "1583358383412"
},
"invited_by": {
"id": 183,
"color": "#827718",
"username": "Jerry Krusinski",
"email": "jerry@example.com",
"initials": "JK",
"profilePicture": "https://dev-attachments-public.clickup.com/profilePictures/183_nx1.jpg"
},
"can_see_time_spent": true,
"can_see_time_estimated": true,
"can_edit_tags": true,
"shared": {
"tasks": [],
"lists": [
{
"id": "1427",
"name": "List Name",
"orderindex": 1,
"status": null,
"priority": null,
"assignee": null,
"task_count": "5",
"due_date": null,
"start_date": null,
"archived": false,
"override_statuses": true,
"statuses": [
{
"status": "Open",
"orderindex": 0,
"color": "#d3d3d3",
"type": "open"
},
{
"status": "Closed",
"orderindex": 5,
"color": "#6bc950",
"type": "closed"
}
],
"permission_level": "read"
}
],
"folders": []
}
}
}
### Remove Guest From List [DELETE /list/{list_id}/guest/{guest_id}]
+ Parameters
+ list_id: 1427 (number)
+ guest_id: 403 (number)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"guest": {
"user": {
"id": 184,
"username": null,
"email": "guest@example.com",
"color": null,
"profilePicture": null,
"initials": "G",
"role": 4,
"last_active": null,
"date_joined": null,
"date_invited": "1583358383412"
},
"invited_by": {
"id": 183,
"color": "#827718",
"username": "Jerry Krusinski",
"email": "jerry@example.com",
"initials": "JK",
"profilePicture": "https://dev-attachments-public.clickup.com/profilePictures/183_nx1.jpg"
},
"can_see_time_spent": true,
"can_see_time_estimated": true,
"can_edit_tags": true,
"shared": {
"tasks": [],
"lists": [],
"folders": []
}
}
}
### Add Guest To Folder [POST /folder/{folder_id}/guest/{guest_id}]
+ Parameters
+ folder_id: 1057 (number)
+ guest_id: 403 (number)
+ Request
`permisson_level` can be `read`, `comment`, `edit`, or `create`
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"permission_level": "read"
}
+ Response 200 (application/json)
{
"guest": {
"user": {
"id": 184,
"username": null,
"email": "guest@example.com",
"color": null,
"profilePicture": null,
"initials": "G",
"role": 4,
"last_active": null,
"date_joined": null,
"date_invited": "1583358383412"
},
"invited_by": {
"id": 183,
"color": "#827718",
"username": "Jerry Krusinski",
"email": "jerry@example.com",
"initials": "JK",
"profilePicture": "https://dev-attachments-public.clickup.com/profilePictures/183_nx1.jpg"
},
"can_see_time_spent": true,
"can_see_time_estimated": true,
"can_edit_tags": true,
"shared": {
"tasks": [],
"lists": [],
"folders": [
{
"id": "1057",
"name": "Folder Name",
"orderindex": 5,
"override_statuses": true,
"hidden": false,
"task_count": "20",
"archived": false,
"statuses": [
{
"status": "Open",
"orderindex": 0,
"color": "#d3d3d3",
"type": "open"
},
{
"status": "Closed",
"orderindex": 5,
"color": "#6bc950",
"type": "closed"
}
],
"lists": [],
"permission_level": "read"
}
]
}
}
}
### Remove Guest From Folder [DELETE /folder/{folder_id}/guest/{guest_id}]
+ Parameters
+ folder_id: 1057 (number)
+ guest_id: 403 (number)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"guest": {
"user": {
"id": 184,
"username": null,
"email": "guest@example.com",
"color": null,
"profilePicture": null,
"initials": "G",
"role": 4,
"last_active": null,
"date_joined": null,
"date_invited": "1583358383412"
},
"invited_by": {
"id": 183,
"color": "#827718",
"username": "Jerry Krusinski",
"email": "jerry@example.com",
"initials": "JK",
"profilePicture": "https://dev-attachments-public.clickup.com/profilePictures/183_nx1.jpg"
},
"can_see_time_spent": true,
"can_see_time_estimated": true,
"can_edit_tags": true,
"shared": {
"tasks": [],
"lists": [],
"folders": []
}
}
}
## Lists [/lists]
### Create List [POST /folder/{folder_id}/list]
+ Parameters
+ folder_id: 456 (number)
+ Request
`assignee` is a userid of the assignee to be added to this task.
`priority` is an integer mapping as 1 : Urgent, 2 : High, 3 : Normal, 4 : Low.
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "New List Name",
"content": "New List Content",
"due_date": 1567780450202,
"due_date_time": false,
"priority": 1,
"assignee": 183,
"status": "red"
}
+ Response 200 (application/json)
{
"id": "124",
"name": "New List Name",
"orderindex": 1,
"content": "New List Content",
"status": {
"status": "red",
"color": "#e50000",
"hide_label": true
},
"priority": {
"priority": "urgent",
"color": "#f50000"
},
"assignee": {
"id": 183,
"color": "#827718",
"username": "Jerry Krusinski",
"initials": "JK",
"profilePicture": "https://dev-attachments-public.clickup.com/profilePictures/183_nx1.jpg"
},
"task_count": null,
"due_date": "1567780450202",
"due_date_time": false,
"start_date": null,
"start_date_time": null,
"folder": {
"id": "456",
"name": "Folder Name",
"hidden": false,
"access": true
},
"space": {
"id": "789",
"name": "Space Name",
"access": true
},
"inbound_address": "add.task.1389.ac725f.31518a6a-05bb-4997-92a6-1dcfe2f527ca@tasks.clickup.com"
}
### Create Folderless List [POST /space/{space_id}/list]
+ Parameters
+ space_id: 789 (number)
+ Request
`assignee` is a userid of the assignee to be added to this task.
`priority` is an integer mapping as 1 : Urgent, 2 : High, 3 : Normal, 4 : Low.
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "New List Name",
"content": "New List Content",
"due_date": 1567780450202,
"due_date_time": false,
"priority": 1,
"assignee": 183,
"status": "red"
}
+ Response 200 (application/json)
{
"id": "124",
"name": "New List Name",
"orderindex": 1,
"content": "New List Content",
"status": {
"status": "red",
"color": "#e50000",
"hide_label": true
},
"priority": {
"priority": "urgent",
"color": "#f50000"
},
"assignee": {
"id": 183,
"color": "#827718",
"username": "Jerry Krusinski",
"initials": "JK",
"profilePicture": "https://dev-attachments-public.clickup.com/profilePictures/183_nx1.jpg"
},
"task_count": null,
"due_date": "1567780450202",
"due_date_time": false,
"start_date": null,
"start_date_time": null,
"folder": {
"id": "457",
"name": "hidden",
"hidden": true,
"access": true
},
"space": {
"id": "789",
"name": "Space Name",
"access": true
},
"inbound_address": "add.task.1389.ac725f.31518a6a-05bb-4997-92a6-1dcfe2f527ca@tasks.clickup.com"
}
### Update List [PUT /list/{list_id}]
+ Parameters
+ list_id: 124 (string)
+ Request
Only pass the properties you want to update. It is unnessary to pass the entire list object. `assignee` is a userid of the assignee to be added to this task.
`priority` is an integer mapping as 1 : Urgent, 2 : High, 3 : Normal, 4 : Low.
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "Updated List Name",
"content": "Updated List Content",
"due_date": 1567780450202,
"due_date_time": true,
"priority": 2,
"assignee": "none",
"unset_status": true
}
+ Response 200 (application/json)
{
"id": "124",
"name": "Updated List Name",
"orderindex": 1,
"content": "Updated List Content",
"status": {
"status": "red",
"color": "#e50000",
"hide_label": true
},
"priority": {
"priority": "high",
"color": "#f50000"
},
"assignee": null,
"task_count": null,
"due_date": "1567780450202",
"due_date_time": true,
"start_date": null,
"start_date_time": null,
"folder": {
"id": "456",
"name": "Folder Name",
"hidden": false,
"access": true
},
"space": {
"id": "789",
"name": "Space Name",
"access": true
},
"inbound_address": "add.task.1389.ac725f.31518a6a-05bb-4997-92a6-1dcfe2f527ca@tasks.clickup.com"
}
### Delete List [DELETE /list/{list_id}]
+ Parameters
+ list_id: 124 (number)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Response 200 (application/json)
{}
### Get Lists [GET /folder/{folder_id}/list{?archived}]
+ Parameters
+ folder_id: 456 (number)
+ archived: false (boolean)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"lists": [
{
"id": "124",
"name": "Updated List Name",
"orderindex": 1,
"content": "Updated List Content",
"status": {
"status": "red",
"color": "#e50000",
"hide_label": true
},
"priority": {
"priority": "high",
"color": "#f50000"
},
"assignee": null,
"task_count": null,
"due_date": "1567780450202",
"due_date_time": true,
"start_date": null,
"start_date_time": null,
"folder": {
"id": "456",
"name": "Folder Name",
"hidden": false,
"access": true
},
"space": {
"id": "789",
"name": "Space Name",
"access": true
},
"inbound_address": "add.task.124.ac725f.31518a6a-05bb-4997-92a6-1dcfe2f527ca@tasks.clickup.com"
},
{
"id": "125",
"name": "Second List",
"orderindex": 1,
"content": "Second List Content",
"status": null,
"priority": null,
"assignee": null,
"task_count": null,
"due_date": null,
"due_date_time": null,
"start_date": null,
"start_date_time": null,
"folder": {
"id": "456",
"name": "Folder Name",
"hidden": false,
"access": true
},
"space": {
"id": "789",
"name": "Space Name",
"access": true
},
"inbound_address": "add.task.125.ac725f.31518a6a-05bb-4997-92a6-1dcfe2f527ca@tasks.clickup.com"
}
]
}
### Get Folderless Lists [GET /space/{space_id}/list{?archived}]
+ Parameters
+ space_id: 789 (number)
+ archived: false (boolean)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"lists": [
{
"id": "124",
"name": "Updated List Name",
"orderindex": 1,
"content": "Updated List Content",
"status": {
"status": "red",
"color": "#e50000",
"hide_label": true
},
"priority": {
"priority": "high",
"color": "#f50000"
},
"assignee": null,
"task_count": null,
"due_date": "1567780450202",
"due_date_time": true,
"start_date": null,
"start_date_time": null,
"folder": {
"id": "457",
"name": "hidden",
"hidden": true,
"access": true
},
"space": {
"id": "789",
"name": "Space Name",
"access": true
},
"inbound_address": "add.task.124.ac725f.31518a6a-05bb-4997-92a6-1dcfe2f527ca@tasks.clickup.com"
},
{
"id": "125",
"name": "Second List",
"orderindex": 1,
"content": "Second List Content",
"status": null,
"priority": null,
"assignee": null,
"task_count": null,
"due_date": null,
"due_date_time": null,
"start_date": null,
"start_date_time": null,
"folder": {
"id": "457",
"name": "hidden",
"hidden": true,
"access": true
},
"space": {
"id": "789",
"name": "Space Name",
"access": true
},
"inbound_address": "add.task.125.ac725f.31518a6a-05bb-4997-92a6-1dcfe2f527ca@tasks.clickup.com"
}
]
}
### Get List [GET /list/{list_id}]
+ Parameters
+ list_id: 124 (number)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (applicaton/json)
{
"id": "124",
"name": "Updated List Name",
"orderindex": 1,
"content": "Updated List Content",
"status": {
"status": "red",
"color": "#e50000",
"hide_label": true
},
"priority": {
"priority": "high",
"color": "#f50000"
},
"assignee": null,
"task_count": null,
"due_date": "1567780450202",
"due_date_time": true,
"start_date": null,
"start_date_time": null,
"folder": {
"id": "456",
"name": "Folder Name",
"hidden": false,
"access": true
},
"space": {
"id": "789",
"name": "Space Name",
"access": true
},
"inbound_address": "add.task.124.ac725f.31518a6a-05bb-4997-92a6-1dcfe2f527ca@tasks.clickup.com"
}
## Members [/members]
### Get Task Members [GET /task/{task_id}/member]
+ Parameter
+ task_id: 9hz (string)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"members": [
{
"id": 812,
"username": "John Doe",
"email": "john@example.com",
"color": "#FFFFFF",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/812_nx1.jpg",
"initials": "JD",
"role": 2
},
{
"id": 813,
"username": "Jane Doe",
"email": "jane@example.com",
"color": null,
"profilePicture": "https://attachments-public.clickup.com/profilePictures/813_nx1.jpg",
"initials": "JD",
"role": 3
}
]
}
### Get List Members [GET /list/{list_id}/member]
+ Parameter
+ list_id: 123 (number)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"members": [
{
"id": 812,
"username": "John Doe",
"email": "john@example.com",
"color": "#FFFFFF",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/812_nx1.jpg",
"initials": "JD",
"role": 2
},
{
"id": 813,
"username": "Jane Doe",
"email": "jane@example.com",
"color": null,
"profilePicture": "https://attachments-public.clickup.com/profilePictures/813_nx1.jpg",
"initials": "JD",
"role": 3
}
]
}
## Shared Hierarchy [/share]
### Shared Hierarchy [GET /team/{team_id}/shared]
+ Parameter
+ team_id: 333 (number)
+ Request
Returns all resources you have access to where you don't have access to its parent. For example, if you have a access to a shared task, but don't have access to its parent list, it will come back in this request.
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"shared": {
"tasks": [],
"lists": [
{
"id": "1421",
"name": "Shared List",
"orderindex": 0,
"content": null,
"status": null,
"priority": null,
"assignee": null,
"task_count": "0",
"due_date": null,
"start_date": null,
"archived": false
}
],
"folders": [
{
"id": "1058",
"name": "Shared Folder",
"orderindex": 0,
"content": null,
"task_count": "0",
"due_date": null,
"archived": false
}
]
}
}
## Spaces [/space]
### Create Space [POST /team/{team_id}/space]
+ Parameters
+ team_id: 512 (number)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "New Space Name",
"multiple_assignees": true,
"features": {
"due_dates": {
"enabled": true,
"start_date": false,
"remap_due_dates": true,
"remap_closed_due_date": false
},
"time_tracking": {
"enabled": false
},
"tags": {
"enabled": true
},
"time_estimates": {
"enabled": true
},
"checklists": {
"enabled": true
},
"custom_fields": {
"enabled": true
},
"remap_dependencies": {
"enabled": true
},
"dependency_warning": {
"enabled": true
},
"portfolios": {
"enabled": true
}
}
}
+ Response 200 (application/json)
{
"id": "790",
"name": "New Space Name",
"private": false,
"statuses": [
{
"status": "to do",
"type": "open",
"orderindex": 0,
"color": "#d3d3d3"
},
{
"status": "complete",
"type": "closed",
"orderindex": 1,
"color": "#6bc950"
}
],
"multiple_assignees": true,
"features": {
"due_dates": {
"enabled": true,
"start_date": false,
"remap_due_dates": true,
"remap_closed_due_date": false
},
"time_tracking": {
"enabled": false
},
"tags": {
"enabled": true
},
"time_estimates": {
"enabled": true
},
"checklists": {
"enabled": true
},
"custom_fields": {
"enabled": true
},
"remap_dependencies": {
"enabled": true
},
"dependency_warning": {
"enabled": true
},
"portfolios": {
"enabled": true
}
}
}
### Update Space [PUT /space/{space_id}]
+ Parameters
+ space_id: 790 (number)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "Updated Space Name",
"multiple_assignees": false,
"features": {
"due_dates": {
"enabled": false,
"start_date": false,
"remap_due_dates": false,
"remap_closed_due_date": false
},
"time_tracking": {
"enabled": false
},
"tags": {
"enabled": false
},
"time_estimates": {
"enabled": false
},
"checklists": {
"enabled": true
},
"custom_fields": {
"enabled": true
},
"remap_dependencies": {
"enabled": false
},
"dependency_warning": {
"enabled": false
},
"portfolios": {
"enabled": false
}
}
}
+ Response 200 (application/json)
{
"id": "790",
"name": "Updated Space Name",
"private": false,
"statuses": [
{
"status": "to do",
"type": "open",
"orderindex": 0,
"color": "#d3d3d3"
},
{
"status": "complete",
"type": "closed",
"orderindex": 1,
"color": "#6bc950"
}
],
"multiple_assignees": false,
"features": {
"due_dates": {
"enabled": false,
"start_date": false,
"remap_due_dates": false,
"remap_closed_due_date": false
},
"time_tracking": {
"enabled": false
},
"tags": {
"enabled": false
},
"time_estimates": {
"enabled": false
},
"checklists": {
"enabled": true
},
"custom_fields": {
"enabled": true
},
"remap_dependencies": {
"enabled": false
},
"dependency_warning": {
"enabled": false
},
"portfolios": {
"enabled": false
}
}
}
### Delete Space [DELETE /space/{space_id}]
+ Parameters
+ space_id: 790 (number)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{}
### Get Spaces [GET /team/{team_id}/space{?archived}]
+ Parameters
+ team_id: 512 (number)
+ archived: false (boolean)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"spaces": [
{
"id": "790",
"name": "Updated Space Name",
"private": false,
"statuses": [
{
"status": "to do",
"type": "open",
"orderindex": 0,
"color": "#d3d3d3"
},
{
"status": "complete",
"type": "closed",
"orderindex": 1,
"color": "#6bc950"
}
],
"multiple_assignees": false,
"features": {
"due_dates": {
"enabled": false,
"start_date": false,
"remap_due_dates": false,
"remap_closed_due_date": false
},
"time_tracking": {
"enabled": false
},
"tags": {
"enabled": false
},
"time_estimates": {
"enabled": false
},
"checklists": {
"enabled": true
},
"custom_fields": {
"enabled": true
},
"remap_dependencies": {
"enabled": false
},
"dependency_warning": {
"enabled": false
},
"portfolios": {
"enabled": false
}
}
},
{
"id": "791",
"name": "Second Space Name",
"private": false,
"statuses": [
{
"status": "Open",
"type": "open",
"orderindex": 0,
"color": "#d3d3d3"
},
{
"status": "Closed",
"type": "closed",
"orderindex": 1,
"color": "#6bc950"
}
],
"multiple_assignees": true,
"features": {
"due_dates": {
"enabled": true,
"start_date": false,
"remap_due_dates": false,
"remap_closed_due_date": false
},
"time_tracking": {
"enabled": true
},
"tags": {
"enabled": true
},
"time_estimates": {
"enabled": true
},
"checklists": {
"enabled": true
}
}
}
]
}
### Get Space [GET /space/{space_id}]
+ Parameters
+ space_id: 790 (number)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"id": "790",
"name": "Updated Space Name",
"private": false,
"statuses": [
{
"status": "to do",
"type": "open",
"orderindex": 0,
"color": "#d3d3d3"
},
{
"status": "complete",
"type": "closed",
"orderindex": 1,
"color": "#6bc950"
}
],
"multiple_assignees": false,
"features": {
"due_dates": {
"enabled": false,
"start_date": false,
"remap_due_dates": false,
"remap_closed_due_date": false
},
"time_tracking": {
"enabled": false
},
"tags": {
"enabled": false
},
"time_estimates": {
"enabled": false
},
"checklists": {
"enabled": true
},
"custom_fields": {
"enabled": true
},
"remap_dependencies": {
"enabled": false
},
"dependency_warning": {
"enabled": false
},
"portfolios": {
"enabled": false
}
}
}
## Tags [/{space_id}/tag]
### Get Space Tags [GET /space/{space_id}/tag]
+ Parameters
+ space_id: 512 (number)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Response 200 (application/json)
{
"tags": [
{
"name": "Tag name",
"tag_fg": "#000000",
"tag_bg": "#000000"
}
]
}
### Create Space Tag [POST /space/{space_id}/tag]
+ Parameters
+ space_id: 512 (number)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"tag": {
"name": "Tag Name",
"tag_fg": "#000000",
"tag_bg": "#000000"
}
}
+ Response 200 (application/json)
{
}
### Edit Space Tag [PUT /space/{space_id}/tag/{tag_name}]
+ Parameters
+ space_id: 512 (number)
+ tag_name: name (string)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Response 200 (application/json)
{
"tag": {
"name": "Updated Tag",
"fg_color": "#ffffff",
"bg_color": "#ffffff"
}
}
### Delete Space Tag [DELETE /space/{space_id}/tag/{tag_name}]
+ Parameters
+ space_id: 512 (number)
+ tag_name: name (string)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"tag":
{
"name": "Tag name",
"tag_fg": "#000000",
"tag_bg": "#000000"
}
}
+ Response 200 (application/json)
{
}
### Add Tag To Task [POST /task/{task_id}/tag/{tag_name}]
+ Parameters
+ task_id: abc (string)
+ tag_name: name (string)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Response 200 (application/json)
{
}
### Remove Tag From Task [DELETE /task/{task_id}/tag/{tag_name}]
+ Parameters
+ task_id: abc (string)
+ tag_name: name (string)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Response 200 (application/json)
{}
## Tasks [/tasks]
### Create Task [POST /list/{list_id}/task]
+ Parameters
+ list_id: 123 (number)
+ Request
`assignees` is an array of the assignees' userids to be added to this task.
`priority` is an integer mapping as 1 : Urgent, 2 : High, 3 : Normal, 4 : Low.
Time estimate is in milliseconds.
See the fields section below to see the custom fields available on a list. If `notify_all` is true, creation notifications will be sent to everyone including the creator of the task.
Instead of `content` you can pass `markdown_content` with valid markdown syntax to add formatting to the task description.
Passing an existing task ID in the `parent` property will make the new task a subtask of that parent. The `parent` you pass must not be a subtask itself, and must be part of the list that you pass in the URL params.
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "New Task Name",
"content": "New Task Content",
"assignees": [
183
],
"tags": ["tag name 1"],
"status": "Open",
"priority": 3,
"due_date": 1508369194377,
"due_date_time": false,
"time_estimate": 8640000,
"start_date": 1567780450202,
"start_date_time": false,
"notify_all": true,
"parent": null,
"custom_fields": [
{
"id": "0a52c486-5f05-403b-b4fd-c512ff05131c",
"value": 23
},
{
"id": "03efda77-c7a0-42d3-8afd-fd546353c2f5",
"value": "Text field input"
}
]
}
+ Response 200 (application/json)
{
"id": "9hx",
"name": "New Task Name",
"status": {
"status": "Open",
"color": "#d3d3d3",
"orderindex": 0,
"type": "open"
},
"orderindex": "1.00000000000000000000000000000000",
"date_created": "1567780450202",
"date_updated": "1567780450202",
"date_closed": null,
"creator": {
"id": 183,
"username": "John Doe",
"color": "#827718",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg"
},
"assignees": [],
"checklists": [],
"tags": [],
"parent": null,
"priority": null,
"due_date": null,
"start_date": null,
"time_estimate": null,
"time_spent": null,
"list": {
"id": "123"
},
"folder": {
"id": "456"
},
"space": {
"id": "789"
},
"url": "https://app.clickup.com/t/9hx"
}
### Update Task [PUT /task/{task_id}]
+ Parameters
+ task_id: 9hx (string)
+ Request
Only pass properties you want to update. It is unnesseary to pass the entire task object. `assignees` is an array of the assignees' userids to be added to this task.
`priority` is an integer mapping as 1 : Urgent, 2 : High, 3 : Normal, 4 : Low.
Time estimate is in milliseconds.
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "Updated Task Name",
"content": "Updated Task Content",
"status": "in progress",
"priority": 1,
"time_estimate": 8640000,
"assignees": {
"add": [182],
"rem": [183]
},
"archived": false,
}
+ Response 200 (application/json)
{
"id": "9hx",
"name": "Updated Task Name",
"status": {
"status": "in progress",
"color": "#d3d3d3",
"orderindex": 1,
"type": "custom"
},
"archived": false,
"orderindex": "1.00000000000000000000000000000000",
"date_created": "1567780450202",
"date_updated": "1567780450202",
"date_closed": null,
"creator": {
"id": 183,
"username": "John Doe",
"color": "#827718",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg"
},
"assignees": [],
"checklists": [],
"tags": [],
"parent": null,
"priority": null,
"due_date": null,
"start_date": null,
"time_estimate": null,
"time_spent": null,
"list": {
"id": "123"
},
"folder": {
"id": "456"
},
"space": {
"id": "789"
},
"url": "https://app.clickup.com/t/9hx"
}
### Delete Task [DELETE /task/{task_id}]
+ Parameters
+ task_id: 9xh (string)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Response 200 (application/json)
{}
### Get Tasks [GET /list/{list_id}/task{?archived,page,order_by,reverse,subtasks,space_ids%5B%5D,project_ids%5B%5D,statuses%5B%5D,include_closed,assignees%5B%5D,tags%5B%5D,due_date_gt,due_date_lt,date_created_gt,date_created_lt,date_updated_gt,date_updated_lt}]
+ Parameters
+ list_id: 123 (number)
+ archived: false (boolean)
+ page (integer, optional) - Page to fetch (starts at 0)
+ order_by (string, optional) - Order by field, defaults to created
Options: id, created, updated, due_date
+ reverse (boolean, optional) - Reverse order
+ subtasks (boolean, optional) - Include subtasks, default false
+ space_ids%5B%5D (array, optional) - Spaces to query
+ project_ids%5B%5D (array, optional) - Projects to query
+ statuses%5B%5D (array, optional) - Statuses to query
+ include_closed (boolean, optional) - By default, the api does not include closed tasks. Set this to true and dont send a status filter to include closed tasks.
+ assignees%5B%5D (array, optional) - Assignees to query
+ due_date_gt (integer, optional) - Filter due date greater than posix time
+ due_date_lt (integer, optional) - Filter due date less than posix time
+ date_created_gt (integer, optional) - Filter date created greater than posix time
+ date_created_lt (integer, optional) - Filter date created less than posix time
+ date_updated_gt (integer, optional) - Filter date updated greater than posix time
+ date_updated_lt (integer, optional) - Filter date updated less than posix time
+ Request
The maximum number of tasks returned in this response is `100`. When you are paging this request, you should check list limit against the length of each response to determine if you are on the last page.
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Response 200 (application/json)
[
{
"id": "9hx",
"name": "New Task Name",
"status": {
"status": "Open",
"color": "#d3d3d3",
"orderindex": 0,
"type": "open"
},
"orderindex": "1.00000000000000000000000000000000",
"date_created": "1567780450202",
"date_updated": "1567780450202",
"date_closed": null,
"creator": {
"id": 183,
"username": "John Doe",
"color": "#827718",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg"
},
"assignees": [],
"checklists": [],
"tags": [],
"parent": null,
"priority": null,
"due_date": null,
"start_date": null,
"time_estimate": null,
"time_spent": null,
"list": {
"id": "123"
},
"folder": {
"id": "456"
},
"space": {
"id": "789"
},
"url": "https://app.clickup.com/t/9hx"
},
{
"id": "9hz",
"name": "Second task",
"status": {
"status": "Open",
"color": "#d3d3d3",
"orderindex": 0,
"type": "open"
},
"orderindex": "2.00000000000000000000000000000000",
"date_created": "1567780450202",
"date_updated": "1567780450202",
"date_closed": null,
"creator": {
"id": 183,
"username": "John Doe",
"color": "#827718",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg"
},
"assignees": [],
"checklists": [],
"tags": [],
"parent": null,
"priority": null,
"due_date": null,
"start_date": null,
"time_estimate": null,
"time_spent": null,
"list": {
"id": "123"
},
"folder": {
"id": "456"
},
"space": {
"id": "789"
},
"url": "https://app.clickup.com/t/9hz"
}
]
### Get Task [GET /task/{task_id}]
+ Parameters
+ task_id: 9hz (string)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Response 200 (application/json)
{
"id": "9hx",
"name": "Updated Task Name",
"status": {
"status": "in progress",
"color": "#d3d3d3",
"orderindex": 1,
"type": "custom"
},
"orderindex": "1.00000000000000000000000000000000",
"date_created": "1567780450202",
"date_updated": "1567780450202",
"date_closed": null,
"creator": {
"id": 183,
"username": "John Doe",
"color": "#827718",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg"
},
"assignees": [],
"checklists": [],
"tags": [],
"parent": null,
"priority": null,
"due_date": null,
"start_date": null,
"time_estimate": null,
"time_spent": null,
"list": {
"id": "123"
},
"folder": {
"id": "456"
},
"space": {
"id": "789"
},
"url": "https://app.clickup.com/t/9hx"
}
### Get Filtered Team Tasks [GET /team/{team_id}/task{?page,order_by,reverse,subtasks,space_ids%5B%5D,project_ids%5B%5D,list_ids%5B%5D,statuses%5B%5D,include_closed,assignees%5B%5D,tags%5B%5D,due_date_gt,due_date_lt,date_created_gt,date_created_lt,date_updated_gt,date_updated_lt}]
+ Parameters
+ team_id: 123 (string) - Team ID of tasks
+ page (integer) - Page to fetch
+ order_by (string, optional) - Order by field, defaults to created
Options: id, created, updated, due_date
+ reverse (boolean, optional) - Reverse order
+ subtasks (boolean, optional) - Include subtasks, default false
+ space_ids%5B%5D (array, optional) - Spaces to query
+ project_ids%5B%5D (array, optional) - Projects to query
+ list_ids%5B%5D (array, optional) - Lists to query
+ statuses%5B%5D (array, optional) - Statuses to query
+ include_closed (boolean, optional) - By default, the api does not include closed tasks. Set this to true and dont send a status filter to include closed tasks.
+ assignees%5B%5D (array, optional) - Assignees to query
+ tags%5B%5D (array, optional) - Tag names to query
+ due_date_gt (integer, optional) - Filter due date greater than posix time
+ due_date_lt (integer, optional) - Filter due date less than posix time
+ date_created_gt (integer, optional) - Filter date created greater than posix time
+ date_created_lt (integer, optional) - Filter date created less than posix time
+ date_updated_gt (integer, optional) - Filter date updated greater than posix time
+ date_updated_lt (integer, optional) - Filter date updated less than posix time
+ Request
By default this does not include closed tasks. To page tasks, pass the page number you wish to fetch.
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"tasks": [
{
"id": "av1",
"name": "My First Task",
"text_content": "Task description",
"status": {
"status": "Open",
"type": "open",
"orderindex": 1,
"color": "#000000"
},
"orderindex": "1.0000",
"date_created": "1508369194377",
"date_updated": "1508369194377",
"date_closed": "1508369194377",
"creator": {
"id": 123,
"username": "John Doe",
"color": "#000000",
"profilePicture": "https://clickup.com/avatar.jpg"
},
"assignees": [
{
"id": 123,
"username": "John Doe",
"color": "#000000",
"profilePicture": "https://clickup.com/avatar.jpg"
}
],
"tags": [
{
"name": "tagged",
"tag_fg": "#000000",
"tag_bg": "#000000"
}
],
"parent": "av2",
"priority": 1,
"due_date": "1508369194377",
"start_date": "1508369194377",
"points": 1.3,
"time_estimate": 1.2,
"space": {
"id": 1
},
"project": {
"id": 1
},
"list": {
"id": 1
},
"url": "https://app.clickup.com/###"
}
]
}
## Task Templates [/{team_id}/taskTemplate]
### Get Task Templates [GET /team/{team_id}/taskTemplate{?page}]
+ Parameters
+ team_id: 512 (number)
+ page: 0 (integer) Page to fetch
+ Request
To page task templates, pass the page number you wish to fetch.
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Response 200 (application/json)
{
"templates": []
}
### Create Task From Template [POST /list/{list_id}/taskTemplate/{template_id}]
+ Parameters
+ list_id: 512 (number)
+ template_id: 9hz (string)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "New task name"
}
+ Response 200 (application/json)
{
"id": "9hk"
}
## Teams [/teams]
### Get Teams [GET /team]
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"teams": [
{
"id": "333",
"name": "Team Name",
"color": "#000000",
"avatar": null,
"members": [
{
"user": {
"id": 812,
"username": "John Doe",
"email": "john@example.com",
"color": "#FFFFFF",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/812_nx1.jpg",
"initials": "JD",
"role": 2
}
},
{
"user": {
"id": 813,
"username": "Jane Doe",
"email": "jane@example.com",
"color": null,
"profilePicture": "https://attachments-public.clickup.com/profilePictures/813_nx1.jpg",
"initials": "JD",
"role": 3
}
}
]
}
]
}
## Time Tracking [/task/{task_id}/time]
### Track time [POST /task/{task_id}/time]
+ Parameters
+ task_id: 9hv (string)
+ Request
Include the total time or the start and end. The time is in milliseconds and the start and end are posix dates.
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"start": 1567780450202,
"end": 1508369194377,
"time": 8640000
}
+ Response 200 (application/json)
{
"id": "123",
}
### Get tracked time [GET /task/{task_id}/time]
+ Parameters
+ task_id: 9hv (string)
+ Request
Get time tracked for a task.
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Response 200 (application/json)
{
"data": [
{
"user": {
"id": 1,
"username": "John Doe",
"email": "johndoe@gmail.com",
"color": "#795548",
"initials": "JD",
"profilePicture": null
},
"time": 1000000,
"intervals": [
{
"id": "318",
"start": null,
"end": null,
"time": "1000000",
"source": "chrome",
"date_added": "1569983937761"
}
]
}
]
}
### Edit time tracked [PUT /task/{task_id}/time/{interval_id}]
+ Parameters
+ task_id: 9hv (string)
+ interval_id: 123 (string)
+ Request
Edit the start, end, or total time of a time tracked entry.
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"start": 1567780450202,
"end": 1508369194377,
"time": 8640000
}
+ Response 200 (application/json)
{
}
### Delete time tracked [DELETE /task/{task_id}/time/{interval_id}]
+ Parameters
+ task_id: 9hv (string)
+ interval_id: 123 (string)
+ Request
Delete a time tracked entry
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Response 200 (application/json)
{}
## Views [/view]
While you can use the ClickUp API to manage the views that you have access to through the UI, they are great for filtering and sorting tasks. Below is an example view object and an explanation of each part.
#### The View Object
```
{
"name": "View Name,
"type": "list",
"parent": {
"id": 333,
"type": 7
},
"grouping": {
"field": "status",
"dir": 1
},
"filters": {
"op": "AND",
"fields": [
{
"field": "assignee",
"op": "EQ",
"values": []
}
],
"search": "",
"show_closed": false
},
"sorting": {
"fields": [
{
"field": "dateCreated",
"dir": -1
}
]
},
"columns": {
"fields": [
{
"field": "dateCreated"
}
]
}
}
```
##### View Types
The view `type` describes what kind of view the object is. This value can be either `list`, `board`, `calendar`, or `gantt`. You cannot currently work with page views through the public API.
##### Parent Types
The `parent` object of the view describes what level of hierarchy the view lives on. Since a view can live on the `team`, `space`, `folder`, or `list` level, you must specify this parent type along with its ID. Below are the available types:
- Team: `7`
- List: `6`
- Folder: `5`,
- Space: `4`
Below is an example of the parent object, on a list with the ID `234`.
```
const parent = {
"type": 6,
"id": 234
}
```
_Note_ - Team level views are the views that live on the `Everything` button in the ClickUp UI.
#### Grouping
The grouping is basically the first sort field that you want to organize your tasks by. In the ClickUp UI it determines the display that the tasks should be shown in. For example, if you group by `priority`, all tasks in urgent priority will be grouped together and displayed under the red urgent priority flag. You should manipulate this field for views only if those views are intended to be viewed and manipulated through the UI. If you are using views purely for filtering and sorting through the public API, it is recommended that you set your grouping to `none`.
__*Field:*__
To set the group type, you can set `grouping.field` to any of the following values:
- `none` (recommended)
- `status`
- `priority`
- `assignee`
- `tag`
- `dueDate`
__*Dir:*__ Set the group dir to `1` or `-1` to change the direction of the group sort.
#### Filters
Filters are what make views powerful. It gives you the ability to form a complex combination of queries to find exactly the task that you are looking for.
##### Filter Operator
The `op` property of the filters object stands for operator and determines in what way you want multiple filters to behave together. The available values for this property are `AND` and `OR`.
##### Filter Search
The `search` property of the filters object is a filter for task name (it does not search the task description or any other property of the task object). Unlike all of the filters in `filters.fields`, this specific filter does not respect the value of `filters.op` and will always use `AND` in conjunction with other filters.
##### Filter Show Closed
The `show_closed` property is a shorthand filter to toggle the behavior of closed tasks. By default, this property is `false`. You can use the `status` filter (explained below) to achieve a similar outcome, however the main difference with this filter is it does not respect the value of `filters.op` and will always use `AND` in conjunction with other filters (similar to `search`).
##### Filter Fields
The `filters.fields` array is where you will place a majority of your filters. Each object in this array will always follow this format:
```
{
"field": "field name",
"op": "op name",
"values": [] // array of values
}
```
###### Archived
To filter by assignees, use the `archived` field.
*Operators:*
- `EQ`
- `NOT`
*Values* - The values array is ignored for this filter
```
{
"field": "archived",
"op": "EQ",
"values": []
}
```
*Values* - An array of `userid`'s
###### Assignee
To filter by assignees, use the `assignee` field.
*Operators:*
- `ANY`
- `ALL`
- `NOT ANY`
- `NOT ALL`
*Values* - An array of `userid`'s
*Example:*
```
{
"field": "assignee",
"op": "ANY",
"values": [182, 183]
}
```
###### Priority
To filter by priority, use the `prioirty` field.
*Operators:*
- `EQ`
- `NOT`
*Values* - An array of prioirty values
*Example:*
```
{
"field": "priority",
"op": "EQ",
"values": ["4", "-1"]
}
```
_Note_ - `-1` is no priority
###### Date Filters
To filter by due date, use the `dueDate` field. You can also use the same operators and values for the similar date columns, `startDate`, `dateClosed`, `dateCreated`, and `dateUpdated`.
_Operators:_
- `EQ`
- `NOT`
*Values:*
Due date values are dynamic values, which allow you to specify values such as `today` or `overdue` and query due dates without actually setting a specific timestamp. Each value is an object with a descriptive `op` property and sometimes one or more reference values.
- `{ "op": "today" }`
- `{ "op": "yesterday" }`
- `{ "op": "tomorrow" }`
- `{ "op": "next7" }` (next seven days)
- `{ "op": "last7" }` (last seven days)
- `{ "op": "overdue" }`
- `{ "op": "earlier" }` (today and earlier)
- `{ "op": "thisweek" }`
- `{ "op": "thismonth" }`
- `{ "op": "lastmonth" }`
- `{ "op": "eq", "dueDate": 1579240800000 }` (exact date)
- `{ "op": "ls", "dueDate": 1579240800000 }` (before date)
- `{ "op": "gt", "dueDate": 1579240800000 }` (after date)
- `{ "op": "ra", "dueDate": 1579240800000, "startDate": 1579068000000 }` (date range)
- `{ "op": "notNull" }` (any date)
- `{ "op": "null" }` (no date)
*Example:*
```
{
"field": "dueDate",
"op": "EQ",
"values": [{ "op": "notNull" }]
}
```
###### Status
To filter by due date, use the `status` field.
_Operators:_
- `EQ`
- `NOT`
*Values:*
Use the `{ "type": "x" }` format to target status types, such as `active`, `done`, or `closed`. Otherwise, pass an array of status names as strings.
- `{ "type": "active" }`
- `{ "type": "done" }`
- `{ "type": "closed" }`
- `"in progress"`
*Example:*
```
{
"field": "status",
"op": "EQ",
"values": ["in progress", { "type": "done" }]
}
```
###### Tag
To filter by assignees, use the `tag` field.
*Operators:*
- `ANY`
- `ALL`
- `NOT ANY`
- `NOT ALL`
*Values* - An array of tags names
*Example:*
```
{
"field": "tag",
"op": "ANY",
"values": ["tag 1", "tag 2"]
}
```
###### Recurring
To filter by assignees, use the `recurring` field.
*Operators:*
- `EQ`
- `NOT`
*Values* - The values array is ignored for this filter
```
{
"field": "recurring",
"op": "EQ",
"values": []
}
```
###### Custom Fields
To filter by a custom field, you must create the field name using the format `cf_{{field_id}}`. For example, if the id of your custom field is `ec49d70b-72e1-40c2-b04c-b0f728499f28`, then the field name would be `cf_ec49d70b-72e1-40c2-b04c-b0f728499f28`.
*Operators:* - All custom field types can use the filter operators `EQ` and `NOT`. Additionally, you can use the operators `GT`, `GTE`, `LT`, and `LTE` for `number` and `currency` fields.
*Values:* - The type of values you can add to the `values` array depend on the type of custom field that you are filtering by. For instance, for a number field you would pass `[12]`, but to indicate a drop down option, you would pass its ID, like `["435562d0-0b35-4cfe-9726-1c4baf8d1c44"]`. For any custom field, you can filter by `is set` and `not set` by passing `{ "op": "NOT", "values": [null] }` (does not equal null) and `{ "op": "NOT", "values": [null] }` (equals null) respectively.
```
{
"field": "cf_ec49d70b-72e1-40c2-b04c-b0f728499f28",
"op": "EQ",
"values": [null]
}
```
#### Sorting
Add sorting options by passing sort objects to the `view.sorting.fields` array. You can include a `dir` value of `1` or `-1` to specify a sort direction. You can use any `field` value that you can use in filters, as specified above.
#### Columns
Specify the columns that are visible to you in the UI by adding column objects to the `view.columns.fields` array. You can use any `field` value that you can use in filters, as specified above.
#### Get View Tasks
Finally, you can use the `GET /api/v2/view/{{view_id}}/tasks` route to get the resulting tasks from your view query. You must create a view first with the view CRUD operations to get the `view_id`.
### Create Team View [POST /team/{team_id}/view]
+ Parameters
+ team_id: 512 (number)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "New Team View Name",
"type": "list",
"grouping": {
"field": "status",
"dir": 1,
"collapsed": [],
"ignore": false
},
"divide": {
"field": null,
"dir": null,
"collapsed": []
},
"sorting": {
"fields": []
},
"filters": {
"op": "AND",
"fields": [],
"search": "",
"show_closed": false
},
"columns": {
"fields": []
},
"team_sidebar": {
"assignees": [],
"assigned_comments": false,
"unassigned_tasks": false
},
"settings": {
"show_task_locations": false,
"show_subtasks": 3,
"show_subtask_parent_names": false,
"show_closed_subtasks": false,
"show_assignees": true,
"show_images": true,
"collapse_empty_columns": null,
"me_comments": true,
"me_subtasks": true,
"me_checklists": true
}
}
+ Response 200 (application/json)
{
"view": {
"id": "3c-105",
"name": "New Team View Name",
"type": "list",
"parent": {
"id": "512",
"type": 7
},
"grouping": {
"field": "status",
"dir": 1,
"collapsed": [],
"ignore": false
},
"divide": {
"field": null,
"dir": null,
"collapsed": []
},
"sorting": {
"fields": []
},
"filters": {
"op": "AND",
"fields": [],
"search": "",
"show_closed": false
},
"columns": {
"fields": []
},
"team_sidebar": {
"assignees": [],
"assigned_comments": false,
"unassigned_tasks": false
},
"settings": {
"show_task_locations": false,
"show_subtasks": 3,
"show_subtask_parent_names": false,
"show_closed_subtasks": false,
"show_assignees": true,
"show_images": true,
"collapse_empty_columns": null,
"me_comments": true,
"me_subtasks": true,
"me_checklists": true
}
}
}
### Create Space View [POST /space/{space_id}/view]
+ Parameters
+ space_id: 790 (number)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "New Space View Name",
"type": "list",
"grouping": {
"field": "status",
"dir": 1,
"collapsed": [],
"ignore": false
},
"divide": {
"field": null,
"dir": null,
"collapsed": []
},
"sorting": {
"fields": []
},
"filters": {
"op": "AND",
"fields": [],
"search": "",
"show_closed": false
},
"columns": {
"fields": []
},
"team_sidebar": {
"assignees": [],
"assigned_comments": false,
"unassigned_tasks": false
},
"settings": {
"show_task_locations": false,
"show_subtasks": 3,
"show_subtask_parent_names": false,
"show_closed_subtasks": false,
"show_assignees": true,
"show_images": true,
"collapse_empty_columns": null,
"me_comments": true,
"me_subtasks": true,
"me_checklists": true
}
}
+ Response 200 (application/json)
{
"view": {
"id": "3c-106",
"name": "New Space View Name",
"type": "list",
"parent": {
"id": "790",
"type": 4
},
"grouping": {
"field": "status",
"dir": 1,
"collapsed": [],
"ignore": false
},
"divide": {
"field": null,
"dir": null,
"collapsed": []
},
"sorting": {
"fields": []
},
"filters": {
"op": "AND",
"fields": [],
"search": "",
"show_closed": false
},
"columns": {
"fields": []
},
"team_sidebar": {
"assignees": [],
"assigned_comments": false,
"unassigned_tasks": false
},
"settings": {
"show_task_locations": false,
"show_subtasks": 3,
"show_subtask_parent_names": false,
"show_closed_subtasks": false,
"show_assignees": true,
"show_images": true,
"collapse_empty_columns": null,
"me_comments": true,
"me_subtasks": true,
"me_checklists": true
}
}
}
### Create Folder View [POST /folder/{folder_id}/view]
+ Parameters
+ folder_id: 457 (number)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "New Folder View Name",
"type": "list",
"grouping": {
"field": "status",
"dir": 1,
"collapsed": [],
"ignore": false
},
"divide": {
"field": null,
"dir": null,
"collapsed": []
},
"sorting": {
"fields": []
},
"filters": {
"op": "AND",
"fields": [],
"search": "",
"show_closed": false
},
"columns": {
"fields": []
},
"team_sidebar": {
"assignees": [],
"assigned_comments": false,
"unassigned_tasks": false
},
"settings": {
"show_task_locations": false,
"show_subtasks": 3,
"show_subtask_parent_names": false,
"show_closed_subtasks": false,
"show_assignees": true,
"show_images": true,
"collapse_empty_columns": null,
"me_comments": true,
"me_subtasks": true,
"me_checklists": true
}
}
+ Response 200 (application/json)
{
"view": {
"id": "3c-107",
"name": "New Folder View Name",
"type": "list",
"parent": {
"id": "457",
"type": 5
},
"grouping": {
"field": "status",
"dir": 1,
"collapsed": [],
"ignore": false
},
"divide": {
"field": null,
"dir": null,
"collapsed": []
},
"sorting": {
"fields": []
},
"filters": {
"op": "AND",
"fields": [],
"search": "",
"show_closed": false
},
"columns": {
"fields": []
},
"team_sidebar": {
"assignees": [],
"assigned_comments": false,
"unassigned_tasks": false
},
"settings": {
"show_task_locations": false,
"show_subtasks": 3,
"show_subtask_parent_names": false,
"show_closed_subtasks": false,
"show_assignees": true,
"show_images": true,
"collapse_empty_columns": null,
"me_comments": true,
"me_subtasks": true,
"me_checklists": true
}
}
}
### Create List View [POST /list/{list_id}/view]
+ Parameters
+ list_id: 124 (number)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "New List View Name",
"type": "list",
"grouping": {
"field": "status",
"dir": 1,
"collapsed": [],
"ignore": false
},
"divide": {
"field": null,
"dir": null,
"collapsed": []
},
"sorting": {
"fields": []
},
"filters": {
"op": "AND",
"fields": [],
"search": "",
"show_closed": false
},
"columns": {
"fields": []
},
"team_sidebar": {
"assignees": [],
"assigned_comments": false,
"unassigned_tasks": false
},
"settings": {
"show_task_locations": false,
"show_subtasks": 3,
"show_subtask_parent_names": false,
"show_closed_subtasks": false,
"show_assignees": true,
"show_images": true,
"collapse_empty_columns": null,
"me_comments": true,
"me_subtasks": true,
"me_checklists": true
}
}
+ Response 200 (application/json)
{
"view": {
"id": "3c-108",
"name": "New List View Name",
"type": "list",
"parent": {
"id": "124",
"type": 6
},
"grouping": {
"field": "status",
"dir": 1,
"collapsed": [],
"ignore": false
},
"divide": {
"field": null,
"dir": null,
"collapsed": []
},
"sorting": {
"fields": []
},
"filters": {
"op": "AND",
"fields": [],
"search": "",
"show_closed": false
},
"columns": {
"fields": []
},
"team_sidebar": {
"assignees": [],
"assigned_comments": false,
"unassigned_tasks": false
},
"settings": {
"show_task_locations": false,
"show_subtasks": 3,
"show_subtask_parent_names": false,
"show_closed_subtasks": false,
"show_assignees": true,
"show_images": true,
"collapse_empty_columns": null,
"me_comments": true,
"me_subtasks": true,
"me_checklists": true
}
}
}
### Get Team Views [GET /team/{team_id}/view]
+ Parameters
+ team_id: 512 (number)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"views": [
{
"id": "3c-105",
"name": "New View Name",
"type": "list",
"parent": {
"id": "512",
"type": 7
},
"grouping": {
"field": "status",
"dir": 1,
"collapsed": [],
"ignore": false
},
"divide": {
"field": null,
"dir": null,
"collapsed": []
},
"sorting": {
"fields": []
},
"filters": {
"op": "AND",
"fields": [],
"search": "",
"show_closed": false
},
"columns": {
"fields": []
},
"team_sidebar": {
"assignees": [],
"assigned_comments": false,
"unassigned_tasks": false
},
"settings": {
"show_task_locations": false,
"show_subtasks": 3,
"show_subtask_parent_names": false,
"show_closed_subtasks": false,
"show_assignees": true,
"show_images": true,
"collapse_empty_columns": null,
"me_comments": true,
"me_subtasks": true,
"me_checklists": true
}
}
]
}
### Get Space Views [GET /space/{space_id}/view]
+ Parameters
+ space_id: 790 (number)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"views": [
{
"id": "3c-106",
"name": "New Space View Name",
"type": "list",
"parent": {
"id": "790",
"type": 4
},
"grouping": {
"field": "status",
"dir": 1,
"collapsed": [],
"ignore": false
},
"divide": {
"field": null,
"dir": null,
"collapsed": []
},
"sorting": {
"fields": []
},
"filters": {
"op": "AND",
"fields": [],
"search": "",
"show_closed": false
},
"columns": {
"fields": []
},
"team_sidebar": {
"assignees": [],
"assigned_comments": false,
"unassigned_tasks": false
},
"settings": {
"show_task_locations": false,
"show_subtasks": 3,
"show_subtask_parent_names": false,
"show_closed_subtasks": false,
"show_assignees": true,
"show_images": true,
"collapse_empty_columns": null,
"me_comments": true,
"me_subtasks": true,
"me_checklists": true
}
}
]
}
### Get Folder Views [GET /folder/{folder_id}/view]
+ Parameters
+ folder_id: 457 (number)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"views": [
{
"id": "3c-107",
"name": "New Folder View Name",
"type": "list",
"parent": {
"id": "457",
"type": 5
},
"grouping": {
"field": "status",
"dir": 1,
"collapsed": [],
"ignore": false
},
"divide": {
"field": null,
"dir": null,
"collapsed": []
},
"sorting": {
"fields": []
},
"filters": {
"op": "AND",
"fields": [],
"search": "",
"show_closed": false
},
"columns": {
"fields": []
},
"team_sidebar": {
"assignees": [],
"assigned_comments": false,
"unassigned_tasks": false
},
"settings": {
"show_task_locations": false,
"show_subtasks": 3,
"show_subtask_parent_names": false,
"show_closed_subtasks": false,
"show_assignees": true,
"show_images": true,
"collapse_empty_columns": null,
"me_comments": true,
"me_subtasks": true,
"me_checklists": true
}
}
]
}
### Get List Views [GET /list/{list_id}/view]
+ Parameters
+ list_id: 124 (number)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"views": [
{
"id": "3c-107",
"name": "New List View Name",
"type": "list",
"parent": {
"id": "124",
"type": 6
},
"grouping": {
"field": "status",
"dir": 1,
"collapsed": [],
"ignore": false
},
"divide": {
"field": null,
"dir": null,
"collapsed": []
},
"sorting": {
"fields": []
},
"filters": {
"op": "AND",
"fields": [],
"search": "",
"show_closed": false
},
"columns": {
"fields": []
},
"team_sidebar": {
"assignees": [],
"assigned_comments": false,
"unassigned_tasks": false
},
"settings": {
"show_task_locations": false,
"show_subtasks": 3,
"show_subtask_parent_names": false,
"show_closed_subtasks": false,
"show_assignees": true,
"show_images": true,
"collapse_empty_columns": null,
"me_comments": true,
"me_subtasks": true,
"me_checklists": true
}
}
]
}
### Get View [GET /view/{view_id}]
+ Parameters
+ view_id: 3c-105 (string)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"view": {
"id": "3c-105",
"name": "New View Name",
"type": "list",
"parent": {
"id": "512",
"type": 7
},
"grouping": {
"field": "status",
"dir": 1,
"collapsed": [],
"ignore": false
},
"divide": {
"field": null,
"dir": null,
"collapsed": []
},
"sorting": {
"fields": []
},
"filters": {
"op": "AND",
"fields": [],
"search": "",
"show_closed": false
},
"columns": {
"fields": []
},
"team_sidebar": {
"assignees": [],
"assigned_comments": false,
"unassigned_tasks": false
},
"settings": {
"show_task_locations": false,
"show_subtasks": 3,
"show_subtask_parent_names": false,
"show_closed_subtasks": false,
"show_assignees": true,
"show_images": true,
"collapse_empty_columns": null,
"me_comments": true,
"me_subtasks": true,
"me_checklists": true
}
}
}
### Get View Tasks [GET /view/{view_id}/task{?page}]
+ Parameters
+ view_id: 3c-105 (string)
+ page: 0 (integer) Page to fetch
+ Request
To page the tasks returned, include the page param
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"tasks": [
{
"id": "9hx",
"name": "New Task Name",
"status": {
"status": "Open",
"color": "#d3d3d3",
"orderindex": 0,
"type": "open"
},
"orderindex": "1.00000000000000000000000000000000",
"date_created": "1567780450202",
"date_updated": "1567780450202",
"date_closed": null,
"creator": {
"id": 183,
"username": "John Doe",
"color": "#827718",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg"
},
"assignees": [],
"checklists": [],
"tags": [],
"parent": null,
"priority": null,
"due_date": null,
"start_date": null,
"time_estimate": null,
"time_spent": null,
"list": {
"id": "123"
},
"folder": {
"id": "456"
},
"space": {
"id": "789"
},
"url": "https://app.clickup.com/t/9hx"
},
{
"id": "9hz",
"name": "Second task",
"status": {
"status": "Open",
"color": "#d3d3d3",
"orderindex": 0,
"type": "open"
},
"orderindex": "2.00000000000000000000000000000000",
"date_created": "1567780450202",
"date_updated": "1567780450202",
"date_closed": null,
"creator": {
"id": 183,
"username": "John Doe",
"color": "#827718",
"profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg"
},
"assignees": [],
"checklists": [],
"tags": [],
"parent": null,
"priority": null,
"due_date": null,
"start_date": null,
"time_estimate": null,
"time_spent": null,
"list": {
"id": "123"
},
"folder": {
"id": "456"
},
"space": {
"id": "789"
},
"url": "https://app.clickup.com/t/9hz"
}
],
"last_page": true,
}
### Update View [PUT /view/{view_id}]
+ Parameters
+ view_id: 3c-105 (string)
+ Request
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"name": "New View Name",
"type": "list",
"parent": {
"id": "512",
"type": 7
},
"grouping": {
"field": "status",
"dir": 1,
"collapsed": [],
"ignore": false
},
"divide": {
"field": null,
"dir": null,
"collapsed": []
},
"sorting": {
"fields": []
},
"filters": {
"op": "AND",
"fields": [],
"search": "",
"show_closed": false
},
"columns": {
"fields": []
},
"team_sidebar": {
"assignees": [],
"assigned_comments": false,
"unassigned_tasks": false
},
"settings": {
"show_task_locations": false,
"show_subtasks": 3,
"show_subtask_parent_names": false,
"show_closed_subtasks": false,
"show_assignees": true,
"show_images": true,
"collapse_empty_columns": null,
"me_comments": true,
"me_subtasks": true,
"me_checklists": true
}
}
+ Response 200 (application/json)
+ Response 200 (application/json)
{
"view": {
"id": "3c-105",
"name": "New View Name",
"type": "list",
"parent": {
"id": "512",
"type": 7
},
"grouping": {
"field": "status",
"dir": 1,
"collapsed": [],
"ignore": false
},
"divide": {
"field": null,
"dir": null,
"collapsed": []
},
"sorting": {
"fields": []
},
"filters": {
"op": "AND",
"fields": [],
"search": "",
"show_closed": false
},
"columns": {
"fields": []
},
"team_sidebar": {
"assignees": [],
"assigned_comments": false,
"unassigned_tasks": false
},
"settings": {
"show_task_locations": false,
"show_subtasks": 3,
"show_subtask_parent_names": false,
"show_closed_subtasks": false,
"show_assignees": true,
"show_images": true,
"collapse_empty_columns": null,
"me_comments": true,
"me_subtasks": true,
"me_checklists": true
}
}
}
### Delete View [DELETE /view/{view_id}]
+ Parameters
+ view_id: 3c-105 (string)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{}
## Webhooks [/webhook]
The ClickUp API 2.0 now supports webhooks to notify you when changes are made to your resources. If you have not used webhooks before, our friends from Zapier have put together a great [post](https://zapier.com/blog/what-are-webhooks/) that describes them in detail.
### Events
Below are a list of events that you can subscribe to in order to listen to specific changes to your resources. You can also pass the wildcard `*` to listen to all events that are available.
- taskCreated
- taskUpdated
- taskDeleted
- taskPriorityUpdated
- taskStatusUpdated
- taskAssigneeUpdated
- taskDueDateUpdated
- taskTagUpdated
- taskMoved
- taskCommentPosted
- taskCommentUpdated
- taskTimeEstimateUpdated
- taskTimeTrackedUpdated
- listCreated
- listUpdated
- listDeleted
- folderCreated
- folderUpdated
- folderDeleted
- spaceCreated
- spaceUpdated
- spaceDeleted
- goalCreated
- goalUpdated
- goalDeleted
- keyResultCreated
- keyResultUpdated
- keyResultDeleted
### Endpoint
When an event occurs that your webhoook is subscribed to, we will send details about that change to the endpoint that you provided when you create the webhook. If no protocol is provided on the endpoint, the default will be https. In the future, non-ssl may not be supported so it is highly recommended to use the secure protocol when possible.
Requests to your endpoints will always adhere to the following criteria:
- Always sent with the method `POST`
- The `Content-Type` will always be `application/json`
- The `webhook_id`, `event`, and resource ID will be passed in the body.
- If a history item exists describing the event, it will be passed in a `history_items` array.
An example request:
```
POST https://yourdomain.com/webhook
Content-Type: application/json
{
"webhook_id": "7689a169-a000-4985-8676-6902b96d6627",
"event": "taskUpdated",
"task_id":"c0j",
"history_items": [
{
"id":"33169",
"type":1,
"date":"1575650190085",
"field":"status",
"parent_id":"1753",
"data":{
"status_type":"closed"
},
"source":null,
"user":{
"id":183,
"username":"John Doe",
"email":"example@email.com",
"color":"#827718",
"initials":"JK",
"profilePicture":"https://dev-attachments-public.clickup.com/profilePictures/183_nx1.jpg"
},
"before":{
"status":"open",
"color":"#d3d3d3",
"orderindex":0,
"type":"open"
},
"after":{
"status":"complete",
"color":"#6bc950",
"orderindex":1,
"type":"closed"
}
}
]
}
```
### Webhook Health Status
To ensure the efficient use of our resources here at ClickUp, the health of the webhooks that you create will be monitored. As long as the endpoints that you provide us send a successful HTTP status code in a timely manner, your webhook will stay active and healthy. If an endpoint becomes degraded, we will set your webhook to the appropriate health status described below.
#### `active`
If your webhook is sending us healthy http status codes, we will keep sending your subscribed changes to the endpoint.
#### `failing`
If an unsuccessful http status code is received or if a request takes longer that 15 seconds to complete, we will consider the webhook as failing. We understand though that flukes can happen, so we will retry your webhook five times for each event. If on the fifth retry the endpoint is still failing, we will increment a `fail_count` which you can see in the webhook `health` object. This count will be incremented for each event that we fail to send you.
If at any time while your webhook is marked as `failing` the issues with your endpoint are resolved and success status codes are received, we will automatically mark your webhook back to the `active` status and clear the `fail_count`.
#### `suspended`
If your webhook is set as `failing` and the fail count reaches 100, we will mark the webhook as suspended. We will no longer attempt to send events to this webhook. The only way reactivate this webhook is to fix the endpoint and set the status back to `active` using the `PUT /api/v2/webhook/{webhook_id}` request.
### `401 Gone`
Sometimes the webhooks that you create are no longer necessary to keep active. As a convenience to you, we will immediately mark webhooks as suspended if a `401` http status code is received.
### Signature
All requests sent to your webhook endpoints will be signed so that you can verify that traffic coming to your servers is coming from ClickUp. To sign our requests, we use a hash-based message authentication code, or [HMAC](https://en.wikipedia.org/wiki/HMAC).
Each webhook that is created will be provided with a `secret` which can be found on any of the CRUD webhook endpoints. When a request is sent to your webhook endpoint a signature will be created by hashing the body of the request that is being sent with the shared secret. This signature is sent in the `X-Signature` http header so that the client can verify it was made with the same secret that it has access to.
An example event request sent to a webhook endpoint:
```
POST https://yourdomain.com/webhook
Content-Type: application/json
X-Signature: f7bc83f430538424b13298e6aa6
{
"webhook_id": "7689a169-a000-4985-8676-6902b96d6627",
"event": "taskCreated",
"task_id":"c0j"
}
```
The `X-Signature` value for this request was created by creating a `SHA-256` hash of the above request body using the provided `secret` as a key. In order for the client to verify the signature, it can create a hash signature using the same algorithm and see if the value matches. Below is an example using Node.js. You can find examples using other languages [here](https://github.com/danharper/hmac-examples).
```
const crypto = require('crypto');
const key = 'secret'; // from the webhook object
const body = '{"webhook_id":"7689a169-a000-4985-8676-6902b96d6627","event":"taskCreated","task_id":"c0j"}';
const hash = crypto.createHmac('sha256', key).update(body);
const signature = hash.digest('hex');
```
**Note** - _The body in this example already exists as a string. If you are using an http client that automatically parses request bodies, you must stringify the object with no white spaces inserted_
**Note** - _Signatures will always be digested using hexadecimal_
**Note** - _Only webhooks that were created by the authenticated user will be returned on the fetch webhook endpoints._
### Create Webhook [POST /team/{team_id}/webhook]
+ Parameters
+ team_id: 512 (number)
+ Request
You may filter the location of resources that get sent to a webhook by passing an optional `space_id`, `folder_id`, `list_id`, or `task_id` in the body of the request.
Without specifying any events, all event types will be sent to the webhook. However, you can filter for specific actions by sending an `events` array.
To subscribe to specific events, pass an array of `events` that you want to subscribe to, otherwise pass `"*"` to subscribe to everything.
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"endpoint": "https://yourdomain.com/webhook",
"events": [
"taskCreated",
"taskUpdated",
"taskDeleted",
"listCreated",
"listUpdated",
"listDeleted",
"folderCreated",
"folderUpdated",
"folderDeleted",
"spaceCreated",
"spaceUpdated",
"spaceDeleted",
"goalCreated",
"goalUpdated",
"goalDeleted",
"keyResultCreated",
"keyResultUpdated",
"keyResultDeleted"
]
}
+ Response 200 (application/json)
{
"id": "4b67ac88-e506-4a29-9d42-26e504e3435e",
"webhook": {
"id": "4b67ac88-e506-4a29-9d42-26e504e3435e",
"userid": 183,
"team_id": 108,
"endpoint": "https://yourdomain.com/webhook",
"client_id": "QVOQP06ZXC6CMGVFKB0ZT7J9Y7APOYGO",
"events": [
"taskCreated",
"taskUpdated",
"taskDeleted",
"listCreated",
"listUpdated",
"listDeleted",
"folderCreated",
"folderUpdated",
"folderDeleted",
"spaceCreated",
"spaceUpdated",
"spaceDeleted",
"goalCreated",
"goalUpdated",
"goalDeleted",
"keyResultCreated",
"keyResultUpdated",
"keyResultDeleted"
],
"task_id": null,
"list_id": null,
"folder_id": null,
"space_id": null,
"health": {
"status": "active",
"fail_count": 0
},
"secret": "O94IM25S7PXBPYTMNXLLET230SRP0S89COR7B1YOJ2ZIE8WQNK5UUKEF26W0Z5GA"
}
}
### Update Webhook [PUT /webhook/{webhook_id}]
+ Parameters
+ webhook_id: 4b67ac88-e506-4a29-9d42-26e504e3435e (uuid)
+ Request
To subscribe to specific events, pass an array of `events` that you want to subscribe to, otherwise pass `"*"` to subscribe to everything.
+ Headers
Authorization: "access_token"
Content-Type: application/json
+ Body
{
"endpoint": "https://yourdomain.com/webhook",
"events": "*",
"status": "active"
}
+ Response 200 (application/json)
{
"id": "4b67ac88-e506-4a29-9d42-26e504e3435e",
"webhook": {
"id": "4b67ac88-e506-4a29-9d42-26e504e3435e",
"userid": 183,
"team_id": 108,
"endpoint": "https://yourdomain.com/webhook",
"client_id": "QVOQP06ZXC6CMGVFKB0ZT7J9Y7APOYGO",
"events": [
"taskCreated",
"taskUpdated",
"taskDeleted",
"listCreated",
"listUpdated",
"listDeleted",
"folderCreated",
"folderUpdated",
"folderDeleted",
"spaceCreated",
"spaceUpdated",
"spaceDeleted",
"goalCreated",
"goalUpdated",
"goalDeleted",
"keyResultCreated",
"keyResultUpdated",
"keyResultDeleted"
],
"task_id": null,
"list_id": null,
"folder_id": null,
"space_id": null,
"health": {
"status": "active",
"fail_count": 0
},
"secret": "O94IM25S7PXBPYTMNXLLET230SRP0S89COR7B1YOJ2ZIE8WQNK5UUKEF26W0Z5GA"
}
}
### Delete Webhook [DELETE /webhook/{webhook_id}]
+ Parameters
+ webhook_id: 4b67ac88-e506-4a29-9d42-26e504e3435e (uuid)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{}
### Get Webhooks [GET /team/{team_id}/webhook]
**Note** - _Only webhooks that were created by the authenticated user will be returned on this endpoint.
+ Parameters
+ team_id: 512 (number)
+ Request
+ Headers
Authorization: "access_token"
+ Response 200 (application/json)
{
"webhooks": [
{
"id": "4b67ac88-e506-4a29-9d42-26e504e3435e",
"userid": 183,
"team_id": 108,
"endpoint": "https://yourdomain.com/webhook",
"client_id": "QVOQP06ZXC6CMGVFKB0ZT7J9Y7APOYGO",
"events": [
"taskCreated",
"taskUpdated",
"taskDeleted",
"listCreated",
"listUpdated",
"listDeleted",
"folderCreated",
"folderUpdated",
"folderDeleted",
"spaceCreated",
"spaceUpdated",
"spaceDeleted",
"goalCreated",
"goalUpdated",
"goalDeleted",
"keyResultCreated",
"keyResultUpdated",
"keyResultDeleted"
],
"task_id": null,
"list_id": null,
"folder_id": null,
"space_id": null,
"health": {
"status": "failing",
"fail_count": 5
},
"secret": "O94IM25S7PXBPYTMNXLLET230SRP0S89COR7B1YOJ2ZIE8WQNK5UUKEF26W0Z5GA"
}
]
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment