canonical: https://jentic.com/apis/clickup.com/clickup-api

# ClickUp API

Jentic publishes the only available OpenAPI specification for ClickUp API, keeping it validated and agent-ready. Manage tasks, spaces, folders, lists, goals, and time entries across a hierarchical workspace structure with 50 endpoints. Supports task dependencies, comments, checklists, tags, webhooks, custom views, and team member management for project tracking at every level of the workspace hierarchy.

## For AI agents

Create tasks, track time, manage goals, and organize work across ClickUp's Workspace > Space > Folder > List hierarchy. Supports 50 endpoints for dependencies, comments, tags, and webhooks.

## Scope

Does not handle team messaging, document editing, or video conferencing - use for hierarchical task management and time tracking only.

## Capabilities

- Create tasks with assignees, due dates, priorities, and checklist items within any list
- Track time entries against tasks for workload analysis and billing
- Organize work hierarchically across Spaces, Folders, and Lists within a Workspace
- Set and monitor goals with measurable targets tied to task completion
- Configure webhooks for real-time notifications on task and list changes
- Add dependencies between tasks to enforce execution order and identify blockers
- Build custom views with filters and groupings for tailored work visibility

## Use cases

### AI Agent Task Creation and Updates

AI agents use the ClickUp API through Jentic to create tasks, update statuses, and log time without manual interaction. An agent searches for the task creation operation, loads the schema with assignees, priority, and due date fields, and executes in under a minute. This enables automated ticket creation from support channels, status progression from CI/CD pipelines, and time logging from developer tooling.

Example prompt: Create a task in list ID 901 with name 'Fix login bug', assignee user_id 123, priority 'urgent', due_date '2026-05-10', and add a checklist with items 'Reproduce', 'Fix', 'Test'

### Time Tracking and Resource Allocation

Log and query time entries against tasks to measure where team effort goes. The ClickUp API returns time entries with duration, billable status, and task association. Managers use this data to calculate project costs, identify bottlenecks, and forecast sprint capacity. Time data integrates with invoicing systems for client billing accuracy.

Example prompt: Create a time entry for task ID 'abc123' with duration 3600000ms (1 hour), billable=true, and description 'Code review for PR #45'

### Goal Tracking and OKR Management

Define measurable goals at the team level and track progress through task completion. The ClickUp API lets you create goals with numeric or percentage targets, link tasks as key results, and query current progress. This supports OKR frameworks where strategic objectives connect directly to operational work items in the task hierarchy.

Example prompt: Retrieve all goals for team ID 'team_456' and return each goal's name, target value, current progress percentage, and linked task count

### Webhook-Driven Workflow Automation

Subscribe to ClickUp webhooks to trigger downstream actions when tasks change status, get assigned, or hit their due date. Each webhook payload includes the task details, event type, and workspace context. This replaces polling patterns and enables instant reactions like sending Slack notifications, updating external dashboards, or triggering deployment pipelines.

Example prompt: Create a webhook for team ID 'team_456' with endpoint 'https://hooks.example.com/clickup' listening to 'taskStatusUpdated' and 'taskCreated' events

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /api/v2/list/{list_id}/task | Create a task in a list |
| GET | /api/v2/task/{task_id} | Get task details |
| GET | /api/v2/team/{team_id}/time_entries | Get time entries for a team |
| POST | /api/v2/team/{team_id}/goal | Create a goal |
| GET | /api/v2/team/{team_id}/goal | Get goals for a team |
| POST | /api/v2/team/{team_id}/webhook | Create a webhook |
| POST | /api/v2/task/{task_id}/comment | Add a comment to a task |
| POST | /api/v2/task/{task_id}/dependency | Add a task dependency |

## Key resources

- **Tasks** — Create, update, assign, and query tasks with priorities, due dates, checklists, and dependencies
- **Spaces** — Top-level organizational containers within a workspace with their own settings and features
- **Lists** — Task containers within folders or spaces that hold the actual work items
- **Goals** — Define measurable targets with progress tracking linked to task completion
- **Time Entries** — Log billable and non-billable time against tasks for workload and cost tracking
- **Webhooks** — Subscribe to workspace events for real-time automation triggers

## Why Jentic

- **Setup:** Wiring the ClickUp API by hand means setting the Authorization API key header on every call to api.clickup.com and mapping the right operation across lists, tasks, time entries, and goals yourself. Through Jentic you install once, import the ClickUp API from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** ClickUp puts list, task, and team ids in the URL path (/list/{list_id}/task, /task/{task_id}, /team/{team_id}/goal), so a rule can pin your agent to one list and the tasks under it. You choose the operations it may call, so writes like adding task dependencies are not included unless you add them.
- **Credential handling:** Your ClickUp API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a task in ClickUp with assignees' or 'log time against a task', and Jentic returns the matching ClickUp operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Asana** — Asana offers flat project-based task management with stronger goal and portfolio tracking features
- **monday.com API** — monday.com uses a visual board/column model with GraphQL access suited to non-technical teams
- **Jira** — Jira is purpose-built for software teams with sprints, story points, and release versioning
- **Slack Web API** — Slack provides team messaging for task notifications, assignment alerts, and status updates

## FAQ

### Why is there no official OpenAPI spec for ClickUp API?

ClickUp does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call ClickUp API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the ClickUp API use?

The ClickUp API uses API key authentication. Include your personal API token in the Authorization header. Keys are generated from ClickUp Settings > Apps. Through Jentic, these API keys are stored encrypted in your Jentic One instance and agents receive scoped credentials without handling raw secrets.

### Can I create tasks with checklists using the ClickUp API?

Yes. First create the task via POST /api/v2/list/{list_id}/task with name, assignees, due_date, and priority. Then add a checklist via POST /api/v2/task/{task_id}/checklist with a name and items array. Each checklist item can have an assignee and order index.

### What are the rate limits for the ClickUp API?

ClickUp enforces a rate limit of 100 requests per minute per API token for most endpoints. Responses include X-RateLimit-Limit and X-RateLimit-Remaining headers. For bulk operations, batch your requests and respect the retry-after header when limits are hit.

### How do I log time against a task through Jentic?

Search Jentic for 'log time entry clickup task'. Jentic returns the POST /api/v2/team/{team_id}/time_entries endpoint schema with duration (in milliseconds), task_id, billable flag, and description parameters. Load the schema, set your values, and execute to record the time entry.

### How is the ClickUp workspace hierarchy structured?

ClickUp uses a five-level hierarchy: Workspace > Space > Folder > List > Task. The API reflects this - you query spaces under a team, folders under a space, lists under a folder, and tasks under a list. Tasks can also have subtasks. Goals exist at the team level outside this hierarchy.

### Can I limit what my agent is allowed to do with the ClickUp API?

Yes. Because you self-host Jentic One, your own rules decide which ClickUp operations and credentials the agent may use. Since ClickUp puts list, task, and team ids in the URL path (/list/{list_id}/task, /task/{task_id}, /team/{team_id}/goal), you can pin the agent to a single list and the tasks under it. You also pick the exact operations it may call, so write actions like adding task dependencies stay off limits unless you include them.