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
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 theissueId
.The
expand=authors
to expand the response with author details like Display Name. Otherwise you will receive only theaccountId
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.
Request query parameters
starting_at | The lower bound of the returned worklogs in the format of YYYY-MM-DD. |
ending_at | The upper bound of the returned worklogs in the format of YYYY-MM-DD. |
project_ids[] | Narrow down the returned worklogs to selected projects only. If both are provided, |
account_id | Narrow down the returned worklogs to the selected authors only.
|
expand | Comma-separated list of response parts to include. Currently supported expand item are: |
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
REQUIRED | Specify the issue you want to start a timer on. If both are provided, |
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
REQUIRED | Specify the issue you want to stop the timer on. If both are provided, |
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"
}
}
]
}