{"openapi":"3.1.0","info":{"title":"Clockify Planning (BYOK) API","version":"0.1.0","description":"Clockify Planning (BYOK) lets an AI assistant read your own Clockify Planning data through the Clockify Planning API with a key you supply (API key). Read-only: 8 tools (list_assignments, list_project_workload, get_project_workload, list_time_off_policies, get_time_off_policy, list_holidays, list_user_groups, list_project_templates). The BYOK key travels with each request, is used for that one...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-clockify-planning.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-clockify-planning/docs"},"termsOfService":"https://connectorbay.com/byok-clockify-planning/terms"},"servers":[{"url":"https://byok-clockify-planning.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-clockify-planning/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_assignments":{"post":{"operationId":"list_assignments","summary":"List scheduled assignments (who is planned on which project and task, hours per day, period) in a date range. Scheduling","description":"List scheduled assignments (who is planned on which project and task, hours per day, period) in a date range. Scheduling is a paid Clockify feature. Use for \"Who is scheduled on which Clockify project this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (from the Clockify connector's list_workspaces).","maxLength":200,"title":"Workspace Id","type":"string"},"start":{"description":"Start of the period, in the form 2026-10-01T00:00:00Z.","maxLength":30,"title":"Start","type":"string"},"end":{"description":"End of the period, in the form 2026-10-31T23:59:59Z.","maxLength":30,"title":"End","type":"string"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only assignments whose name matches this text.","title":"Name"},"sort_column":{"anyOf":[{"enum":["PROJECT","USER","ID"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by PROJECT, USER or ID.","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 (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","start","end"],"title":"list_assignmentsArguments","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_workload":{"post":{"operationId":"list_project_workload","summary":"List projects with total scheduled hours in a date range, plus milestones. Paid Clockify scheduling feature. Use for \"Ho","description":"List projects with total scheduled hours in a date range, plus milestones. Paid Clockify scheduling feature. Use for \"How many hours are scheduled per Clockify project next month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (from the Clockify connector's list_workspaces).","maxLength":200,"title":"Workspace Id","type":"string"},"start":{"description":"Start of the period, in the form 2026-10-01T00:00:00Z.","maxLength":30,"title":"Start","type":"string"},"end":{"description":"End of the period, in the form 2026-10-31T23:59:59Z.","maxLength":30,"title":"End","type":"string"},"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only projects or clients whose name matches this text.","title":"Search"},"page_size":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (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","start","end"],"title":"list_project_workloadArguments","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_project_workload":{"post":{"operationId":"get_project_workload","summary":"Scheduled hours of one project in a date range, with milestones and which days have assignments. Paid Clockify schedulin","description":"Scheduled hours of one project in a date range, with milestones and which days have assignments. Paid Clockify scheduling feature. Use for \"What is the schedule for Clockify project 5b715612b079875110791111\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (from the Clockify connector's list_workspaces).","maxLength":200,"title":"Workspace Id","type":"string"},"project_id":{"description":"Project id (from list_workspace_projects of the Clockify connector or list_project_workload).","maxLength":200,"title":"Project Id","type":"string"},"start":{"description":"Start of the period, in the form 2026-10-01T00:00:00Z.","maxLength":30,"title":"Start","type":"string"},"end":{"description":"End of the period, in the form 2026-10-31T23:59:59Z.","maxLength":30,"title":"End","type":"string"}},"required":["workspace_id","project_id","start","end"],"title":"get_project_workloadArguments","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_off_policies":{"post":{"operationId":"list_time_off_policies","summary":"List time-off policies (name, unit days or hours, accrual, approval requirement, archived flag). Time off is a paid Cloc","description":"List time-off policies (name, unit days or hours, accrual, approval requirement, archived flag). Time off is a paid Clockify feature. Use for \"What time-off policies exist in Clockify\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (from the Clockify connector's list_workspaces).","maxLength":200,"title":"Workspace Id","type":"string"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only policies whose name contains this text.","title":"Name"},"status":{"anyOf":[{"enum":["ACTIVE","ARCHIVED","ALL"],"type":"string"},{"type":"null"}],"default":"ACTIVE","description":"ACTIVE, ARCHIVED or ALL.","title":"Status"},"page_size":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (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_time_off_policiesArguments","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_off_policy":{"post":{"operationId":"get_time_off_policy","summary":"Get one time-off policy with unit, accrual rule, negative balance rule and approval setting. Use for \"Show Clockify time","description":"Get one time-off policy with unit, accrual rule, negative balance rule and approval setting. Use for \"Show Clockify time-off policy 5b715612b079875110793333\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (from the Clockify connector's list_workspaces).","maxLength":200,"title":"Workspace Id","type":"string"},"policy_id":{"description":"Policy id (from list_time_off_policies).","maxLength":200,"title":"Policy Id","type":"string"}},"required":["workspace_id","policy_id"],"title":"get_time_off_policyArguments","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_holidays":{"post":{"operationId":"list_holidays","summary":"List company holidays with name, date period, whether they repeat yearly and who they apply to (counts of users and grou","description":"List company holidays with name, date period, whether they repeat yearly and who they apply to (counts of users and groups come as ids). Use for \"Which holidays are set up in Clockify\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (from the Clockify connector's list_workspaces).","maxLength":200,"title":"Workspace Id","type":"string"},"assigned_to":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only holidays assigned to this user id.","title":"Assigned To"}},"required":["workspace_id"],"title":"list_holidaysArguments","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_user_groups":{"post":{"operationId":"list_user_groups","summary":"List user groups (teams) with name, member ids and team managers. Use for \"What user groups exist in our Clockify worksp","description":"List user groups (teams) with name, member ids and team managers. Use for \"What user groups exist in our Clockify workspace\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (from the Clockify connector's list_workspaces).","maxLength":200,"title":"Workspace Id","type":"string"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only groups whose name contains this text.","title":"Name"},"project_id":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only groups assigned to this project id.","title":"Project Id"},"include_team_managers":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include each group's team managers.","title":"Include Team Managers"},"page_size":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (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_user_groupsArguments","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_templates":{"post":{"operationId":"list_project_templates","summary":"List project templates with id and name. Use for \"What project templates does our Clockify workspace have\".","description":"List project templates with id and name. Use for \"What project templates does our Clockify workspace have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"workspace_id":{"description":"Workspace id (from the Clockify connector's list_workspaces).","maxLength":200,"title":"Workspace Id","type":"string"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only templates whose name contains this text.","title":"Name"},"page_size":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results per page (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_project_templatesArguments","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}}}}