Skip to content
Docs
Project management

ClickUp

Let hires find, create, update, close and comment on tasks in your ClickUp spaces and lists.

Explore 9 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With ClickUp, a hire can:

  • list the lists it can use, with their spaces and folders, and each list's statuses,
  • list a list's tasks (open ones, or all), optionally only those in one status,
  • search tasks by the words in their names and descriptions,
  • read a task with its description, priority and latest comments,
  • create tasks with a status, priority and due date,
  • change a task's title, description, status, priority or due date, and close or reopen it,
  • comment on a task.

1. Choose how Roster signs in

  • A personal API token (quickest). Open ClickUp's Apps settings (the form in Roster links there too), and under API Token click Generate. Copy the token (it starts with pk_; Roster tells you at once if what you paste doesn't). What hires do shows as you, so you may want a ClickUp member just for Roster.
  • An OAuth app of yours. In Settings → Apps, click Create new app, set its redirect URL to the address Roster shows on the connection (it ends in /api/integrations/clickup/oauth/callback), and copy its client ID and secret.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for ClickUp and choose it.
  2. How Roster signs in: pick the way you chose above. Only its fields are shown.
  3. Paste the token, or the app's client ID and secret.
  4. Workspace: your ClickUp workspace's name. Leave it empty if the account is in only one.
  5. Click Connect. With a token, Roster checks it with ClickUp, and the connection shows Connected as your ClickUp workspace. If ClickUp refuses it, Roster says so and saves nothing. With an OAuth app, then click Connect with ClickUp and choose the workspace.

3. Give hires access

On the hire's Tools tab, click Give access on ClickUp:

  • Read only: it can list lists, statuses and tasks, search and read tasks, and nothing else.
  • Read and write: it can also create, update, close and comment on tasks.
  • Spaces: space names, one per line. Leave it empty for every space in the workspace.
  • Lists: list names (or ids). Leave it empty for every list in those spaces. A task in any other list is refused.

Hires refer to tasks by their id (the code at the end of a task's address, like 86a1b2c3d), and to lists and statuses by name, so "move it to in review" works with your own statuses.

Watching for changes

A hire's responsibility can watch ClickUp: when tasks in its lists change, the hire is woken with the list. Checking is one request and costs nothing when nothing changed.

If something goes wrong

  • Search misses an old task: ClickUp has no search for apps, so the hire looks through the 300 most recently updated tasks in its lists. Give it the list, or the task's id.
  • "Rate limit is used up": most ClickUp plans allow 100 requests a minute. The hire waits and tries again.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect ClickUp and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

API key or access token

In ClickUp: your avatar → Settings → Apps → API Token → Generate (it starts with pk_). Hires' work shows as you.

For: How Roster signs in: Personal API token.

OAuth 2.0

From the OAuth app you made in ClickUp: Settings → Apps → Create new app.

For: How Roster signs in: An OAuth app of yours.

No fixed permission list is declared for this connection. Review the sign-in consent screen, the account's roles, and the service's own documentation before connecting.

Connection fields

ClickUp connection fields
FieldWhat to provide
How Roster signs in
signIn
Optional		A token is quickest. An OAuth app of yours lets ClickUp show Roster by name.

Choices: Personal API token (token); An OAuth app of yours (oauth).

Starts with: token.

Personal API token
token
Required · sealed secret		In ClickUp: your avatar → Settings → Apps → API Token → Generate (it starts with pk_). Hires' work shows as you.

Shown when signIn: token.

OAuth app client ID
clientId
Optional		From the OAuth app you made in ClickUp: Settings → Apps → Create new app.

Shown when signIn: oauth.

OAuth app client secret
clientSecret
Optional · sealed secret		Use the value for your account or connection.

Shown when signIn: oauth.

Workspace
workspace
Optional		The ClickUp workspace's name or id. Leave empty if the account is in only one.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

ClickUp per-hire limits
FieldWhat to provide
Spaces
spaces
Optional		Space names (or ids). Leave empty for every space in the workspace.
Lists
lists
Optional		List names (or ids). Leave empty for every list in those spaces.

Actions

9 actions: 5 only read and 4 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

9 of 9 actions. Open an action for its arguments and full input schema.

list_listsRead only

The ClickUp lists this hire can use, with their spaces and folders.

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}
list_tasksRead only

A list's tasks, recently updated first, open ones unless asked, optionally in one status.

Approval: Uses your workspace and hire approval settings.

Arguments for list_tasks
ArgumentTypeDetails
listRequiredstringlist name or id
statusOptionalstringonly tasks in this status, by name
include_doneOptionalbooleanSee input schema below.Default: false
limitOptionalintegerSee input schema below.Default: 30
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "minLength": 1,
      "description": "list name or id"
    },
    "status": {
      "description": "only tasks in this status, by name",
      "type": "string"
    },
    "include_done": {
      "default": false,
      "type": "boolean"
    },
    "limit": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "list"
  ]
}
search_tasksRead only

Find tasks by words in their name or description, among the recently updated tasks of the hire's lists (or one of them).

Approval: Uses your workspace and hire approval settings.

Arguments for search_tasks
ArgumentTypeDetails
textRequiredstringSee input schema below.
listOptionalstringlist name or id
include_doneOptionalbooleanSee input schema below.Default: false
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "minLength": 1
    },
    "list": {
      "type": "string",
      "minLength": 1,
      "description": "list name or id"
    },
    "include_done": {
      "default": false,
      "type": "boolean"
    }
  },
  "required": [
    "text"
  ]
}
get_taskRead only

A task's description, status, priority, assignees, due date and latest comments.

Approval: Uses your workspace and hire approval settings.

Arguments for get_task
ArgumentTypeDetails
taskRequiredstringtask id, e.g. 86a1b2c3d
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "task": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,40}$",
      "description": "task id, e.g. 86a1b2c3d"
    }
  },
  "required": [
    "task"
  ]
}
create_taskRead and write

Create a task in a list, with a status, priority and due date if given.

Approval: Uses your workspace and hire approval settings.

Arguments for create_task
ArgumentTypeDetails
listRequiredstringlist name or id
titleRequiredstringSee input schema below.
descriptionOptionalstringplain textDefault: ""
statusOptionalstringone of the list's statuses, by name; default: its first
priorityOptional"urgent" | "high" | "normal" | "low"See input schema below.
dueOptionalstringdue date like 2026-11-30, or "none" to clear it
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "minLength": 1,
      "description": "list name or id"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "description": {
      "default": "",
      "type": "string",
      "description": "plain text"
    },
    "status": {
      "description": "one of the list's statuses, by name; default: its first",
      "type": "string"
    },
    "priority": {
      "type": "string",
      "enum": [
        "urgent",
        "high",
        "normal",
        "low"
      ]
    },
    "due": {
      "type": "string",
      "pattern": "^(\\d{4}-\\d{2}-\\d{2}|none)$",
      "description": "due date like 2026-11-30, or \"none\" to clear it"
    }
  },
  "required": [
    "list",
    "title"
  ]
}
update_taskRead and write

Change a task's title, description, status, priority or due date. Only what's given changes.

Approval: Uses your workspace and hire approval settings.

Arguments for update_task
ArgumentTypeDetails
taskRequiredstringtask id, e.g. 86a1b2c3d
titleOptionalstringSee input schema below.
descriptionOptionalstringreplaces the description
statusOptionalstringone of the list's statuses, by name
priorityOptional"urgent" | "high" | "normal" | "low"See input schema below.
dueOptionalstringdue date like 2026-11-30, or "none" to clear it
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "task": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,40}$",
      "description": "task id, e.g. 86a1b2c3d"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "description": {
      "description": "replaces the description",
      "type": "string"
    },
    "status": {
      "description": "one of the list's statuses, by name",
      "type": "string"
    },
    "priority": {
      "type": "string",
      "enum": [
        "urgent",
        "high",
        "normal",
        "low"
      ]
    },
    "due": {
      "type": "string",
      "pattern": "^(\\d{4}-\\d{2}-\\d{2}|none)$",
      "description": "due date like 2026-11-30, or \"none\" to clear it"
    }
  },
  "required": [
    "task"
  ]
}
complete_taskRead and write

Close a task (its list's closed status), or open it again.

Approval: Uses your workspace and hire approval settings.

Arguments for complete_task
ArgumentTypeDetails
taskRequiredstringtask id, e.g. 86a1b2c3d
doneOptionalbooleanSee input schema below.Default: true
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "task": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,40}$",
      "description": "task id, e.g. 86a1b2c3d"
    },
    "done": {
      "default": true,
      "type": "boolean"
    }
  },
  "required": [
    "task"
  ]
}
list_statusesRead only

A list's statuses, in order, with which ones close a task.

Approval: Uses your workspace and hire approval settings.

Arguments for list_statuses
ArgumentTypeDetails
listRequiredstringlist name or id
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "list": {
      "type": "string",
      "minLength": 1,
      "description": "list name or id"
    }
  },
  "required": [
    "list"
  ]
}
commentRead and write

Comment on a task.

Approval: Uses your workspace and hire approval settings.

Arguments for comment
ArgumentTypeDetails
taskRequiredstringtask id, e.g. 86a1b2c3d
textRequiredstringplain text
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "task": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{1,40}$",
      "description": "task id, e.g. 86a1b2c3d"
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "description": "plain text"
    }
  },
  "required": [
    "task",
    "text"
  ]
}

Watches and incoming events

  • This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
  • No incoming webhook handler is declared for this integration.

Limits and troubleshooting

  • Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
  • Expired or revoked access: reconnect or replace the key on the connection.
  • Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
  • The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

Basecamp

Projects, to-dos, messages and docs in Basecamp.

Jira

Let hires search, read, create, update, move, comment on and assign Jira issues and plan sprints, on Jira Cloud or your own Jira Data Center.

On this page

1. Choose how Roster signs in2. Connect it in Roster3. Give hires accessIf something goes wrongTools and permissions reference