Events

An event /ɪˈvɛnt/ is what you'd expect. It has a start time, a title and various pieces of metadata. Every event belongs to a specific calendar.

The event model

The event model contains metadata about the event.

Properties

Name
id
Type
string
Description
Unique identifier for the event in the Calapi API
Name
title
Type
string
Description
Title of the event
Name
description
Type
string?
Description
Description of the event
Name
location
Type
string?
Description
The location of the event as a string
Name
status
Type
string
Description
The status of the event. Either "confirmed" or "cancelled"
Name
start
Type
object
Description
The start time of the event. Start and end times are represented as an object with three properties: date, date_time and time_zone. For all day events the date field will be set to the ISO 8601 representation of the date i.e. 2024-08-03.
For normal events the start will be represented as an ISO 8601 UTC date time with precision to the second e.g. 2024-08-03T12:00:00Z on the date_time property. The time_zone property will be the IANA Time Zone database name e.g. Europe/London or Asia/Calcutta.
Name
end
Type
object
Description
The end time of the event. See the documentation of start above for the format.
Name
color
Type
string
Description
The color of the event as a hex string
Name
provider
Type
string
Description
The provider of this calendar. Either google, zoho, ics, caldav or icloud.
Name
provider_id
Type
string
Description
The internal id used by the provider to refer to this calendar
Name
calendar_id
Type
string
Description
The id of the calendar that the event belongs to in the Calapi API
Name
canonical_url
Type
string
Description
The event's URL in the Calapi API. You can use this to update or delete the Event.

The event Model

{
  "id": "6kq68o9j68o3ab9ichhj0b9kckq62bb261i62bb66crjgdpl6pi3cohgco",
  "title": "Field Day festival",
  "description": "Field day returns in 2024 with a top line up including PinkPantheress and Charlotte de Witte",
  "location": "Victoria Park, London",
  "status": "confirmed",
  "start": {
    "date": "2024-08-24",
    "date_time": null,
    "time_zone": null
  },
  "end": {
    "date": "2024-08-25",
    "date_time": null,
    "time_zone": null
  },
  "color": "#7ae7bf",
  "provider": "google",
  "provider_id": "6kq68o9j68o3ab9ichhj0b9kckq62bb261i62bb66crjgdpl6pi3cohgco",
  "calendar_id": "cal_p0L6j8LRO2",
  "canonical_url": "https://api.calapi.io/calendars/cal_p0L6j8LRO2/events/6kq68o9j68o3ab9ichhj0b9kckq62bb261i62bb66crjgdpl6pi3cohgco"
},

GET/calendars/:calendar_id/events/

List all events

This endpoint allows you to retrieve a list of all your events.

Optional query parameters

Name
range_start
Type
datetime
Description
Filters events by those that occur (either start or finish) after this ISO 8601 datetime.
Name
range_end
Type
datetime
Description
Filters events by those that occur (either start or finish) before this ISO 8601 datetime.

Request

GET

/calendars/cal_p0L6j8LRO2/events

curl --location 'https://api.calapi.io/calendars/cal_p0L6j8LRO2/events' \
  -H 'Authorization: Bearer {token}'

Response

{
  "data": [
    {
      "id": "a5jnip3e95mkmda98dk3cs1n8d15cebmap9makr968q4iujpdpjlar9i85b6uu3l81mm2obb5lgmepbechgisrjc",
      "title": "Tottenham Hotspur - Burnley FC",
      "description": "Calendar not up to date? Check https://fixtur.es/up-to-date",
      "location": "Tottenham Hotspur Stadium, 782 High Rd, London, N17 0BX",
      "status": "confirmed",
      "end": {
        "date": null,
        "date_time": "2024-05-11T15:45:00Z",
        "time_zone": "UTC"
      },
      "start": {
        "date": null,
        "date_time": "2024-05-11T14:00:00Z",
        "time_zone": "UTC"
      },
      "color": "#f6bf26",
      "provider": "google",
      "provider_id": "_a5jnip3e95mkmda98dk3cs1n8d15cebmap9makr968q4iujpdpjlar9i85b6uu3l81mm2obb5lgmepbechgisrjc",
      "calendar_id": "cal_YUJMya8hsk",
      "canonical_url": "https://api.calapi.io/calendars/cal_YUJMya8hsk/events/_a5jnip3e95mkmda98dk3cs1n8d15cebmap9makr968q4iujpdpjlar9i85b6uu3l81mm2obb5lgmepbechgisrjc"
    },
    // Other events...
  ]
}

POST/calendars/:calendar_id/events/

Create an event

This endpoint allows you to create a new event on one of your providers. It will return a 201 status code on success.

Required body parameters

Name
title
Type
string
Description
Title of the event
Name
description
Type
string?
Description
Description of the event
Name
start
Type
object
Description
The start time of the event
Name
end
Type
object
Description
The end time of the event. See the documentation of start above for the format.

Optional body parameters

Name
description
Type
string
Description
The description of the event
Name
location
Type
string
Description
The location of the event
Name
color
Type
string
Description
The color of the event. This can be either in hexadecimal form or a color alias. Be warned that some calendar providers do not allow arbitrary colors. See the colors documentation for more details.

Request

POST

https://api.calapi.io/calendars/cal_YUJMya8hsk/events

curl --location 'https://api.calapi.io/calendars/cal_p0L6j8LRO2/events' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}' \
--data '{
 "title": "Rolland Garros Final",
 "description": "The French Open, also known as Roland-Garros, is a major tennis tournament held over two weeks at the Stade Roland Garros in Paris",
 "location": "Paris",
 "color": "sage",
 "start": {
   "date_time": "2024-05-09T15:00:00Z",
   "time_zone": "Europe/Paris"
 },
 "end": {
   "date_time": "2024-05-09T18:00:00Z",
   "time_zone": "Europe/Paris"
 }
}'

Response

{
  "data": {
    "id": "dhveh0070tvnak5vjfk0f4f3kc",
    "title": "Rolland Garros Final",
    "description": "The French Open, also known as Roland-Garros, is a major tennis tournament held over two weeks at the Stade Roland Garros in Paris",
    "location": "Paris",
    "status": "confirmed",
    "start": {
      "date": null,
      "date_time": "2024-05-09T13:00:00Z",
      "time_zone": "Europe/Paris"
    },
    "end": {
      "date": null,
      "date_time": "2024-05-09T16:00:00Z",
      "time_zone": "Europe/Paris"
    },
    "color": "#33b679",
    "provider": "google",
    "provider_id": "dhveh0070tvnak5vjfk0f4f3kc",
    "calendar_id": "cal_p0L6j8LRO2",
    "canonical_url": "https://api.calapi.io/calendars/cal_p0L6j8LRO2/events/dhveh0070tvnak5vjfk0f4f3kc"
  }
}

GET/calendars/:calendar_id/events/:id

Retrieve an event

This endpoint allows you to retrieve an event by providing the event id.

Request

GET

/calendars/cal_p0L6j8LRO2/events/dhveh0070tvnak5vjfk0f4f3kc

curl --location 'https://api.calapi.io/events/cal_0vR36ILzVL' \
    -H 'Authorization: Bearer {token}'

Response

{
  "data": {
    "id": "dhveh0070tvnak5vjfk0f4f3kc",
    "title": "Rolland Garros Final",
    "description": "The French Open, also known as Roland-Garros, is a major tennis tournament held over two weeks at the Stade Roland Garros in Paris",
    "location": "Paris",
    "status": "confirmed",
    "start": {
      "date": null,
      "time_zone": "Europe/Paris",
      "date_time": "2024-05-09T13:00:00Z"
    },
    "end": {
      "date": null,
      "time_zone": "Europe/Paris",
      "date_time": "2024-05-09T16:00:00Z"
    },
    "color": "#33b679",
    "provider": "google",
    "provider_id": "dhveh0070tvnak5vjfk0f4f3kc",
    "calendar_id": "cal_p0L6j8LRO2",
    "canonical_url": "https://api.calapi.io/calendars/cal_p0L6j8LRO2/events/dhveh0070tvnak5vjfk0f4f3kc"
  }
}

PATCH/calendar/:calendar_id/events/:id

Update an event

This endpoint allows you to perform an update on an event. Examples of updates are adding a reaction, editing the event, or adding an attachment.

Optional body parameters

Name
title
Type
string
Description
The updated title of the event
Name
description
Type
string
Description
The updated description of the event
Name
location
Type
string
Description
The updated description of the event
Name
start
Type
object
Description
The start time of the event
Name
end
Type
object
Description
The end time of the event. See the documentation of start above for the format.
Name
color
Type
string
Description
The color of the event. This can be either in hexadecimal form or a color alias. Be warned that some calendar providers do not allow arbitrary colors. See the colors documentation for more details.

Request

PATCH

/calendars/cal_p0L6j8LRO2/events/dhveh0070tvnak5vjfk0f4f3kc

curl --location 'https://api.calapi.io/calendars/cal_p0L6j8LRO2/events/dhveh0070tvnak5vjfk0f4f3kc' \
--header 'Authorization: Bearer {token}' \
--data '{
  "description": "The French Open Final"
}'

Response

{
  "data": {
    "id": "dhveh0070tvnak5vjfk0f4f3kc",
    "title": "The French Open Final",
    "description": "The French Open, also known as Roland-Garros, is a major tennis tournament held over two weeks at the Stade Roland Garros in Paris",
    "location": "Stade Roland Garros, Paris",
    "status": "confirmed",
    "start": {
      "date": null,
      "time_zone": "Europe/Paris",
      "date_time": "2024-05-09T13:00:00Z"
    },
    "end": {
      "date": null,
      "time_zone": "Europe/Paris",
      "date_time": "2024-05-09T16:00:00Z"
    },
    "color": "#33b679",
    "provider": "google",
    "provider_id": "dhveh0070tvnak5vjfk0f4f3kc",
    "calendar_id": "cal_p0L6j8LRO2",
    "canonical_url": "https://api.calapi.io/calendars/cal_p0L6j8LRO2/events/dhveh0070tvnak5vjfk0f4f3kc"
  }
}

DELETE/calendars/:calendar_id/events/:id

Delete an event

This endpoint allows you to delete events. Note: The event will be permanently deleted.

On success a 204 status code will be returned with an empty response.

Request

DELETE

/calendars/cal_p0L6j8LRO2/events/eve_3NsbrDnK4p

curl --location --request DELETE 'https://api.calapi.io/calendars/cal_p0L6j8LRO2/events/eve_3NsbrDnK4p' \
  -H 'Authorization: Bearer {token}'