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. |
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 is done via a standard “Authorization” HTTP header. You need to pass your token with each request sent to the Clockwork API:
curl https://api.clockwork.report/v1/worklogs \ --header "Authorization: Token LqUOWaETaP3wEf7D...rest of the token...RqWw==" |
response = await fetch("https://api.clockwork.report/v1/worklogs", { headers: { 'Authorization': "Token LqUOWaETaP3wEf7D...rest of the token...RqWw==" } }) |
Unless stated otherwise, the output format of endpoint(s) data is JSON.
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.
https://api.clockwork.report/v1/worklogs?expand=issues,authors,emails,worklogs |
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.
All endpoints are currently hosted under https://api.clockwork.report/v1
. Add that prefix to each of the endpoints below.
GET /worklogs
This endpoint retrieves the list of worklogs, and can be scoped with query parameters to narrow the response.
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: |
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>' |
[ { "author": { "accountId": "5ba374cab1a6ab2f054f17b1" }, "id": "10685", "issue": { "id": "10118" }, "started": "2021-02-08T14:23:35Z", "timeSpentSeconds": 2700 } ] |
POST /start_timer
This endpoint starts your timer for a given issue.
| Specify the issue you want to start a timer on. If both are provided, |
curl 'https://api.clockwork.report/v1/start_timer' \ --request POST \ --data issue_key=SSP-13 \ --header 'Authorization: Token <TOKEN_HERE>' |
Contains an array of UI messages generated during that action.
{ "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" } } ] } |
POST /stop_timer
This endpoint stops a running timer for a given issue.
| Specify the issue you want to stop the timer on. If both are provided, |
curl 'https://api.clockwork.report/v1/stop_timer' \ --request POST \ --data issue_key=SSP-13 \ --header 'Authorization: Token <TOKEN_HERE>' |
Contains an array of UI messages generated during that action.
{ "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" } } ] } |