The Custom Calendars API allows you to programmatically read and manage the business calendars configured in Timepiece. Calendars are central to how Timepiece measures time, when a custom calendar is applied to a report, durations are calculated in business hours rather than continuous 24/7 time, respecting your defined working days, working hours, shifts, and holidays.
This API group covers five endpoints split across two purposes: reading calendar data for use in reports, and administering calendar definitions.
Reading Calendars
List All Calendars
GET /rest/calendar
Returns a flat list of all calendars defined on the instance. Each entry includes the full calendar definition, working times per weekday, daily working hours, timezone, and holiday list. This is the quickest way to retrieve all calendar IDs when building report requests that require a calendar parameter.
See Calendars for the full reference and example response.
Search Calendar
GET /rest/calendar/search
Returns a paginated list of calendars matching a search query. You can search by calendar name using either an exact match (searchType=exact) or a partial match (searchType=contain). Useful when you know part of a calendar name and want to find its ID without fetching the entire list. All users with Timepiece access can call this endpoint.
See Search Calendar for the full parameter reference and example requests.
Get Calendar By ID
GET /rest/calendar/{calendarId}
Returns the complete definition of a single calendar identified by its numeric ID. The response includes the calendar name, timezone, working time windows per weekday (as millisecond offsets from midnight), daily working hours, and the list of configured holidays with their names, dates, and recurrence settings.
See Get Calendar By ID for the full reference and example response.
Administering Calendars
Both write endpoints are admin-only and require a Jira Admin tisjwt token. The request body is a JSON object containing the calendar name, timeZone , an array of workingTimes, and an optional array of holidays. The response for both endpoints returns the full calendar object as saved, including the system-assigned id.
Create Calendar
POST /rest/calendar
Creates a new custom business calendar. The calendar becomes immediately available for selection in Timepiece reports and in the Calendar Settings admin page.
See Create Calendar for the full request body reference and example.
Update Calendar
PUT /rest/calendar/{calendarId}
Replaces the definition of an existing calendar identified by its numeric ID with the values provided in the request body.
See Update Calendar for the full request body reference and example.