{"openapi":"3.1.0","info":{"title":"ClickUp (BYOK) API","version":"0.1.0","description":"ClickUp (BYOK) lets an AI assistant read your own ClickUp data through the ClickUp API with a key you supply (personal API token (starts with pk_)). Read-only: 10 tools (get_authorized_user, list_workspaces, list_spaces, list_folders, list_lists, list_folderless_lists, list_tasks, get_task, list_task_comments, list_goals). The BYOK key travels with each request, is used for that one call only and...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-clickup.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-clickup/docs"},"termsOfService":"https://connectorbay.com/byok-clickup/terms"},"servers":[{"url":"https://byok-clickup.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-clickup/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_authorized_user":{"post":{"operationId":"get_authorized_user","summary":"Show the ClickUp user the token belongs to: ID, username and email. Use for \"Which ClickUp account is my token connected","description":"Show the ClickUp user the token belongs to: ID, username and email. Use for \"Which ClickUp account is my token connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_authorized_userArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_workspaces":{"post":{"operationId":"list_workspaces","summary":"List the Workspaces the token can access with their IDs and names. The Workspace ID is needed by most other tools. Use f","description":"List the Workspaces the token can access with their IDs and names. The Workspace ID is needed by most other tools. Use for \"Which ClickUp workspaces do I belong to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_workspacesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_spaces":{"post":{"operationId":"list_spaces","summary":"List the Spaces of a Workspace with name, privacy and archive flags. Member details are only returned for private Spaces","description":"List the Spaces of a Workspace with name, privacy and archive flags. Member details are only returned for private Spaces. Use for \"What spaces are in my ClickUp workspace\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_id":{"description":"Workspace ID (called team_id by ClickUp); list yours with list_workspaces.","maxLength":200,"title":"Team Id","type":"string"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to show archived items instead of active ones.","title":"Archived"}},"required":["team_id"],"title":"list_spacesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_folders":{"post":{"operationId":"list_folders","summary":"List the Folders of a Space with name, task count and archive flag. Subfolders appear in the same flat list with a paren","description":"List the Folders of a Space with name, task count and archive flag. Subfolders appear in the same flat list with a parent_folder field. Use for \"What folders are in this ClickUp space\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"space_id":{"description":"Space ID; list them with list_spaces.","maxLength":200,"title":"Space Id","type":"string"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to show archived items instead of active ones.","title":"Archived"}},"required":["space_id"],"title":"list_foldersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_lists":{"post":{"operationId":"list_lists","summary":"List the Lists inside a Folder with name, task count, due date and archive flag. Use for \"What lists are in this ClickUp","description":"List the Lists inside a Folder with name, task count, due date and archive flag. Use for \"What lists are in this ClickUp folder\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"folder_id":{"description":"Folder ID; list them with list_folders.","maxLength":200,"title":"Folder Id","type":"string"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to show archived items instead of active ones.","title":"Archived"}},"required":["folder_id"],"title":"list_listsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_folderless_lists":{"post":{"operationId":"list_folderless_lists","summary":"List the Lists of a Space that are not inside any Folder, with name, task count, due date and archive flag. Use for \"Whi","description":"List the Lists of a Space that are not inside any Folder, with name, task count, due date and archive flag. Use for \"Which lists in this ClickUp space have no folder\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"space_id":{"description":"Space ID; list them with list_spaces.","maxLength":200,"title":"Space Id","type":"string"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to show archived items instead of active ones.","title":"Archived"}},"required":["space_id"],"title":"list_folderless_listsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_tasks":{"post":{"operationId":"list_tasks","summary":"List the tasks whose home is one List, 100 per page, with status, assignees, due date, priority and URL. Subtasks and cl","description":"List the tasks whose home is one List, 100 per page, with status, assignees, due date, priority and URL. Subtasks and closed tasks are left out unless requested. Use for \"What open tasks are in this ClickUp list\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"list_id":{"description":"List ID; list them with list_lists or list_folderless_lists.","maxLength":200,"title":"List Id","type":"string"},"page":{"anyOf":[{"maximum":10000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number, starting at 0.","title":"Page"},"order_by":{"anyOf":[{"enum":["id","created","updated","due_date"],"type":"string"},{"type":"null"}],"default":"created","description":"Order by id, created, updated or due_date (default created).","title":"Order By"},"reverse":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to reverse the order.","title":"Reverse"},"subtasks":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include subtasks.","title":"Subtasks"},"include_closed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include closed tasks.","title":"Include Closed"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to show archived items instead of active ones.","title":"Archived"},"date_updated_gt":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only tasks updated after this Unix time in milliseconds.","title":"Date Updated Gt"},"due_date_lt":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only tasks due before this Unix time in milliseconds.","title":"Due Date Lt"}},"required":["list_id"],"title":"list_tasksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_task":{"post":{"operationId":"get_task","summary":"Get one task by ID with description, status, priority, assignees, dates, tags, custom fields and location. Use for \"Show","description":"Get one task by ID with description, status, priority, assignees, dates, tags, custom fields and location. Use for \"Show the details of ClickUp task 86abc123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"task_id":{"description":"Task ID, for example '86abc123'.","maxLength":200,"title":"Task Id","type":"string"},"include_subtasks":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include the task's subtasks.","title":"Include Subtasks"},"include_markdown_description":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to return the description as Markdown.","title":"Include Markdown Description"}},"required":["task_id"],"title":"get_taskArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_task_comments":{"post":{"operationId":"list_task_comments","summary":"List a task's comments, newest first, 25 per request, with text, author, time and resolved flag. To page, send the date ","description":"List a task's comments, newest first, 25 per request, with text, author, time and resolved flag. To page, send the date and id of the last comment as start and start_id. Use for \"What are the comments on ClickUp task 86abc123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"task_id":{"description":"Task ID, for example '86abc123'.","maxLength":200,"title":"Task Id","type":"string"},"start":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Unix time in milliseconds of the last comment of the previous page (use with start_id).","title":"Start"},"start_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"ID of the last comment of the previous page (use with start).","title":"Start Id"}},"required":["task_id"],"title":"list_task_commentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_goals":{"post":{"operationId":"list_goals","summary":"List the Goals of a Workspace with name, due date, completion percentage and key result count. Use for \"How are our Clic","description":"List the Goals of a Workspace with name, due date, completion percentage and key result count. Use for \"How are our ClickUp goals doing\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_id":{"description":"Workspace ID (called team_id by ClickUp); list yours with list_workspaces.","maxLength":200,"title":"Team Id","type":"string"},"include_completed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include completed goals.","title":"Include Completed"}},"required":["team_id"],"title":"list_goalsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}