{"openapi":"3.1.0","info":{"title":"Clockify (BYOK) API","version":"0.1.0","description":"Clockify (BYOK) lets an AI assistant read your own Clockify data through the Clockify API with a key you supply (API key). Read-only: 9 tools (get_current_user, list_workspaces, list_workspace_users, list_projects, list_clients, list_tags, list_project_tasks, list_time_entries, list_running_timers). The BYOK key travels with each request, is used for that one call only and is never stored, logged...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-clockify.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-clockify/docs"},"termsOfService":"https://connectorbay.com/byok-clockify/terms"},"servers":[{"url":"https://byok-clockify.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-clockify/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_current_user":{"post":{"operationId":"get_current_user","summary":"Show the Clockify user the key belongs to: id (needed for time entries), name, email, active and default workspace ids, ","description":"Show the Clockify user the key belongs to: id (needed for time entries), name, email, active and default workspace ids, and status. Use for \"Which Clockify account is my API key for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_current_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 you belong to with id, name, hourly rate and plan type; filter by your role. Use for \"What Clockify ","description":"List the workspaces you belong to with id, name, hourly rate and plan type; filter by your role. Use for \"What Clockify workspaces am I in\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"roles":{"anyOf":[{"enum":["WORKSPACE_ADMIN","OWNER","TEAM_MANAGER","PROJECT_MANAGER"],"type":"string"},{"type":"null"}],"default":null,"description":"Only workspaces where you hold this role.","title":"Roles"}},"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_workspace_users":{"post":{"operationId":"list_workspace_users","summary":"List members of a workspace with name, email, status and default workspace; filter by name, email, project or status. Us","description":"List members of a workspace with name, email, status and default workspace; filter by name, email, project or status. Use for \"Who are the members of my Clockify workspace\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (from list_workspaces, or the active_workspace of get_current_user).","maxLength":200,"title":"Workspace Id","type":"string"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only users whose name contains this text.","title":"Search"},"email":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only users whose email contains this text.","title":"Email"},"status":{"anyOf":[{"enum":["PENDING","ACTIVE","DECLINED","INACTIVE","ALL"],"type":"string"},{"type":"null"}],"default":null,"description":"Membership status: PENDING, ACTIVE, DECLINED, INACTIVE or ALL.","title":"Status"},"project_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only users with access to this project id.","title":"Project Id"},"sort_column":{"anyOf":[{"enum":["ID","EMAIL","NAME","NAME_LOWERCASE","ACCESS","HOURLYRATE","COSTRATE"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by ID, EMAIL (default), NAME, NAME_LOWERCASE, ACCESS, HOURLYRATE or COSTRATE.","title":"Sort Column"},"sort_order":{"anyOf":[{"enum":["ASCENDING","DESCENDING"],"type":"string"},{"type":"null"}],"default":null,"description":"ASCENDING (default) or DESCENDING.","title":"Sort Order"},"include_roles":{"anyOf":[{"enum":["true","false"],"type":"string"},{"type":"null"}],"default":"false","description":"Set true to include each user's detailed manager roles; default false.","title":"Include Roles"},"page_size":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (1 to 200, default 50).","title":"Page Size"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["workspace_id"],"title":"list_workspace_usersArguments","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_projects":{"post":{"operationId":"list_projects","summary":"List the projects of a workspace with name, color, billable and archived flags, public flag, note and duration; filter b","description":"List the projects of a workspace with name, color, billable and archived flags, public flag, note and duration; filter by name, archived or billable. Use for \"What projects do I have in Clockify\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (from list_workspaces, or the active_workspace of get_current_user).","maxLength":200,"title":"Workspace Id","type":"string"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only projects whose name contains this text.","title":"Search"},"strict_name_search":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to match the name exactly instead of by substring.","title":"Strict Name Search"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only archived projects; leave empty for both archived and active.","title":"Archived"},"billable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only billable projects; leave empty for both.","title":"Billable"},"sort_column":{"anyOf":[{"enum":["ID","NAME","CLIENT_NAME","DURATION","BUDGET","PROGRESS"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by ID, NAME, CLIENT_NAME, DURATION, BUDGET or PROGRESS.","title":"Sort Column"},"sort_order":{"anyOf":[{"enum":["ASCENDING","DESCENDING"],"type":"string"},{"type":"null"}],"default":null,"description":"ASCENDING or DESCENDING.","title":"Sort Order"},"page_size":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (1 to 200, default 50).","title":"Page Size"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["workspace_id"],"title":"list_projectsArguments","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_clients":{"post":{"operationId":"list_clients","summary":"List the clients of a workspace with name, email, address, currency and archived flag. Use for \"Which clients do I have ","description":"List the clients of a workspace with name, email, address, currency and archived flag. Use for \"Which clients do I have in Clockify\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (from list_workspaces, or the active_workspace of get_current_user).","maxLength":200,"title":"Workspace Id","type":"string"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only clients whose name contains this text.","title":"Search"},"archived":{"anyOf":[{"enum":["true","false"],"type":"string"},{"type":"null"}],"default":null,"description":"Set to true or false to filter archived clients; leave empty for default behavior.","title":"Archived"},"sort_order":{"anyOf":[{"enum":["ASCENDING","DESCENDING"],"type":"string"},{"type":"null"}],"default":null,"description":"ASCENDING or DESCENDING (sorted by name).","title":"Sort Order"},"page_size":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (1 to 200, default 50).","title":"Page Size"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["workspace_id"],"title":"list_clientsArguments","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_tags":{"post":{"operationId":"list_tags","summary":"List the tags of a workspace with id, name and archived flag. Use for \"What tags exist in my Clockify workspace\".","description":"List the tags of a workspace with id, name and archived flag. Use for \"What tags exist in my Clockify workspace\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (from list_workspaces, or the active_workspace of get_current_user).","maxLength":200,"title":"Workspace Id","type":"string"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only tags whose name contains this text.","title":"Search"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only archived tags, false for only active tags.","title":"Archived"},"sort_order":{"anyOf":[{"enum":["ASCENDING","DESCENDING"],"type":"string"},{"type":"null"}],"default":null,"description":"ASCENDING or DESCENDING.","title":"Sort Order"},"page_size":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (1 to 200, default 50).","title":"Page Size"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["workspace_id"],"title":"list_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/list_project_tasks":{"post":{"operationId":"list_project_tasks","summary":"List the tasks of one project with name, status, billable flag, assignees and estimate. Use for \"What tasks are in my Cl","description":"List the tasks of one project with name, status, billable flag, assignees and estimate. Use for \"What tasks are in my Clockify project\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (from list_workspaces, or the active_workspace of get_current_user).","maxLength":200,"title":"Workspace Id","type":"string"},"project_id":{"description":"Project id from list_projects.","maxLength":200,"title":"Project Id","type":"string"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only tasks whose name contains this text.","title":"Search"},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only active tasks.","title":"Is Active"},"sort_order":{"anyOf":[{"enum":["ASCENDING","DESCENDING"],"type":"string"},{"type":"null"}],"default":null,"description":"ASCENDING or DESCENDING.","title":"Sort Order"},"page_size":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (1 to 200, default 50).","title":"Page Size"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["workspace_id","project_id"],"title":"list_project_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/list_time_entries":{"post":{"operationId":"list_time_entries","summary":"List one user's time entries in a workspace, newest first, with description, project, task, tags, billable flag, start, ","description":"List one user's time entries in a workspace, newest first, with description, project, task, tags, billable flag, start, end and duration; filter by time range, project or description. Use for \"What did I track in Clockify this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (from list_workspaces, or the active_workspace of get_current_user).","maxLength":200,"title":"Workspace Id","type":"string"},"user_id":{"description":"User id (your own id comes from get_current_user).","maxLength":200,"title":"User Id","type":"string"},"start":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only entries starting at or after this UTC time, format yyyy-MM-ddTHH:mm:ssZ, for example 2026-10-12T00:00:00Z.","title":"Start"},"end":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only entries ending at or before this UTC time, same format.","title":"End"},"project":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only entries of this project id.","title":"Project"},"description":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only entries whose description contains this text.","title":"Description"},"in_progress":{"anyOf":[{"enum":["true","false"],"type":"string"},{"type":"null"}],"default":null,"description":"Set to true to list only the running timer.","title":"In Progress"},"page_size":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (1 to 200, default 50).","title":"Page Size"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["workspace_id","user_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/list_running_timers":{"post":{"operationId":"list_running_timers","summary":"List all time entries that are currently running (timers not yet stopped) across the workspace, with user, project and s","description":"List all time entries that are currently running (timers not yet stopped) across the workspace, with user, project and start time. Use for \"Who has a Clockify timer running right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (from list_workspaces, or the active_workspace of get_current_user).","maxLength":200,"title":"Workspace Id","type":"string"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 1000, default 10).","title":"Page Size"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["workspace_id"],"title":"list_running_timersArguments","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}}}}