View Source

You can use this REST API to develop integrations between Company Calendar for Jira and other applications or systems. This page documents the available REST resources along with expected HTTP responses and sample requests.

To use REST API, an admin has to generate a token tied either to specific calendars or all calendars. It’s recommended to assign minimum calendars per token and to create "All Calendars" tokens only when it’s needed.

Company Calendar for Jira Documentation > REST API > image-20230214-105039.png

Introduced in the app version 8.1, users are able to create, edit and delete calendars and custom event sources via REST API. The editing and deletion of calendars and sources can be managed on the token level.

Please note that it is important to use a token based on the “All” calendars options should you wish to add new calendars via REST API.

URL Structure

To use REST API, your application will make an HTTP request and parse the response.

Since the Cloud version of the app is hosted in the Cloud, while the Server and Data Center versions reside on the same server as Jira, there are different URLs for REST API.

For Jira Cloud REST API URIs start with:

https://ccj.brizoit.com/ccj/rest/brizo-calendar

For Jira Server REST API URIs start with your Jira URL followed by /rest/brizo-calendar

JIRA-SERVER-URL/rest/brizo-calendar

Jira URL can be copied from the browser or checked in Administration -> System -> General configuration, Base URL setting:

Company Calendar for Jira Documentation > REST API > image-20230214-115745.png

Authentication

Requests to the REST points should be authenticated by Bearer authentication (also known as token authentication). To do so, the clients must send the token in the Authorization header when making requests:

Authorization: Bearer <token>

When no token or wrong token is passed all REST resources return 401 error code.

GET /api/1/calendar

Returns the list of calendars tied for the passed token.

Successful response brings JSON with calendars associated with the passed token:

Company Calendar for Jira Documentation > REST API > image-20230214-121733.png

See the response sample:

[
    {
        "id": 1959,
        "sources": [
            {
                "id": 5655,
                "calendarId": 1959,
                "emailsEnabled": false,
                "eventType": {
                    "issueRequired": false,
                    "key": "meeting",
                    "name": "Meetings",
                    "projectRequired": false,
                    "systemType": true,
                    "usersRequired": true
                },
                "order": 1,
                "value": "{\"color\":\"#7500ca\",\"projectId\":-1,\"condColors\":[],\"name\":\"Dekki's meetings\",\"concurrence\":\"allow\",\"hideStartTime\":false,\"issueFields\":[{\"id\":\"issuekey\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.project\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"event.summary\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.users\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.reporter\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.description\",\"showEvent\":true,\"showInfo\":true}],\"summaryFromSourceName\":false,\"summaryFromIssueSummary\":false}"
            },
            {
                "id": 5656,
                "calendarId": 1959,
                "emailsEnabled": false,
                "eventType": {
                    "issueRequired": false,
                    "key": "jira",
                    "name": "Jira dates",
                    "projectRequired": false,
                    "systemType": true,
                    "usersRequired": false
                },
                "order": 2,
                "value": "{\"color\":\"#cc6fcc\",\"condColors\":[],\"dateRanges\":[],\"singleDates\":[\"duedate\"],\"summaryFromSourceName\":false,\"projectId\":-1,\"name\":\"Dekki's JD source\",\"issueFields\":[{\"id\":\"duedate\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"issuekey\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"summary\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"issuetype\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"status\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"assignee\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"reporter\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"description\",\"showEvent\":false,\"showInfo\":true}],\"hideStartTime\":false}"
            }
        ],
        "value": "{\"description\":\"\",\"name\":\"Dekki Gedru's first calendar\",\"usersFromEvents\":true}",
        "user": "66625976fc0cc7a600b08977"
    },
    {
        "id": 1995,
        "sources": [
            {
                "id": 5779,
                "calendarId": 1995,
                "emailsEnabled": false,
                "eventType": {
                    "issueRequired": false,
                    "key": "jira",
                    "name": "Jira dates",
                    "projectRequired": false,
                    "systemType": true,
                    "usersRequired": false
                },
                "order": 1,
                "value": "{\"color\":\"#057fff\",\"condColors\":[],\"dateRanges\":[],\"singleDates\":[\"duedate\"],\"summaryFromSourceName\":false,\"projectId\":10336,\"name\":\"Jira dates events\",\"issueFields\":[{\"id\":\"duedate\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"issuekey\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"summary\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"issuetype\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"status\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"assignee\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"reporter\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"description\",\"showEvent\":false,\"showInfo\":true}],\"hideStartTime\":false}"
            },
            {
                "id": 5780,
                "calendarId": 1995,
                "emailsEnabled": false,
                "eventType": {
                    "issueRequired": false,
                    "key": "sprint",
                    "name": "Jira sprints",
                    "projectRequired": false,
                    "systemType": true,
                    "usersRequired": false
                },
                "order": 2,
                "value": "{\"boardId\":132,\"color\":\"#cc6fcc\",\"name\":\"Sprints\",\"projectId\":10336,\"show\":0,\"state\":0,\"hideStartTime\":false}"
            },
            {
                "id": 5781,
                "calendarId": 1995,
                "emailsEnabled": false,
                "eventType": {
                    "issueRequired": false,
                    "key": "version",
                    "name": "Jira versions",
                    "projectRequired": false,
                    "systemType": true,
                    "usersRequired": false
                },
                "order": 3,
                "value": "{\"name\":\"Versions\",\"color\":\"#ff3e05\",\"projectId\":10371,\"show\":0,\"releasedStatus\":0}"
            },
            {
                "id": 5782,
                "calendarId": 1995,
                "emailsEnabled": false,
                "eventType": {
                    "issueRequired": false,
                    "key": "trip",
                    "name": "Business trips",
                    "projectRequired": false,
                    "systemType": true,
                    "usersRequired": true
                },
                "order": 4,
                "value": "{\"color\":\"#40af04\",\"projectId\":0,\"condColors\":[],\"name\":\"Business trips\",\"issuesAsResources\":false,\"concurrence\":\"allow\",\"hideStartTime\":false,\"issueFields\":[{\"id\":\"event.summary\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.users\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.reporter\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.description\",\"showEvent\":true,\"showInfo\":true}],\"summaryFromSourceName\":false,\"summaryFromIssueSummary\":false}"
            }
        ],
        "value": "{\"description\":\"\",\"name\":\"Development\",\"usersFromEvents\":true}",
        "user": "6666d5194d18cbf6772f4"
    }
]

GET /api/1/calendar/{calendarId}

Returns the calendar for the given calendar id.

In addition to properties returned by GET /api/1/calendar , this method brings permissions related properties.

Successful response brings JSON with a calendar:

Company Calendar for Jira Documentation > REST API > image-20230214-124707.png

See the response sample:

{
    "id": 1959,
    "publicCalendar": false,
    "calendarEditable": false,
    "permCalendarEdit": {
        "groups": [],
        "users": []
    },
    "eventsEditable": false,
    "permEventsEdit": {
        "groups": [],
        "users": []
    },
    "eventReporterEdit": false,
    "sources": [
        {
            "id": 5655,
            "calendarId": 1959,
            "emailsEnabled": false,
            "eventType": {
                "issueRequired": false,
                "key": "meeting",
                "name": "Meetings",
                "projectRequired": false,
                "systemType": true,
                "usersRequired": true
            },
            "order": 1,
            "value": "{\"color\":\"#7500ca\",\"projectId\":-1,\"condColors\":[],\"name\":\"Dekki's meetings\",\"concurrence\":\"allow\",\"hideStartTime\":false,\"issueFields\":[{\"id\":\"issuekey\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.project\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"event.summary\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.users\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.reporter\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.description\",\"showEvent\":true,\"showInfo\":true}],\"summaryFromSourceName\":false,\"summaryFromIssueSummary\":false}"
        },
        {
            "id": 5656,
            "calendarId": 1959,
            "emailsEnabled": false,
            "eventType": {
                "issueRequired": false,
                "key": "jira",
                "name": "Jira dates",
                "projectRequired": false,
                "systemType": true,
                "usersRequired": false
            },
            "order": 2,
            "value": "{\"color\":\"#cc6fcc\",\"condColors\":[],\"dateRanges\":[],\"singleDates\":[\"duedate\"],\"summaryFromSourceName\":false,\"projectId\":-1,\"name\":\"Dekki's JD source\",\"issueFields\":[{\"id\":\"duedate\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"issuekey\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"summary\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"issuetype\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"status\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"assignee\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"reporter\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"description\",\"showEvent\":false,\"showInfo\":true}],\"hideStartTime\":false}"
        }
    ],
    "value": "{\"description\":\"\",\"name\":\"Dekki Gedru's first calendar\",\"usersFromEvents\":true}",
    "user": "534534976fc0cc7a60053444"
}

404 status code is returned for non-existing calendarId or when the calendarId is not associated with the token.

POST /api/1/calendar

Creates a new calendar.

Company Calendar for Jira Documentation > REST API > cf29953a-9943-47e1-a97c-78f608f63b89#media-blob-url=true&id=8d0f01b0-00c9-4092-a234-5d80ca4d5042&collection=&contextId=35627&mimeType=image%2Fpng&name=image-20241002-112938.png&size=68235&width=1439&height=325&alt=image-20241002-112938.png

To create a public calendar, please follow the example below.

Request Body:

{
  "publicCalendar": true,
  "calendarEditable": true,
  "eventsEditable": true,
  "value": "{\"name\":\"New public calendar\",\"usersFromEvents\":true}",
  "user": "userID"
}

To create a private calendar or a calendar with permission granted to specific users or groups, please use the following example.

Request Body:

{
  "publicCalendar": false,
  "permCalendarView": {
        "groups": [],
        "users": []
    },
  "calendarEditable": false,
  "permCalendarEdit": {
    "groups": [],
    "users": []
  },
  "eventsEditable": false,
  "permEventsEdit": {
    "groups": [],
    "users": []
  },
  "eventReporterEdit": false,
  "value": "{\"name\":\"New calendar\",\"usersFromEvents\":true}",
  "user": "userID"
}

Response: 200 OK: Returns the newly created calendar object (with calendar id)

PUT /api/1/calendar

Updates an existing calendar.

Company Calendar for Jira Documentation > REST API > 19c5564a-d107-4662-9c3f-ba981f5b6fd6#media-blob-url=true&id=8de7e1f7-78b1-4d0f-b9ea-ad97564fb28e&collection=&contextId=35627&mimeType=image%2Fpng&name=image-20241001-101107.png&size=58481&width=1435&height=395&alt=image-20241001-101107.png

Important: It is necessary to provide the complete value JSON object when updating resources. If any properties are omitted in the update request, they will be overwritten or lost. To retain all existing properties, ensure that you include them in the request body during the update.

Request body:

{
  "id": "calendarId",
  "publicCalendar": false,
  "permCalendarView": {
        "groups": [],
        "users": []
    },
  "calendarEditable": false,
  "permCalendarEdit": {
    "groups": [],
    "users": []
  },
  "eventsEditable": false,
  "permEventsEdit": {
    "groups": [],
    "users": []
  },
  "eventReporterEdit": false,
  "value": "{\"name\":\"Updated calendar\",\"usersFromEvents\":true}",
  "user": "userId"
}

Response:

200 OK: Calendar updated successfully. Returns the updated calendar object
400 Bad Request: Missing calendar ID.

DELETE /api/1/calendar/{id}

Deletes a calendar by its ID.

Deleting a calendar is possible when the token has the permission to delete the calendar.

Path Parameters:

id (Long): The ID of the calendar to delete.

Company Calendar for Jira Documentation > REST API > 342c6b98-1a1e-4f55-aa5f-e3aae9f202cd#media-blob-url=true&id=9bb2a0bd-85db-4326-8795-0d77a42fac62&collection=&contextId=35627&mimeType=image%2Fpng&name=image-20241001-101201.png&size=56987&width=1435&height=395&alt=image-20241001-101201.png

Response:

200 OK: Calendar deleted successfully. Returns the deleted calendar object.
403 Forbidden: Delete operation not allowed.

GET /api/1/eventypes

Retrieves all available event types, including predefined ones like vacation, sickness, trip, and meeting, along with any custom event types defined by the user.

Company Calendar for Jira Documentation > REST API > 965bd728-f0c5-4321-9616-3cda0a7a1d99#media-blob-url=true&id=9a7278d8-44a3-40b8-a981-bf3245d5f6d0&collection=&contextId=35627&mimeType=image%2Fpng&name=image-20241001-120512.png&size=54151&width=1435&height=356&alt=image-20241001-120512.png

Response:

200 OK: Returns a list of event types. The list includes both predefined types (e.g., vacation, sickness, trip, meeting) and custom types defined by the user.

POST /api/1/source

Creates a new source linked to a calendar.

For the POST /api/1/source endpoint, note that the eventTypeId should be obtained from the /api/1/eventypes endpoint.

Company Calendar for Jira Documentation > REST API > d5efe606-8ab0-40a5-afe4-bef4d5959d8d#media-blob-url=true&id=90ad9874-8001-4e66-85b3-78e20e8e9743&collection=&contextId=35627&mimeType=image%2Fpng&name=image-20241001-101543.png&size=43508&width=1435&height=356&alt=image-20241001-101543.png

Request Body:

{
  "eventTypeId":  <evenTypeId from  the /api/1/eventypes endpoint>,
  "calendarConfigurationId": <calendarId>,
  "emailsEnabled": false,
  "value": "{\"color\":\"#0fff04\",\"projectId\":-1,\"condColors\":[],\"name\":\"New source\",\"concurrence\":\"allow\",\"hideStartTime\":false,\"issueFields\":[{\"id\":\"issuekey\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.project\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"event.summary\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.users\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.reporter\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.description\",\"showEvent\":true,\"showInfo\":true}],\"summaryFromSourceName\":false,\"summaryFromIssueSummary\":false}"
}

PUT /api/1/source

Updates an existing source.

Company Calendar for Jira Documentation > REST API > 38a1224b-a8e6-4b59-b010-00d82737a6d8#media-blob-url=true&id=77df49e5-80a9-486e-b7f2-99bcb065bae9&collection=&contextId=35627&mimeType=image%2Fpng&name=image-20241001-121723.png&size=45210&width=1435&height=356&alt=image-20241001-121723.png

{
  "id": <sourceId>,
  "calendarConfigurationId": <calendarId>,
  "eventTypeId": <eventTypeId>,
  "emailsEnabled": false,
  "value": "{\"color\":\"#0fff04\",\"projectId\":-1,\"condColors\":[],\"name\":\"Updated source\",\"concurrence\":\"allow\",\"hideStartTime\":false,\"issueFields\":[{\"id\":\"issuekey\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.project\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"event.summary\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.users\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.reporter\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.description\",\"showEvent\":true,\"showInfo\":true}],\"summaryFromSourceName\":false,\"summaryFromIssueSummary\":false}"
}

Important: It is necessary to provide the complete value JSON object when updating resources. If any properties are omitted in the update request, they will be overwritten or lost. To retain all existing properties, ensure that you include them in the request body during the update.

GET /api/1/source/{sourceId}

Returns the source for the given source id.

Successful response brings JSON with a source representation:

Company Calendar for Jira Documentation > REST API > image-20230214-130143.png

See the response sample:

{
    "id": 5655,
    "calendarId": 1959,
    "emailsEnabled": false,
    "eventType": {
        "issueRequired": false,
        "key": "meeting",
        "name": "Meetings",
        "projectRequired": false,
        "systemType": true,
        "usersRequired": true
    },
    "order": 1,
    "value": "{\"color\":\"#7500ca\",\"projectId\":-1,\"condColors\":[],\"name\":\"Dekki's meetings\",\"concurrence\":\"allow\",\"hideStartTime\":false,\"issueFields\":[{\"id\":\"issuekey\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.project\",\"showEvent\":false,\"showInfo\":true},{\"id\":\"event.summary\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.users\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.reporter\",\"showEvent\":true,\"showInfo\":true},{\"id\":\"event.description\",\"showEvent\":true,\"showInfo\":true}],\"summaryFromSourceName\":false,\"summaryFromIssueSummary\":false}"
}

404 status code is returned for non-existing sourceId or when the sourceId belongs to a calendar that is not associated with the token.

DELETE /api/1/source/{id}

Deletes a source by its ID.

Path Parameters:

Deletes a source by its ID (Long): The ID of the source to delete.

Deleting a source is possible when the token has the permission to delete the source.

Company Calendar for Jira Documentation > REST API > e85da0d2-82e3-43ac-bb9a-6ad0d0e7152f#media-blob-url=true&id=5b964d5c-e4ef-4706-9726-07aad8ad5355&collection=&contextId=35627&mimeType=image%2Fpng&name=image-20241001-123640.png&size=45260&width=1435&height=356&alt=image-20241001-123640.png

Response:

200 OK: Source deleted successfully. Returns the deleted source object.
403 Forbidden

POST /api/1/event/search

Searches for events.

Only events from sources with type key vacation, sickness, trip, meeting or custom are returned.

JSON body parameters:

startDate		long	Unix milliseconds timestamp. Mutually exclusive with startDateIso and endDateIso.
endDate			long	Unix milliseconds timestamp. Mutually exclusive with startDateIso and endDateIso.
startDateIso	string	ISO 8601 date and time. Mutually exclusive with startDate and endDate.
endDateIso		string	Unix milliseconds timestamp. Mutually exclusive with startDateIso and endDateIso.
calendarId		long    Id of the calendar to fetch events from. Mutually exclusive with sourceId.
sourceId		long    Id of the source to fetch events from. Mutually exclusive with calendarId.

Interval between start and end dates should be less than 92 days (i.e. a quarter).

JSON body parameters samples:

Period passed as Unix milliseconds and calendarId:

{
  "startDate": 1672531200000,
  "endDate": 1680307200000,
  "calendarId": 1959
}

Here:
- startDate corresponds to Sun Jan 01 2023 00:00:00 GMT
- endDate corresponds to Sat Apr 01 2023 00:00:00 GMT

2. Period passed as ISO dates and sourceId:

{
  "startDateIso": "2023-01-01T00:00:00-05:00",
  "endDateIso": "2023-04-01T00:00:00-04:00",
  "sourceId": 5655
}

Here:
- startDateIso corresponds to Sun Jan 01 2023 00:00:00 EST
- endDateIso corresponds to Sat Apr 01 2023 00:00:00 DST

Successful response brings JSON with matching events:

Company Calendar for Jira Documentation > REST API > image-20230214-140804.png

As for now, values are non-paginated and all matching events are returned. We might introduce the pagination should we see the need.

See the response sample:

{
    "maxResults": 2147483647,
    "startAt": 0,
    "total": 16,
    "values": [
        {
            "sourceId": 5655,
            "userKeys": [
                "63c16312eac4f07e3f3c4650"
            ],
            "author": "63c16312eac4f07e3f3c4650",
            "allDayStart": "2023-01-01",
            "allDayEnd": "2023-01-01",
            "created": 1673618588000,
            "summary": "Dekki's 1st January meeting",
            "id": 13473
        },
        {
            "sourceId": 5655,
            "endDate": 1672736400000,
            "startDate": 1672732800000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1673341200000,
            "startDate": 1673337600000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1673622600000,
            "startDate": 1673620800000,
            "userKeys": [
                "63c16312eac4f07e3f3c4650"
            ],
            "author": "63c16312eac4f07e3f3c4650",
            "updateAuthor": "63c16312eac4f07e3f3c4650",
            "created": 1673618378000,
            "summary": "fisrt gedru's meeting",
            "updated": 1673618498000,
            "id": 13471
        },
        {
            "sourceId": 5655,
            "endDate": 1673778600000,
            "startDate": 1673776800000,
            "userKeys": [
                "63c16312eac4f07e3f3c4650"
            ],
            "author": "63c16312eac4f07e3f3c4650",
            "created": 1673618484000,
            "summary": "second dekki's meeting",
            "id": 13472
        },
        {
            "sourceId": 5655,
            "endDate": 1673946000000,
            "startDate": 1673942400000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1674550800000,
            "startDate": 1674547200000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1675155600000,
            "startDate": 1675152000000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1675760400000,
            "startDate": 1675756800000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1676365200000,
            "startDate": 1676361600000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1676970000000,
            "startDate": 1676966400000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1677574800000,
            "startDate": 1677571200000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1678179600000,
            "startDate": 1678176000000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1678784400000,
            "startDate": 1678780800000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1679389200000,
            "startDate": 1679385600000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        },
        {
            "sourceId": 5655,
            "endDate": 1679990400000,
            "startDate": 1679986800000,
            "userKeys": [
                "61eff161cb7c5f006be4b63e",
                "637236628fd2d2d5f12ba8d1",
                "62028c79f5d29a0068fb2036",
                "62028c799493720070b81cf7"
            ],
            "recurrence": "FREQ=WEEKLY;BYDAY=TU",
            "author": "5d333333333cab1017089",
            "updateAuthor": "5d333333333cab1017089",
            "created": 1676383015000,
            "summary": "Tuesday status meeting",
            "updated": 1676383045000,
            "id": 13848
        }
    ]
}

400 status code is returned when parameters validation fails. The status is accompanied with the error messages. E.g.:

Company Calendar for Jira Documentation > REST API > image-20230214-145124.png

404 status code is returned for non-existing calendarId or sourceId or when the calendarId or sourceId correspond to a calendar that is not associated with the token.

POST /api/1/event

Creates a new event.

Company Calendar for Jira Documentation > REST API > 2033d572-e2f3-4b75-bf24-1101f8569c9a#media-blob-url=true&id=64122b3f-009f-4e17-9fc5-234c004b1394&collection=&contextId=35627&mimeType=image%2Fpng&name=image-20241001-132618.png&size=63974&width=1435&height=356&alt=image-20241001-132618.png

To create an all-day event, please see the example below.

Request body:

{
  "event": {
    "summary": "All-day Rest API event",
    "eventTypeConfigId": "sourceId",
    "userKeys": ["account-id"],
    "allDayStart": "2024-09-29",
    "allDayEnd": "2024-09-29"
  },
  "mode": "add"
}

To create an event with the specified start and end times, please use the following example.

Request Body:

{
  "event": {
    "summary": "Timed Rest API event",
    "eventTypeConfigId": "sourceId",
    "userKeys": ["account-id"],
    "startDate": 1728367200000,
    "endDate": 1728369900000
  },
  "mode": "add"
}

Here:

startDate corresponds to Tue Oct 08 2024 06:00:00 GMT
endDate corresponds to Tue Oct 08 2024 06:45:00 GMT

Recurrent events

To create a recurrent event, please provide startDate and endDate to define the range to expand the occurrences.

Company Calendar for Jira Documentation > REST API > cad06092-9810-404c-a34b-1defd0461383#media-blob-url=true&id=c1ade8ea-9de2-4ddb-87c4-3aa3c738352b&collection=&contextId=35627&mimeType=image%2Fpng&name=image-20241001-135423.png&size=87167&width=1435&height=479&alt=image-20241001-135423.png

Request body:

{
  "event": {
    "recurrence": <recurrence rule>, // see specifications  👉️ https://icalendar.org/iCalendar-RFC-5545/3-8-5-3-recurrence-rule.html 
    "eventTypeConfigId": <sourceId>,
    "summary": "Recurrence event",
    "userKeys": [
      "account-id"
    ],
    "allDayStart": "2024-09-02",
    "allDayEnd": "2024-09-02"
  },
  "mode": "add",
  "startDate": "2024-08-26T00:00:00+03:00",
  "endDate": "2024-10-07T00:00:00+03:00"
}

Response:

200 OK: Event successfully created. Returns the created event object.

PUT /api/1/event

Updates an existing event.

Company Calendar for Jira Documentation > REST API > 96c9300b-3bcc-407d-b54f-a4c031e5b14b#media-blob-url=true&id=d5574322-54d6-4492-afb8-de540c2260a2&collection=&contextId=35627&mimeType=image%2Fpng&name=image-20241001-133159.png&size=71346&width=1435&height=356&alt=image-20241001-133159.png

{
  "event": {
    "id": <id>,
    "summary": "Update event",
    "eventTypeConfigId": <evenTypedId>,
    "userKeys": [
      account-id
    ],
    "allDayStart": "2024-08-29",
    "allDayEnd": "2024-08-29"
  },
  "mode": "edit"
}

Update a recurrent event

Company Calendar for Jira Documentation > REST API > 5ed8a538-80ba-4d63-a1be-0544a0de5e11#media-blob-url=true&id=dab25eb1-9f3c-4fcc-9700-e11591b477c7&collection=&contextId=35627&mimeType=image%2Fpng&name=image-20241001-140114.png&size=106759&width=1435&height=479&alt=image-20241001-140114.png

Request body:

{
  "event": {
    "allDayEnd": "2024-09-19",
    "allDayStart": "2024-09-19",
    "eventTypeConfigId": 14817,
    "summary": "Recurrence event",
    "userKeys": [
      "5b0d271581c3df12acf5298e"
    ],
    "parentId": 60707,
    "recurrenceId": "20240904",
     "id": 60709  // Only required for subsequent updates; omit this field when creating the event for the first time
  },
  "mode": "edit",
  "select": "current",
  "startDate": "2024-08-26T00:00:00+03:00",
  "endDate": "2024-10-07T00:00:00+03:00"
}

Response:

200 OK: Event updated successfully.
400 Bad Request: Missing event ID.

DELETE /api/1/event/{id}

Deletes an event by its ID.

Path Parameters:

id (Long): The ID of the event to delete.

Response:

200 OK: Event deleted successfully.

DELETE /api/1/event/{id}/recur

This endpoint handles deletion operations for recurring events. Depending on the request body, you can delete the entire recurrence chain, a single occurrence, or remove a specific instance from a recurring series.

Path Parameters

id (Long): The ID of the recurring event or the specific occurrence to be deleted.

Company Calendar for Jira Documentation > REST API > 10f057bd-85c2-4caf-a107-ac10bda372fc#media-blob-url=true&id=6bdbaa84-7683-4f1c-8004-b5269a04226f&collection=&contextId=35627&mimeType=image%2Fpng&name=image-20241001-134650.png&size=115302&width=1435&height=669&alt=image-20241001-134650.png

Deletion Scenarios

Delete the Entire Recurrence Chain (ALL)
If the event is a recurring series, and the recurrence_id is defined in the model:
- The parentId in the model is used to indicate the main recurring event.
- The entire recurrence chain, including all occurrences, will be deleted.
Delete the Current Event from the Chain (Single Event Deletion)
If the event has a recurrence_id:
- The id in the URL points to a single event within the recurrence chain.
- The parentId in the model refers to the main event, which is the parent of the recurrence chain.
- Only the specified event will be deleted, while the rest of the chain remains intact.
Delete an Occurrence (Add Exception Date to the Main Chain)
To delete a specific occurrence of the recurring event (without deleting the entire series):
- The model should have the same parentId as the main event, while the id is used in the request URL to specify the occurrence.
- The parentId in the model will be overridden by the provided id, ensuring that only the specified occurrence is removed.
- Mode: "delete"
  Select: "current"
  Exdate: The date (YYYY-MM-DD) to exclude from the recurring event.

Exemples body:

Delete the Current Event from the Chain (Single Event Deletion)

{
  "event": {
    "eventTypeConfigId":  <sourceId>,
    "recurrenceId":	"20240906",
    "parentId":	<parentId>
  },
  "exdate": "YYYYMMDD",
  "select": "current",
  "startDate": "2024-08-26T00:00:00+03:00",
  "endDate": "2024-10-07T00:00:00+03:00"
}

Delete an Occurrence (Add Exception Date to the Main Chain)

{
  "event": {
    "eventTypeConfigId": <sourceId>
  },
  "select": "current", 
  "exdate": "YYYYMMDD",
  "startDate": "2024-08-26T00:00:00+03:00",
  "endDate": "2024-10-07T00:00:00+03:00"
}

note

We have tickets to implement following functionality:

to create or edit events via the REST API:.
to create or edit calendars or sources via the REST API: .

If you are interested in these features, please contact us through the support portal https://brizoit.atlassian.net/servicedesk/customer/portal/3.

We have tickets to implement following functionality:

to create or edit events via the REST API: CJ-4727 - Getting issue details... STATUS .
to create or edit calendars or sources via the REST API: CJ-4733 - Getting issue details... STATUS .

If you are interested in these features, please contact us through the support portal https://brizoit.atlassian.net/servicedesk/customer/portal/3.