Authenticate using HTTP Basic Auth with your Toggl API token as the username and the literal string api_token as the password.
POST to /api/v9/workspaces/{workspace_id}/time_entries with a JSON body containing description, project_id (optional), tag_ids (optional), and a start timestamp in ISO 8601 UTC; set duration to -1 to indicate a running timer.
Store the returned time_entry id; this ID is required to stop the timer.
PATCH to /api/v9/workspaces/{workspace_id}/time_entries/{time_entry_id}/stop to stop the currently running timer; the server sets the stop time and calculates duration.
Retrieve the completed entry by GET /api/v9/workspaces/{workspace_id}/time_entries/{time_entry_id} to confirm stop time and duration.
If you need to modify the entry after stopping (e.g., add a project), PUT to the same time entry endpoint with the full updated entry object.
Known gotchas
Only one timer can be running at a time per user; starting a new timer while one is already running does not automatically stop the previous one—check for a running entry first.
The duration field of -1 is a Toggl-specific convention for indicating a running timer; other negative values or zero may cause validation errors.
PUT (full update) is required for most time entry modifications on the v9 API; PATCH with partial fields is only supported on specific operations like /stop.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp