Tyme Public API Documentation
To get access to the API, please drop us a message.
- API Endpoint: https://api.tyme-app.com
- All dates & times exchanged in GMT+0.
- Date Format: Y-m-d H:i:s Example: 2025-12-31 23:59:59
- The exchange format is JSON.
- You need to have a team and be a team admin. You can create a new team in Tyme > File > Login > Create Team.
Authentication
Tyme uses the OAuth v2 standard for authenticating users.
To make yourself familiar with OAuth, please take a look at the rfc6749.
Auth Endpoint
Login form to log the user in and redirect them to your app
GET /v1/authorize
Parameter |
Type |
Description |
response_type |
String |
Must be code |
client_id |
String |
Your client ID |
state |
String |
Your state |
redirect_uri |
String |
Your redirect_uri |
Access Token Endpoint
Exchange the authcode with an access & refresh token
POST /v1/access_token
Parameter |
Type |
Description |
grant_type |
String |
Must be authorization_code |
code |
String |
Your auth code |
redirect_uri |
String |
Your redirect_uri |
client_id |
String |
Your client ID |
client_secret |
String |
Your client secret |
Refresh Token Endpoint
Exchange the refresh token with a new access & refresh token
POST /v1/refresh_token
Parameter |
Type |
Description |
grant_type |
String |
Must be refresh_token |
refresh_token |
String |
Your refresh token |
client_id |
String |
Your client ID |
client_secret |
String |
Your client secret |
Webhooks
You can use webhooks to subscribe for realtime notifications. The following notifications are available:
- New category created
- New project created
- New task created
- New sub-task created
- New time entry created
- Stopped time entry
Subscribing to a webhook
POST /webhooks/subscribe
Parameter |
Type |
Description |
hook_url |
String |
The URL that should be called from the webhook |
trigger_type |
String |
category, project, task, subtask, time or stopped_time |
Response
Status Code |
Parameter |
Value |
200 |
status |
success |
403 |
error |
not_allowed |
400 |
error |
missing values |
Your response when your webhook is called
Status Code |
Description |
200 |
OK |
410 |
Webhook subscription inactive, stop sending data |
Unsubscribing from a webhook
POST /webhooks/unsubscribe
Parameter |
Type |
Description |
hook_url |
String |
The URL that should be called from the webhook |
trigger_type |
String |
category, project task, subtask, time or stopped_time |
Response
Status Code |
Parameter |
Value |
200 |
status |
success |
403 |
error |
not_allowed |
400 |
error |
missing values |
Searching for entities
GET /data/search_entity
Parameter |
Type |
Description |
type |
String |
ProjectCategory, Project ,TimedTask or TimedSubTask |
name |
String? |
Name to search for |
parent_id |
String? |
ID of the parent entity. For example a project ID when searching for a task |
Response
Status Code |
Parameter |
Value |
200 |
Array |
found results |
403 |
error |
not_allowed |
400 |
error |
missing values |
Inserting & Updating
POST /data/update_entity
Category
Parameter |
Type |
Description |
type |
String |
Must be ProjectCategory |
id |
String? |
ID of the category. If not provided, Tyme will generate a unique ID |
name |
String |
Name of the category |
color |
Int? |
i.e 0xFF9900 |
Project
Parameter |
Type |
Description |
type |
String |
Must be Project |
id |
String? |
ID of the project. If not provided, Tyme will generate a unique ID |
name |
String |
Name of the project |
color |
Int? |
i.e 0xFF9900 |
category_id |
String? |
ID of the parent category |
rounding_method |
Int |
DOWN, NEAREST or UP |
rounding_minutes |
Int |
Minutes the rounding is applied |
hourly_rate |
Int |
Hourly Rate |
planned_duration |
Int |
Duration in seconds |
planned_budget |
Float |
Budget |
Task
Parameter |
Type |
Description |
type |
String |
Must be TimedTask |
id |
String? |
ID of the task. If not provided, Tyme will generate a unique ID |
name |
String |
Name of the task |
project_id |
String? |
ID of the parent project |
billable |
Bool |
Whether the task is billable or not |
planned_duration |
Int |
Duration in seconds |
Sub-Task
Parameter |
Type |
Description |
type |
String |
Must be TimedSubTask |
id |
String? |
ID of the sub-task. If not provided, Tyme will generate a unique ID |
name |
String |
Name of the sub-task |
task_id |
String? |
ID of the parent task |
planned_duration |
Int |
Duration in seconds |
Time Entry
Parameter |
Type |
Description |
type |
String |
Must be TimedTaskRecord |
id |
String? |
ID of the time entry. If not provided, Tyme will generate a unique ID |
task_id |
String? |
ID of the parent task |
time_start |
DateTime |
Start time |
time_end |
DateTime? |
End time. Set to null if the time entry is still running |
note |
String |
Note of the time entry |
user_id |
String? |
User ID the entry belongs to |
Absence
Parameter |
Type |
Description |
type |
String |
Must be NonWorkingRecord |
subtype |
Int |
vacation=0, sick=1, other=2, publicHoliday=3, overtimeCompensation=4, specialLeave=5 |
id |
String? |
ID of the entry. If not provided, Tyme will generate a unique ID |
time_start |
DateTime |
Start time |
time_end |
DateTime? |
End time |
note |
String |
Note |
user_id |
String? |
User ID the entry belongs to |
Response
Status Code |
Parameter |
Value |
200 |
status |
success |
403 |
error |
not_allowed |
400 |
error |
missing values |
Deleting
DELETE /data/entity
Parameter |
Type |
Description |
project_ids |
Array |
Array of entity ids (can be a project, task, sub-task, etc.) |
time_ids |
Array |
Array of time entry ids |
Response
Status Code |
Parameter |
Value |
200 |
status |
success |
403 |
error |
not_allowed |
Task Summary
GET /data/summary
Parameter |
Type |
Description |
from |
DateTime |
Start of the time frame |
to |
DateTime |
End of the time frame |
Response
Status Code |
Parameter |
Value |
200 |
summary |
summary data |
403 |
error |
not_allowed |
400 |
error |
date_range_too_large |
Get Team Members
GET /data/members/:user_id
Parameter |
Type |
Description |
user_id |
String? |
Use me for yourself. Omit for all users |
Response
Status Code |
Parameter |
Value |
200 |
data |
user data |
403 |
error |
not_allowed |
400 |
error |
missing values |
Get Times
GET /data/times
Parameter |
Type |
Description |
from |
DateTime |
Start of the time frame |
to |
DateTime |
End of the time frame |
start |
Int? |
Paging start parameter |
Response
Status Code |
Parameter |
Value |
200 |
data |
times data |
403 |
error |
not_allowed |
400 |
error |
missing values |
Times Response Data
Parameter |
Value |
data |
array of time entries |
start |
current paging start parameter |
limit |
max number of results returned |
total |
total number of results |