Overview

This documentation focuses on current API v9 and the old v8 version will soon be deprecated. The documentation is already extended to Webhooks API and will soon be extended to missing services like Reports API v3.

The documentation is split between a friendly Getting Started section, introducing the most important domains and how to interact with them, and a API Reference section, with a detailed listing of available endpoints and configurations.

For more details about the involved entities, domains or product related features, please refer to Toggl Track Knowledge Center.

The API Format

The API accepts only JSON requests. Please make sure you're setting Content-Type: application/json in your request header. Each request returns a JSON-encoded body. The result of each action is communicated via standard HTTP response codes.

Times and dates use the ISO 8601 standard, more specifically a subset described in RFC 3339. Please do note that the times and dates are stored in UTC (GMT), on return the data is set into the appropriate timezone according to the setting in user profile. 3rd party applications should make sure that they are using correct timezones and also consider daylight saving (where applicable).

For rate limiting we have implemented a Leaky bucket. When a limit has been hit the request will get a HTTP 429 response and it's the task of the client to sleep/wait until bucket is empty. Limits will and can change during time, but a safe window will be 1 request per second. Limiting is applied per api token per IP, meaning two users from the same IP will get their rate allocated separately.

General principles

• API format is JSON (be nice and include a Content-type: application/json header to your request)
• in case of an update request, send only the fields that have changed
• do not include fields that aren't available for current workspace subscription level (example: on a free plan don't send the default workspace rate when updating workspace)
• fetch only the data you need

Eventual Consistency

Our API authorization layer operates within an event-based service architecture designed to achieve eventual consistency. Under certain circumstances, it may take a few seconds for your session state to be updated after a change is made.

When creating new entities such as organizations, workspaces, projects, or groups, you will need to wait for the new entity to be added to your session before you can use it. Operations like adding users to recently created projects may need to be artificially delayed. We recommend waiting between 2 to 5 seconds and performing up to 3 retries, if necessary.

Alternatively, you can find the last session update timestamp using the /me endpoint to verify if or when your session was updated.

Generic responses

We're using standard HTTP status codes and kindly ask the API clients to respect some recommendations:

• in case of 4xx error - don't try another request with the same payload, inspect the response body, most of the times it has a readable message
• in case of 5xx error - have a random delay before the next request
• in case of 429 (Too Many Requests) - back off for a few minutes (you can expect a rate of 1req/sec to be available)
• in case of 410 (Gone) - don't try this endpoint again
• in case of 402 (Payment required) - workspace should be upgraded to have access to said feature, don't repeat the request until that has happened