Tracker API
Which requests of the widely used tracker’s REST API Kaiku answers, and where it behaves differently.
What it is
Kaiku answers the REST API of the self-hosted edition of the most widely used corporate tracker: the same paths, request bodies, response shapes, status codes and error format. A tool written for it is pointed at your workspace address with a token, and works.
We are not affiliated with that vendor, and compatibility is something we work at rather than a guarantee for every tool. If a tool you rely on does not behave, tell us — that is a bug to us.
GET /rest/api/2/serverInfo answers without signing in and reports a Server deployment. Tools use it to decide how to talk, and it is a quick way to check the address is right.
What is answered
Everything below is under /rest/api/2 unless it says otherwise.
| Area | Requests |
|---|---|
| You and the server | myself, serverInfo, configuration, field, mypermissions |
| Projects | project, project/search, project/{key} with /statuses, /versions, /components; creating, changing and deleting a project |
| Issues | issue — create, read, edit, delete; issue/{key}/assignee; issue/createmeta, issue/{key}/editmeta |
| Workflow | issue/{key}/transitions — list and perform |
| Comments | issue/{key}/comment — list, add, edit, delete |
| Work log | issue/{key}/worklog — list and add |
| Attachments | issue/{key}/attachments to upload; attachment/{id} to read and delete; /secure/attachment/{id}/{filename} to download |
| Links and watchers | issueLink, issueLinkType, issue/{key}/remotelink, issue/{key}/watchers |
| Search | search and search/jql, by GET and POST, under both /rest/api/2 and /rest/api/3 — see Search (JQL) |
| Reference data | issuetype, status, statuscategory, priority, resolution |
| People | user, user/search, user/assignable/search, user/assignable/multiProjectSearch, users/search |
| Boards and sprints | Under /rest/agile/1.0: board with its configuration, sprint, issue, backlog, epic; creating, starting, completing and deleting a sprint; moving issues into a sprint and back to the backlog |
Where it differs
- `/rest/api/3` is mostly absent. Only
myself,search,search/jqlandremotelinkanswer there. Use/rest/api/2— tools written for the self-hosted edition already do. - Rich text is a string. Descriptions and comments are plain text, Markdown or the tracker’s wiki markup, sent and returned as strings. A description sent as a document object (the cloud edition’s format) is not read.
- Not there at all: saved filters, dashboards, groups, bulk issue creation, and change history (
expand=changelog). - Versions and components are listed as empty and cannot be created.
- A project or issue you may not see is a 404, not a 403.
- Archived issues are left out of search unless the query mentions
archived. - Story points are
customfield_10016and the sprint iscustomfield_10020, as the tracker’s tools expect. Columns a project adds itself arecustomfield_2xxxx;GET fieldlists them.
Paging, errors and caching
- Search pages with
startAtandmaxResultsand returnstotal(all matches) andisLast.maxResultsis 50 by default and at most 1000. - Errors have the tracker’s shape:
{"errorMessages": […], "errors": {…}}. They are in English unless the request sendsAccept-Language. - Every JSON answer to a GET carries an
ETag; send it back asIf-None-Matchand an unchanged answer is a bodiless 304. - One attachment may be up to 100 MB. A description or a comment may be up to 100 KB of text; longer is refused with a 400, never cut.
- Labels may not contain spaces.
Something missing, or not as described here? Write to hello@kaiku.tech