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: 2024-12-31 23:59:59

Authentication

Tyme uses the OAuth v2 standard for authenticating users. To make yourself familiar with OAuth, please take a look at the introduction at oauth.net.

Auth Endpoint

Login form to log the user in and redirect them to your app

GET /v1/authorize

Parameters:

{
  "response_type": "code",
  "client_id": "YOUR_CLIENT_ID",
  "state": "YOUR_STATE",
  "redirect_uri": "YOUR_REDIRECT_URI"
}

Access Token Endpoint

Exchange the authcode with an access & refresh token

POST /v1/access_token

Parameters:

{
  "grant_type": "authorization_code",
  "code": "YOUR_AUTH_CODE",
  "redirect_uri": "YOUR_REDIRECT_URI",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

Refresh Token Endpoint

Exchange the refresh token with a new access token

POST /v1/refresh_token

Parameters:

{
  "grant_type": "refresh_token",
  "refresh_token": "THE_REFRESH_TOKEN",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

Features

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

GET /webhooks/subscribe/

Parameters:

{
  "hookUrl": "String",
  "trigger_type": "category|project|task|subtask|time|stopped_time"
}

Unsubscribing from a webhook

POST /webhooks/unsubscribe/

Parameters:

{
  "hookUrl": "String",
  "trigger_type": "category|project|task|subtask|time|stopped_time"
}

Searching for entities

GET /data/search_entity/

Parameters:

{
  "type": "ProjectCategory|Project|TimedTask|TimedSubTask",
  // the name to search for
  "name": "String",
  // optional. ID of the parent entity. For example a project id when searching for a task
  "parent_id": "null|String"
}

Inserting new entities

POST /data/update_entity/

Create or Update a Category:

{
  "type": "ProjectCategory",
  // optional. if not provided, Tyme will genereate a unique ID.
  "id": "String",
  "name": "String"
}

Create or Update a Project:

{
  "type": "Project",
  // optional. if not provided, Tyme will genereate a unique ID.
  "id": "String",
  "name": "String",
  // optional. ID of the connected category
  "category_id": "String|null",
  "rounding_method": "DOWN|NEAREST|UP",
  "rounding_minutes": "Int",
  "hourly_rate": "Float",
  // planned duration in hours (i.e. 120.5)
  "planned_duration_hours": "Float",
  "planned_budget": "Float"
}

Create or Update a Task:

{
  "type": "TimedTask",
  // optional. if not provided, Tyme will genereate a unique ID.
  "id": "String",
  "name": "String",
  // ID of the connected project
  "project_id": "String",
  "billable": "Bool",
  "planned_duration": "Int" // duration in seconds
}

Create or Update a Sub-Task:

{
  "type": "TimedSubTask",
  // optional. if not provided, Tyme will genereate a unique ID.
  "id": "String",
  "name": "String",
  // ID of the connected task
  "task_id": "String",
  "planned_duration": "Int" // duration in seconds
}

Create or Update a Time Entry:

{
  "type": "TimedTaskRecord",
  // optional. if not provided, Tyme will genereate a unique ID.
  "id": "String",
  // ID of the connected task or empty if a child of a sub-task
  "task_id": "String",
  // ID of the connected sub-task if or empty is not a child of a sub-task
  "subtask_id": "String",
  "time_start": "DateTime",
  // null if the time entry is still running
  "time_end": "DateTime|null",
  "note": "String"
}

Summaries

GET /data/summary/

Task Summary:

{
  "from": "DateTime", // i.e. 2000-01-01 00:00:00
  "to": "DateTime" 
}