{"openapi":"3.1.0","info":{"title":"Clickup Time and Docs (BYOK) API","version":"0.1.0","description":"Clickup Time and Docs (BYOK) lets an AI assistant read your own Clickup Time and Docs data through the Clickup Time and Docs API with a key you supply (personal API token (starts with pk_)). Read-only: 9 tools (list_time_entries, get_running_time_entry, get_time_entry, list_time_entry_tags, get_task_tracked_time, get_task_time_in_status, search_docs, get_doc, get_doc_page_listing). The BYOK key...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-clickup-time-docs.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-clickup-time-docs/docs"},"termsOfService":"https://connectorbay.com/byok-clickup-time-docs/terms"},"servers":[{"url":"https://byok-clickup-time-docs.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-clickup-time-docs/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/list_time_entries":{"post":{"operationId":"list_time_entries","summary":"List tracked time entries in a date range (last 30 days of the key's own entries by default) with task, location, durati","description":"List tracked time entries in a date range (last 30 days of the key's own entries by default) with task, location, duration in milliseconds, billable flag and tags. Needs the Time Tracking ClickApp. Use for \"What time did I track in ClickUp this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (called team id in older ClickUp docs; from the ClickUp connector's list_workspaces).","minimum":1,"title":"Workspace Id","type":"integer"},"start_date":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Start of the range as Unix time in milliseconds.","title":"Start Date"},"end_date":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"End of the range as Unix time in milliseconds.","title":"End Date"},"assignee":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"User id(s) to read entries of, comma-separated (needs permission to see other people's time).","title":"Assignee"},"space_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only entries of tasks in this Space id.","title":"Space Id"},"folder_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only entries of tasks in this Folder id.","title":"Folder Id"},"list_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only entries of tasks in this List id.","title":"List Id"},"task_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only entries of this task id.","title":"Task Id"},"is_billable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for billable entries only, false for non-billable only.","title":"Is Billable"},"include_location_names":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to add List, Folder and Space names.","title":"Include Location Names"}},"required":["workspace_id"],"title":"list_time_entriesArguments","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_running_time_entry":{"post":{"operationId":"get_running_time_entry","summary":"Show the timer running right now for the key's user (negative duration while running), or an empty answer when none is r","description":"Show the timer running right now for the key's user (negative duration while running), or an empty answer when none is running. Use for \"Is my ClickUp timer running and on which task\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (called team id in older ClickUp docs; from the ClickUp connector's list_workspaces).","minimum":1,"title":"Workspace Id","type":"integer"}},"required":["workspace_id"],"title":"get_running_time_entryArguments","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_time_entry":{"post":{"operationId":"get_time_entry","summary":"Get one time entry by id with task, location, start, end, duration, tags and billable flag. Use for \"Show ClickUp time e","description":"Get one time entry by id with task, location, start, end, duration, tags and billable flag. Use for \"Show ClickUp time entry 2004182123456789\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (called team id in older ClickUp docs; from the ClickUp connector's list_workspaces).","minimum":1,"title":"Workspace Id","type":"integer"},"timer_id":{"description":"Time entry id (from list_time_entries).","maxLength":40,"title":"Timer Id","type":"string"},"include_location_names":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to add List, Folder and Space names.","title":"Include Location Names"}},"required":["workspace_id","timer_id"],"title":"get_time_entryArguments","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_time_entry_tags":{"post":{"operationId":"list_time_entry_tags","summary":"List the tags that have been applied to time entries in the workspace, with colours. Use for \"Which tags are used on Cli","description":"List the tags that have been applied to time entries in the workspace, with colours. Use for \"Which tags are used on ClickUp time entries\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (called team id in older ClickUp docs; from the ClickUp connector's list_workspaces).","minimum":1,"title":"Workspace Id","type":"integer"}},"required":["workspace_id"],"title":"list_time_entry_tagsArguments","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_tracked_time":{"post":{"operationId":"get_task_tracked_time","summary":"Get the time tracked on one task per user with each interval (legacy ClickUp endpoint; time is in milliseconds). Use for","description":"Get the time tracked on one task per user with each interval (legacy ClickUp endpoint; time is in milliseconds). Use for \"How much time was tracked on ClickUp task 86abc123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"task_id":{"description":"Task id, for example '86abc123'.","maxLength":40,"title":"Task Id","type":"string"}},"required":["task_id"],"title":"get_task_tracked_timeArguments","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_time_in_status":{"post":{"operationId":"get_task_time_in_status","summary":"Show how long a task has been in its current status and in each earlier status (needs the Total time in Status ClickApp)","description":"Show how long a task has been in its current status and in each earlier status (needs the Total time in Status ClickApp). Use for \"How long did ClickUp task 86abc123 sit in review\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"task_id":{"description":"Task id, for example '86abc123'.","maxLength":40,"title":"Task Id","type":"string"}},"required":["task_id"],"title":"get_task_time_in_statusArguments","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/search_docs":{"post":{"operationId":"search_docs","summary":"List ClickUp Docs of a workspace (name, parent, creator id, dates, public flag) with cursor paging; Docs the key cannot ","description":"List ClickUp Docs of a workspace (name, parent, creator id, dates, public flag) with cursor paging; Docs the key cannot access are left out. Use for \"Which ClickUp Docs exist in our workspace\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (called team id in older ClickUp docs; from the ClickUp connector's list_workspaces).","minimum":1,"title":"Workspace Id","type":"integer"},"parent_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only Docs below this parent id.","title":"Parent Id"},"parent_type":{"anyOf":[{"enum":["SPACE","FOLDER","LIST","EVERYTHING","WORKSPACE"],"type":"string"},{"type":"null"}],"default":null,"description":"Type of the parent: SPACE, FOLDER, LIST, EVERYTHING or WORKSPACE.","title":"Parent Type"},"creator":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only Docs created by this user id.","title":"Creator"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to return archived Docs.","title":"Archived"},"deleted":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to return deleted Docs.","title":"Deleted"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many Docs to return per page.","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's next_cursor, for the next page.","title":"Cursor"}},"required":["workspace_id"],"title":"search_docsArguments","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_doc":{"post":{"operationId":"get_doc","summary":"Get one Doc's name, parent, creator id, public, archived and deleted flags and dates (not its page text). Use for \"Show ","description":"Get one Doc's name, parent, creator id, public, archived and deleted flags and dates (not its page text). Use for \"Show ClickUp Doc 8cd9v-1234\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (called team id in older ClickUp docs; from the ClickUp connector's list_workspaces).","minimum":1,"title":"Workspace Id","type":"integer"},"doc_id":{"description":"Doc id (from search_docs).","maxLength":40,"title":"Doc Id","type":"string"}},"required":["workspace_id","doc_id"],"title":"get_docArguments","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_doc_page_listing":{"post":{"operationId":"get_doc_page_listing","summary":"Show the page tree of a Doc: page ids, names and nesting (titles only, not page text). Use for \"What pages does ClickUp ","description":"Show the page tree of a Doc: page ids, names and nesting (titles only, not page text). Use for \"What pages does ClickUp Doc 8cd9v-1234 contain\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (called team id in older ClickUp docs; from the ClickUp connector's list_workspaces).","minimum":1,"title":"Workspace Id","type":"integer"},"doc_id":{"description":"Doc id (from search_docs).","maxLength":40,"title":"Doc Id","type":"string"},"max_page_depth":{"anyOf":[{"maximum":20,"minimum":-1,"type":"integer"},{"type":"null"}],"default":-1,"description":"How deep to list sub-pages; -1 for all levels.","title":"Max Page Depth"}},"required":["workspace_id","doc_id"],"title":"get_doc_page_listingArguments","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}}}}