Timers

Freckle is now Noko! Learn how to migrate your apps here

List all currently running or paused timers
Get a project’s timer
Edit a project’s timer
Start a project’s timer
Pause a project’s timer
Add or subtract time to a project’s timer
Log the time in a project’s timer
Log the time in a project’s timer as an Inbox Entry
Discard a project’s timer

List all currently running or paused timers

Get all the currently running or paused timers. The running timer will be shown first, then the paused timers. Only timers for the current user are returned.

GET /v2/timers

# cURL
$ curl -H "X-NokoToken:scbp72wdc528hm8n52fowkma321tn58-jc1l2dkil0pnb75xjni48ad2wwsgr1d" https://api.nokotime.com/v2/timers

Parameters

Each parameter passed will filter the results, and parameters are chained (meaning that if you search by description and projects, it will only return the timers with that description text for those projects).

description: Optional string; Only timers containing this text in their description are returned.; Example: description=meeting
projects: Optional string; A comma-separated list of project IDs to filter by.; Example: projects=4,5,6
billable: Optional boolean; true: only show timers for billable projects; false: only show timers for unbillable projects

Response

Status: 200 OK
Link: <https://api.nokotime.com/v2/timers?page=2>; rel="next",
 <https://api.nokotime.com/v2/timers?page=5>; rel="last"

[
  {
    "id": 123456,
    "state": "running",
    "seconds": 180,
    "formatted_time": "00:03:00",
    "date": "2013-07-09",
    "description": "noko work",
    "user": {
      "id": 5538,
      "email": "john.test@test.com",
      "first_name": "John",
      "last_name": "Test",
      "profile_image_url": "https://api.nokotime.com/images/avatars/0000/0001/avatar.jpg",
      "url": "https://api.nokotime.com/v2/users/5538"
    },
    "project": {
      "id": 37396,
      "name": "Gear GmbH",
      "billing_increment": 10,
      "enabled": true,
      "billable": true,
      "color": "#ff9898",
      "url": "https://api.nokotime.com/v2/projects/37396"
    },
    "url": "https://api.nokotime.com/v2/projects/37396/timer",
    "start_url": "https://api.nokotime.com/v2/projects/37396/timer/start",
    "pause_url": "https://api.nokotime.com/v2/projects/37396/timer/pause",
    "add_or_subtract_time_url": "https://api.nokotime.com/v2/projects/37396/timer/add_or_subtract_time",
    "log_url": "https://api.nokotime.com/v2/projects/37396/timer/log"
  }
]

Get a project’s timer

GET /v2/projects/:project_id/timer

# cURL
$ curl -H "X-NokoToken:scbp72wdc528hm8n52fowkma321tn58-jc1l2dkil0pnb75xjni48ad2wwsgr1d" https://api.nokotime.com/v2/projects/:project_id/timer

Status: 200 OK

{
  "id": 123456,
  "state": "running",
  "seconds": 180,
  "formatted_time": "00:03:00",
  "date": "2013-07-09",
  "description": "noko work",
  "user": {
    "id": 5538,
    "email": "john.test@test.com",
    "first_name": "John",
    "last_name": "Test",
    "profile_image_url": "https://api.nokotime.com/images/avatars/0000/0001/avatar.jpg",
    "url": "https://api.nokotime.com/v2/users/5538"
  },
  "project": {
    "id": 37396,
    "name": "Gear GmbH",
    "billing_increment": 10,
    "enabled": true,
    "billable": true,
    "color": "#ff9898",
    "url": "https://api.nokotime.com/v2/projects/37396"
  },
  "url": "https://api.nokotime.com/v2/projects/37396/timer",
  "start_url": "https://api.nokotime.com/v2/projects/37396/timer/start",
  "pause_url": "https://api.nokotime.com/v2/projects/37396/timer/pause",
  "add_or_subtract_time_url": "https://api.nokotime.com/v2/projects/37396/timer/add_or_subtract_time",
  "log_url": "https://api.nokotime.com/v2/projects/37396/timer/log"
}

Notes

If a project does not have a currently running or paused timer, then the response will return a 404 status code.

Status: 404 Not Found

Timers can have the following state:

pending (no time has elapsed)
running
paused
stopped

Edit a project’s timer

Updates the details for a project’s timer. If the timer does not exist, it will automatically be created.

PUT /v2/projects/:project_id/timer

# cURL
$ curl -X PUT -H "X-NokoToken:scbp72wdc528hm8n52fowkma321tn58-jc1l2dkil0pnb75xjni48ad2wwsgr1d" https://api.nokotime.com/v2/projects/:project_id/timer

Status: 200 OK

{
  "id": 123456,
  "state": "running",
  "seconds": 180,
  "formatted_time": "00:03:00",
  "date": "2013-07-09",
  "description": "noko work",
  "user": {
    "id": 5538,
    "email": "john.test@test.com",
    "first_name": "John",
    "last_name": "Test",
    "profile_image_url": "https://api.nokotime.com/images/avatars/0000/0001/avatar.jpg",
    "url": "https://api.nokotime.com/v2/users/5538"
  },
  "project": {
    "id": 37396,
    "name": "Gear GmbH",
    "billing_increment": 10,
    "enabled": true,
    "billable": true,
    "color": "#ff9898",
    "url": "https://api.nokotime.com/v2/projects/37396"
  },
  "url": "https://api.nokotime.com/v2/projects/37396/timer",
  "start_url": "https://api.nokotime.com/v2/projects/37396/timer/start",
  "pause_url": "https://api.nokotime.com/v2/projects/37396/timer/pause",
  "add_or_subtract_time_url": "https://api.nokotime.com/v2/projects/37396/timer/add_or_subtract_time",
  "log_url": "https://api.nokotime.com/v2/projects/37396/timer/log"
}

Input

description: Optional string; The description that will be used when the timer is logged. Any tags or hashtags will be automatically parsed.

Start a project’s timer

PUT /v2/projects/:project_id/timer/start

# cURL
$ curl -X PUT -H "X-NokoToken:scbp72wdc528hm8n52fowkma321tn58-jc1l2dkil0pnb75xjni48ad2wwsgr1d" https://api.nokotime.com/v2/projects/:project_id/timer/start

Status: 200 OK
Location: https://api.nokotime.com/v2/projects/1/timer

{
  "id": 123456,
  "state": "running",
  "seconds": 180,
  "formatted_time": "00:03:00",
  "date": "2013-07-09",
  "description": "noko work",
  "user": {
    "id": 5538,
    "email": "john.test@test.com",
    "first_name": "John",
    "last_name": "Test",
    "profile_image_url": "https://api.nokotime.com/images/avatars/0000/0001/avatar.jpg",
    "url": "https://api.nokotime.com/v2/users/5538"
  },
  "project": {
    "id": 37396,
    "name": "Gear GmbH",
    "billing_increment": 10,
    "enabled": true,
    "billable": true,
    "color": "#ff9898",
    "url": "https://api.nokotime.com/v2/projects/37396"
  },
  "url": "https://api.nokotime.com/v2/projects/37396/timer",
  "start_url": "https://api.nokotime.com/v2/projects/37396/timer/start",
  "pause_url": "https://api.nokotime.com/v2/projects/37396/timer/pause",
  "add_or_subtract_time_url": "https://api.nokotime.com/v2/projects/37396/timer/add_or_subtract_time",
  "log_url": "https://api.nokotime.com/v2/projects/37396/timer/log"
}

Input

entry_date: Optional string of a date in ISO 8061 format YYYY-MM-DD; If no value is provided, the current date will be used.
description: Optional string; The description that will be used when the timer is logged. Any tags or hashtags will be automatically parsed.

Notes

When a timer is started, the currently running timer (if any) is paused.
Once a timer has been started, its entry date cannot be changed with the start action, even if it is paused or stopped. However, you can change the entry date for the timer when the timer is logged.

Pause a project’s timer

The response does not change if the timer has already been paused or does not exist

PUT /v2/projects/:project_id/timer/pause

# cURL
$ curl -X PUT -H "X-NokoToken:scbp72wdc528hm8n52fowkma321tn58-jc1l2dkil0pnb75xjni48ad2wwsgr1d" https://api.nokotime.com/v2/projects/:project_id/timer/pause

Status: 200 OK

{
  "id": 123456,
  "state": "running",
  "seconds": 180,
  "formatted_time": "00:03:00",
  "date": "2013-07-09",
  "description": "noko work",
  "user": {
    "id": 5538,
    "email": "john.test@test.com",
    "first_name": "John",
    "last_name": "Test",
    "profile_image_url": "https://api.nokotime.com/images/avatars/0000/0001/avatar.jpg",
    "url": "https://api.nokotime.com/v2/users/5538"
  },
  "project": {
    "id": 37396,
    "name": "Gear GmbH",
    "billing_increment": 10,
    "enabled": true,
    "billable": true,
    "color": "#ff9898",
    "url": "https://api.nokotime.com/v2/projects/37396"
  },
  "url": "https://api.nokotime.com/v2/projects/37396/timer",
  "start_url": "https://api.nokotime.com/v2/projects/37396/timer/start",
  "pause_url": "https://api.nokotime.com/v2/projects/37396/timer/pause",
  "add_or_subtract_time_url": "https://api.nokotime.com/v2/projects/37396/timer/add_or_subtract_time",
  "log_url": "https://api.nokotime.com/v2/projects/37396/timer/log"
}

Notes

If a project does not have a currently running or paused timer, then the response will return a 404 status code.

Status: 404 Not Found

Add or subtract time to a project’s timer

The response does not change if the timer has already been paused or does not exist

PUT /v2/projects/:project_id/timer/add_or_subtract_time

# cURL
$ curl -X PUT -H "X-NokoToken:scbp72wdc528hm8n52fowkma321tn58-jc1l2dkil0pnb75xjni48ad2wwsgr1d" https://api.nokotime.com/v2/projects/:project_id/timer/add_or_subtract_time

Status: 200 OK

{
  "id": 123456,
  "state": "running",
  "seconds": 180,
  "formatted_time": "00:03:00",
  "date": "2013-07-09",
  "description": "noko work",
  "user": {
    "id": 5538,
    "email": "john.test@test.com",
    "first_name": "John",
    "last_name": "Test",
    "profile_image_url": "https://api.nokotime.com/images/avatars/0000/0001/avatar.jpg",
    "url": "https://api.nokotime.com/v2/users/5538"
  },
  "project": {
    "id": 37396,
    "name": "Gear GmbH",
    "billing_increment": 10,
    "enabled": true,
    "billable": true,
    "color": "#ff9898",
    "url": "https://api.nokotime.com/v2/projects/37396"
  },
  "url": "https://api.nokotime.com/v2/projects/37396/timer",
  "start_url": "https://api.nokotime.com/v2/projects/37396/timer/start",
  "pause_url": "https://api.nokotime.com/v2/projects/37396/timer/pause",
  "add_or_subtract_time_url": "https://api.nokotime.com/v2/projects/37396/timer/add_or_subtract_time",
  "log_url": "https://api.nokotime.com/v2/projects/37396/timer/log"
}

Input

minutes: Optional integer; The number of minutes to add or subtract to the timer. This number can be positive to add minutes, and negative to subtract minutes.
seconds: Optional integer; The number of seconds to add or subtract to the timer. This number can be positive to add seconds, and negative to subtract seconds.

Notes

Using both the minutes and seconds fields allows you to precisely update a timer. For example, you can add 1:30 to a timer with:
- ```
{
"minutes": 1,
"seconds": 30
}
```
If a project does not have a currently running or paused timer, then the response will return a 404 status code.
- ```
Status: 404 Not Found
```

Log the time in a project’s timer

When a timer is logged, a new entry is created for the user with the description provided.

PUT /v2/projects/:project_id/timer/log

# cURL
$ curl -X PUT -H "X-NokoToken:scbp72wdc528hm8n52fowkma321tn58-jc1l2dkil0pnb75xjni48ad2wwsgr1d" https://api.nokotime.com/v2/projects/:project_id/timer/log

Status: 204 No Content

Input

entry_date: Optional string of a date in ISO 8061 format YYYY-MM-DD; The date that will be used when creating an entry based on this timer. If no value is provided, then the entry_date provided when the timer was started will be used.
minutes: Optional integer; The number of minutes logged in the time entry. This number will automatically be rounded up based on the project’s “billing_increment” settings. If no value is provided, then the timer’s elapsed minutes will be used.
description.: Optional string; The description that will be used when the timer is logged. Any tags or hashtags will be automatically parsed.

Notes

If a project does not have a currently running or paused timer, then the response will return a 404 status code.

Status: 404 Not Found

Custom Error Codes

cannot_create_tags: The authenticated user is unable to create new tags

Log the time in a project’s timer as an Inbox Entry

Not implemented yet!

This is just a sneak peek into how this endpoint might work. Attempting to call it will return a 404 error.

Inbox Entries are pending entries that are placed on the authenticated user’s dashboard, so that they can be manually reviewed before they are logged. You can learn more about Entries vs. Inbox Entries here

PUT /v2/projects/:project_id/timer/log_inbox_entry

Input

inbox_entry_date: Optional string of a date in ISO 8061 format YYYY-MM-DD; The date that will be used when creating an inbox entry based on this timer. If no value is provided, then the entry_date provided when the timer was started will be used.
description: Optional string; The description of the inbox entry. If no value is provided, then the timer’s description will be used.
minutes: Optional integer; The number of minutes logged in this inbox entry. If no value is provided, then the timer’s elapsed minutes will be used.

{
  "inbox_entry_date": "2013-07-09",
  "description": "noko work",
  "minutes": 3
}

Reponse

Status: 204 No Content

Notes

If a project does not have a currently running or paused timer, then the response will return a 404 status code.

Discard a project’s timer

When a project’s timer is discarded, the timer is deleted and no time entry is recorded.

DELETE /v2/projects/:project_id/timer

# cURL
$ curl -X DELETE -H "X-NokoToken:scbp72wdc528hm8n52fowkma321tn58-jc1l2dkil0pnb75xjni48ad2wwsgr1d" https://api.nokotime.com/v2/projects/:project_id/timer

Response

Status: 204 No Content

Topics

Resources

Webhooks

Broadcasts

Account Management

Timers

List all currently running or paused timers

Parameters

Response

Get a project’s timer

Notes

Edit a project’s timer

Input

Start a project’s timer

Input

Notes

Pause a project’s timer

Notes

Add or subtract time to a project’s timer

Input

Notes

Log the time in a project’s timer

Input

Notes

Custom Error Codes

Log the time in a project’s timer as an Inbox Entry

Not implemented yet!

Input

Reponse

Notes

Discard a project’s timer

Response

About Noko

Us & our company

Docs

You & your account