Clockify Scheduling & Team Capacity
Who has room for another project next week? Plan work in Clockify Scheduling: list assignments in a date range, compare each person's capacity with the hours already booked, total scheduled hours per project, add or copy recurring assignments, and publish the schedule so the team sees it.
Connect this API to an AI agent Browse all specs
What you can do with Clockify Scheduling & Team Capacity via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /v1/user |
getCurrentUser | Get the user the API key belongs to (id, active workspace) |
| GET | /v1/workspaces/{workspaceId}/users |
listWorkspaceUsers | List people in the workspace to find their user ids |
| GET | /v1/workspaces/{workspaceId}/projects |
listProjects | List projects to find their ids |
| GET | /v1/workspaces/{workspaceId}/scheduling/assignments/all |
listAssignments | List scheduled assignments between two dates |
| POST | /v1/workspaces/{workspaceId}/scheduling/assignments/user-filter/totals |
getTeamCapacity | Get each person's capacity and scheduled hours for a period |
| GET | /v1/workspaces/{workspaceId}/scheduling/assignments/users/{userId}/totals |
getUserCapacity | Get one person's capacity and scheduled hours for a period |
| POST | /v1/workspaces/{workspaceId}/scheduling/assignments/projects/totals |
getProjectScheduleTotals | Get scheduled hours per project for a period, with filters |
| GET | /v1/workspaces/{workspaceId}/scheduling/assignments/projects/totals/{projectId} |
getProjectSchedule | Get the scheduled assignments and hours on one project |
| POST | /v1/workspaces/{workspaceId}/scheduling/assignments/recurring |
createAssignment | Assign a person to a project for a period, optionally repeating weekly |
| PATCH | /v1/workspaces/{workspaceId}/scheduling/assignments/recurring/{assignmentId} |
updateAssignment | Change an assignment's dates, hours per day or note |
| PUT | /v1/workspaces/{workspaceId}/scheduling/assignments/series/{assignmentId} |
changeRecurringPeriod | Change how long a recurring assignment repeats |
| POST | /v1/workspaces/{workspaceId}/scheduling/assignments/{assignmentId}/copy |
copyAssignment | Copy an assignment to another person |
| PUT | /v1/workspaces/{workspaceId}/scheduling/assignments/publish |
publishAssignments | Publish the schedule for a period and optionally notify the team |
Authentication
ApiKeyAuth
API key — sent as the X-Api-Key header
Clockify personal API key, sent in the X-Api-Key header.
How to get a credential
- Sign in to Clockify and open Profile settings (avatar, top right).
- Scroll to API (Preferences > Advanced in newer layouts) and click Generate (or Manage API keys > Generate new).
- Copy the key. It acts as you, with your role in every workspace you belong to.
- Scheduling must be turned on for the workspace (Workspace settings > General > Scheduling; it is a paid-plan feature).
Permissions used
Clockify API keys have no scopes: every call runs with your role in the workspace, and the workspace's scheduling settings decide who may see or plan whose schedule.
| Access | Operations |
|---|---|
| Read (what your role can see) | getCurrentUser, listWorkspaceUsers, listProjects, listAssignments, getTeamCapacity, getUserCapacity, getProjectScheduleTotals, getProjectSchedule |
| Plan (a role allowed to schedule, typically an admin or manager) | createAssignment, updateAssignment, changeRecurringPeriod, copyAssignment, publishAssignments |
Common errors
- 401 Unauthorized: the key is missing or was regenerated; generate a new one in Profile settings.
- 403 Forbidden: Scheduling is off for the workspace, or your role cannot schedule people on that project.
- 400 Bad Request:
start/endnot inyyyy-MM-ddThh:mm:ssZ,endbeforestart, or a missinguserId,projectIdorhoursPerDayon create. - 429 Too Many Requests: limit is 50 requests per second per workspace; wait and retry.
Data stored in the EU/UK/AU/US regions uses a regional host; the key itself works the same. Store the key as a VX Agents credential for this spec; never paste it into chat.
Usage guide
Setup
- Credential: a Clockify API key (
X-Api-Key). Scheduling must be enabled for the workspace. - Worth pinning: your
workspaceId(fromgetCurrentUser→activeWorkspace), so every call reuses it.
Plan next week's work
- Find ids:
getCurrentUser, thenlistWorkspaceUsers(filter bynameoremail) andlistProjects(filter byname). - Who has room:
getTeamCapacitywithstartandend(and optionalsearch,userFilter.ids,statusFilter) returns each person's capacity next to the hours already scheduled. For one person usegetUserCapacity. - What is booked:
listAssignmentswithstartandend(required) lists assignments in the range;getProjectScheduleTotalstotals scheduled hours per project andgetProjectScheduleshows one project. - Book someone:
createAssignmentwithuserId,projectId,start,end,hoursPerDay(optionalnote,billable,taskId,includeNonWorkingDays). To repeat it, addrecurringAssignmentwithfrequency(WEEKLYorMONTHLY),interval(1 = every week/month, 2 = every other) andrecurringEndType(AFTER_OCCURRENCES+occurrences, orUNTIL_DATE+until). - Adjust:
updateAssignment(dates, hours, note;seriesUpdateOption=THIS_ONE,THIS_AND_FOLLOWINGorALL),changeRecurringPeriodfor the repeat,copyAssignmentto give the same work to anotheruserId. - Share it:
publishAssignmentswithstart,endandnotifyUsers: trueto publish the period and notify the people involved.
Confirm with the user before creating, changing or publishing assignments: published schedules notify the team.
Good to know
- Dates are
yyyy-MM-ddThh:mm:ssZ(UTC), e.g.2026-11-02T00:00:00Z;startTimeishh:mm:ss. - Assignments can be published or unpublished;
statusFilter(PUBLISHED,UNPUBLISHED,ALL) picks which ones count in totals. - Pages use
pageandpage-size(query) orpage/pageSize(body). - Rate limit: 50 requests per second per workspace. Regional workspaces (EU, UK, AU) use a regional API host.
Source: Clockify API reference (https://docs.clockify.me/), checked 2026-10-25.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Clockify Scheduling & Team Capacity” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.