Use the Clockwork API

The Clockwork API allows you to programmatically interacting with Clockwork data. 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.

 

BETA ACCESS

Clockwork API functionality is under development and is subject to change.

Currently API access is available freely to all Clockwork customers. In the future, some functions may only be available in Clockwork Pro.

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
1 2 curl https://api.clockwork.report/v1/worklogs \ --header "Authorization: Token LqUOWaETaP3wEf7D...rest of the token...RqWw=="
JAVASCRIPT
1 2 3 4 5 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
1 https://api.clockwork.report/v1/worklogs?expand=issues,authors,emails

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.

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 item are: issues, authors and emails.

EXAMPLE CURL
1 2 3 4 5 6 7 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>'
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 issue id.

  • 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.

EXAMPLE RESPONSE
1 2 3 4 5 6 7 8 9 10 11 12 13 [ { "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
Required
issue_id
integer
issue_key
string

Specify the issue you want to start a timer on. If both are provided, issue_id takes precedence over issue_key.

EXAMPLE CURL
1 2 3 4 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
1 2 3 4 5 6 7 8 9 10 11 12 { "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
Required
issue_id
integer
issue_key
string

Specify the issue you want to stop the timer on. If both are provided, issue_id takes precedence over issue_key.

EXAMPLE CURL
1 2 3 4 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
1 2 3 4 5 6 7 8 9 10 11 12 { "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" } } ] }