Skip to content
Go to file
8 contributors

Users who have contributed to this file

@tanel @refiito @osamu2001 @MichaelDanilov @kanet77 @glensc @gilberthdez @charlesfsl
140 lines (119 sloc) 4.35 KB

Toggl API v8

The API accepts only JSON requests. Please make sure you're setting Content-Type: application/jsonin your request header. Each request returns a JSON-encoded body. If the time entry is currently running, the duration attribute contains a negative value, denoting the start of the time entry in seconds since epoch (Jan 1 1970). The correct duration can be calculated as current_time + duration, where current_time is the current time in seconds since epoch.

The result of each action is communicated via standard HTTP response codes.


If you wish to use the API using CORS, we'll need to whitelist you first. Please refer to the CORS documentation

Successful requests

When request is successful (2xx), a nested response object is returned. Fields which value is NULL are not in the response.

Example request

curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \
	-H "Content-Type: application/json" \
	-d '{"time_entry":{"description":"New time entry","created_with":"API example code","start":"2012-02-12T15:35:47+02:00","duration":1200,"wid":31366}}' \


    "data": {
        "description": "New time entry",
        "start": "2013-02-12T15:35:47+02:00",
        "billable": false,
        "wid": 31366,
        "pid": 9012,
        "duration": 1200,
        "stop": "2013-02-12T15:35:57+02:00",
        "tags": [
        "id": 4269795

Failed requests

If a create or update action failed, HTTP status code 404 and an array of localized error messages will be returned.

curl -v -u 1971800d4d82861d8f2c1651fea4d212:api_token \
	-H 'Content-Type: application/json' \
	-d '{"time_entry":{"description":"New time entry","created_with":"API example code"}}' \


["Start can't be blank"]


To use the API, you need to authenticate yourself. This can be done via HTTP POST or HTTP Basic Auth. After successful authentication a session is created using a cookie.

If authentication fails, HTTP status code 403 is returned. You can read more about authentication and see sample requests here.

Supported API requests

  • Authenticate and get user data
    • HTTP Basic Auth with e-mail and password
    • HTTP Basic Auth with API token
    • Authentication with a session cookie
    • Destroy the session
  • Clients
    • create a client
    • get client details
    • update a client
    • delete a client
    • get clients visible to user
    • get client projects
  • Groups
    • create a group
    • update a group
    • delete a group
  • Projects
    • create a project
    • get project data
    • update project data
    • delete a project
    • get project users
    • get project tasks
    • delete multiple projects
  • Project users
    • create a project user
    • update a project user
    • delete a project user
    • add multiple users to a project
    • update multiple project users
    • delete multiple project users
  • Tags
    • create a tag
    • update a tag
    • delete a tag
  • Tasks (available only for pro workspaces)
    • create a task
    • get task details
    • update a task
    • delete a task
    • update multiple tasks
    • delete multiple tasks
  • Time entries
    • create a time entry
    • start a time entry
    • stop a time entry
    • get time entry details
    • update time entry
    • delete time entry
    • get time entries started in a specific time range
    • bulk update time entries tags
  • Users
    • get current user data and time entries
    • update current user data
    • reset API token
    • sign up new user
  • Workspaces
    • get user workspaces
    • get workspace users
    • get workspace clients
    • get workspace groups
    • get workspace projects
    • get workspace tasks
    • get workspace tags
  • Workspace users
    • invite users to workspace
    • update workspace user
    • delete workspace user
    • get workspace users for a workspace
  • Dashboard
    • Get a generic overview of your team
You can’t perform that action at this time.