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

Request query parameters

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"
      }
    }
  ]
}