Use the Clockwork API

The Clockwork API allows you to interact with Clockwork data programmatically. For example, you could write automation to retrieve a list of worklogs at the end of every month and pass it into your invoicing service.

At the beginning of July, the Clockwork API will become available only in Clockwork Pro. You can move to the Pro version or use the native Jira API to get your worklogs.

API Token

Authorization for the Clockwork API is based on Clockwork API tokens. All requests to the Clockwork API are executed in the context of the token owner. Every Jira user with Clockwork Timesheets Access can create a token. To create a token, select Apps > Clockwork from the main menu. Click on API tokens on the left nav bar. Click the Create token button.

Authentication

Authentication is done via a standard “Authorization” HTTP header. You need to pass your token with each request sent to the Clockwork API:

CURL

curl https://api.clockwork.report/v1/worklogs \ 
  --header "Authorization: Token LqUOWaETaP3wEf7D...rest of the token...RqWw=="

JAVASCRIPT

response = await fetch("https://api.clockwork.report/v1/worklogs", {
  headers: {
    'Authorization': "Token LqUOWaETaP3wEf7D...rest of the token...RqWw=="
  }
})

Output Format

Unless stated otherwise, the output format of endpoint(s) data is JSON.

Expansion

To minimize processing time and network traffic, some parts of response are not returned unless specifically requested. To request that items be included in the response, use the expand query parameter and specify objects to include. You can provide multiple objects in a comma-separated list.

EXAMPLE

https://api.clockwork.report/v1/worklogs?expand=issues,authors,emails,worklogs

Response

Contains an array of worklogs for the specified scope. You can use:

• The expand=issues query parameter to expand the response with issue details like Summary or Custom Fields. Otherwise you will receive only the issueId.

• The expand=authors to expand the response with author details like Display Name. Otherwise you will receive only the accountId of the user.

• The expand=emails to expand response to include the worklog author’s email address.

• The expand=worklogs query parameter will fetch issue ID, worklog ID, time spent, and worklog attributes such as tags and billable hours.

API endpoints

All endpoints are currently hosted under https://api.clockwork.report/v1. Add that prefix to each of the endpoints below.

Worklogs GET /worklogs

This endpoint retrieves the list of worklogs, and can be scoped with query parameters to narrow the response. Our API limits request to 10000 work logs and have an offset parameter. If you need more worklogs per query, you’ll need to make multiple requests.

Request query parameters

starting_at date	The lower bound of the returned worklogs in the format of YYYY-MM-DD.
ending_at date	The upper bound of the returned worklogs in the format of YYYY-MM-DD.
project_ids[] integer project_keys[] string	Narrow down the returned worklogs to selected projects only. If both are provided,project_ids takes precedence over project_keys. Multiple values are allowed, i.e. project_keys[]=SSP&project_keys[]=SSPA
account_id string user_query string user_query[] string	Narrow down the returned worklogs to the selected authors only. account_id takes precedence over user_query . user_query allows you to provide any kind of term that will be matched against possible authors. You can use it to provide a list of emailAddresses to query against, i.e: user_query[]=alice@company.com&user_query[]=bob@company.com
expand string	Comma-separated list of response parts to include. Currently supported expand items are: worklogs,issues, authors and emails. Adding the expand=worklogs request parameter returns worklog properties, including worklog attributes. This part of the response looks like this: CODE "properties": [ { "key": "clockwork", "value": { "ignore_time_logged_validator_processing": true, "attributes": [ { "key": "lsu5rn3s" }, { "key": "lsu5tfek", "value": true }, { "key": "lusfr0zh" } ], "tracking_mode": "manual" } } ] The attributes can be identified by navigating to Apps>Clockwork, then Settings>Worklogs and opening the Edit worklog attribute dialog. The key is displayed at the bottom of the dialog, like this:
offset number	There is a limit of 10000 worklogs per request. You must make multiple requests to retrieve more than 10000 worklogs. Use the offset parameter to designate where the first worklog to be retrieved: CODE curl 'https://api.clockwork.report/v1/worklogs?offset=0' curl 'https://api.clockwork.report/v1/worklogs?offset=10000' curl 'https://api.clockwork.report/v1/worklogs?offset=20000' curl 'https://api.clockwork.report/v1/worklogs?offset=30000' curl 'https://api.clockwork.report/v1/worklogs?offset=40000' If fewer than 10000 worklogs are returned, then there are fewer than 10000 worklogs (or remaining) that meet the query, and no further requests are required.
tz string	Set up a specific time zone in which your worklogs started time would display: CODE https://api.clockwork.report/v1/worklogs?tz=Europe/Warsaw Answer example: CODE [ { "id": "10294", "timeSpentSeconds": 3600, "started": "2023-04-03T02:15:00+02:00", "author": { "accountId": "62c29c19a152cf973643dba5" }, "issueId": "17843" }, As you can see, the timezone is set - "started": "2023-04-03T02:15:00+02:00", You should be able to use namings from Clockwork Timesheet:

EXAMPLE CURL

curl 'https://api.clockwork.report/v1/worklogs' \
  --get \
  --data starting_at=2021-03-01 \
  --data ending_at=2021-03-31 \
  --data project_keys%5B%5D=SSP \
  --data account_id=5ba374cab1a6ab2f054f17b1 \
  --header 'Authorization: Token <TOKEN_HERE>'

EXAMPLE RESPONSE

[
  {
    "author": {
      "accountId": "5ba374cab1a6ab2f054f17b1"
    },
    "id": "10685",
    "issue": {
      "id": "10118"
    },
    "started": "2021-02-08T14:23:35Z",
    "timeSpentSeconds": 2700
  }
]

Start timer POST /start_timer

This endpoint starts your timer for a given issue.

Request query parameters

EXAMPLE CURL

curl 'https://api.clockwork.report/v1/start_timer' \
  --request POST \
  --data issue_key=SSP-13 \
  --header 'Authorization: Token <TOKEN_HERE>'

Response

Contains an array of UI messages generated during that action.

EXAMPLE RESPONSE

{
  "messages": [
    {
      "title": "Clockwork timer started",
      "body": "Counting working time on SPP-13 for Piotr Stefaniak",
      "type": "info",
      "actions": {
        "clockwork.action.navigate.issue-key.SPP-13": "View SPP-13"
      }
    }
  ]
}

Stop timer POST /stop_timer

This endpoint stops a running timer for a given issue.

Request query parameters

EXAMPLE CURL

curl 'https://api.clockwork.report/v1/stop_timer' \
  --request POST \
  --data issue_key=SSP-13 \
  --header 'Authorization: Token <TOKEN_HERE>'

Response

Contains an array of UI messages generated during that action.

EXAMPLE RESPONSE

{
  "messages": [
    {
      "title": "Clockwork timer stopped",
      "body": "Will report 5m on behalf of Piotr Stefaniak",
      "type": "success",
      "actions": {
        "clockwork.action.navigate.issue-key.SPP-13": "View STT-2"
      }
    }
  ]
}