# Events ## Get All Events From a Calendar `GET` `https://api.pyas.io/google/events` #### Query Parameters | Name | Type | Description | | -------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | calendarId\* | String | The id of the Google calendar | | accountId\* | String | The user's Pyas account id. This is returned when you connect an account to Pyas. | | startDate | Timestamp/Date String |

Filter events by start date

(ex: 01-01-2022)

| | endDate | Timestamp/Date String |

Filter events by end time

(ex: 01-01-2023)

| | search | String | Free text search terms to find events that match these terms in the following fields: `summary`, `description`, `location`, attendee's `displayName`, attendee's `email`. | | nextPageToken | String | Token string used to get the next page of results (paginate) | | maxResults | Integer | Max number of results to return per page | | syncToken | String | Token obtained from the `nextSyncToken` field returned on the last page of results | | eventTypes | String |

Event types to return. Acceptable values are:

| | iCalUID | String | Use this if you want to search for an event by its iCalendar ID. | | maxAttendees | Integer | The maximum number of attendees to include in the response. | | orderBy | String |

The order of the events returned in the result. Acceptable values are:

| | privateExtendedProperty | String | Extended properties constraint specified as `propertyName=value`. Matches only private properties. | | sharedExtendedProperty | String | Extended properties constraint specified as `propertyName=value`. Matches only shared properties | | showDeleted | Boolean | Whether to include deleted events (with status = "cancelled") in the result. | | singleEvents | Boolean | Whether to expand recurring events into instances and only return single one-off events and instances of recurring events, but not the underlying recurring events themselves. Optional. The default is False. | | timeZone | String | Time zone used in the response. Optional. The default is the time zone of the calendar. | | showHiddenInvitations | Boolean | Whether to include hidden invitations in the result. Optional. The default is False. | | updatedMin | Timestamp/Date String | Filter events by last modified/updated time | | filters | JSON |

Query filteres provided in JSON key-value pairs.

ex: {"singleEvents": true} Note: This is supported, but not recommended.

See possible filters list below.

| #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | x-api-key\* | String | API key | {% tabs %} {% tab title="200: OK Successfully retrieved events" %} 
{
    "success": true,
    "data": {
        "nextSyncToken": string|null,
        "nextPageToken": string|null,
        "events": [
            {
                "kind": "calendar#event",
                "etag": "\"00000\"",
                "id": "string",
                "status": "confirmed",
                "htmlLink": "string",
                "created": "2023-01-05T01:56:37.000Z",
                "updated": "2023-01-05T01:56:38.403Z",
                "summary": "some summary",
                "description": "some description",
                "creator": {
                    "email": "string"
                },
                "organizer": {
                    "email": "string"
                },
                "start": {
                    "dateTime": "2023-01-11T13:00:00-05:00",
                    "timeZone": "UTC"
                },
                "end": {
                    "dateTime": "2023-01-11T13:15:00-05:00",
                    "timeZone": "UTC"
                },
                "iCalUID": "string",
                "sequence": 0,
                "attendees": [
                    {
                        "email": "string",
                        "organizer": true,
                        "responseStatus": "string"
                    },
                    {
                        "email": "string",
                        "self": true,
                        "responseStatus": "stringd"
                    }
                ],
                "reminders": {
                    "useDefault": boolean
                },
                "eventType": "string"
            },
        ]
    }
}
{% endtab %} {% tab title="401: Unauthorized Invalid/missing API key" %} ```json { "error": "Unauthorized. Invalid API key." } ``` {% endtab %} {% tab title="400: Bad Request Missing calendar id" %} ```json { "errors": [ { "msg": "a calendar id is required.", "param": "calendarId", "location": "query" } ] } ``` {% endtab %} {% tab title="400: Bad Request Missing account id" %} ```json { "errors": [ { "msg": "an account id is required.", "param": "accountId", "location": "query" } ] } ``` {% endtab %} {% tab title="400: Bad Request Missing both calendar id and account id" %} ```json { "errors": [ { "msg": "an account id is required.", "param": "accountId", "location": "query" }, { "msg": "a calendar id is required.", "param": "calendarId", "location": "query" } ] } ``` {% endtab %} {% tab title="404: Not Found Account Not Found. Invalid accountId" %} ```json { "success": false, "error": "Invalid account id. Account Not Found", "code": 404 } ``` {% endtab %} {% tab title="404: Not Found Calendar Not Found" %} ```json { "success": false, "error": "Not Found", "code": 404 } ``` {% endtab %} {% endtabs %} *** #### List of Possible Filters Below is a list of flags/filters that can be used when listing events. Simply send these as JSON in the `filters` parameter. We support this, but it's better to send these filters as single query parameters. ```typescript startDate, endDate, nextPageToken, search, maxResults, filters, syncToken, eventTypes, iCalUID, maxAttendees, orderBy, privateExtendedProperty, sharedExtendedProperty, showDeleted, showHiddenInvitations, singleEvents, timeZone, updatedMin, ``` ## Get Event by ID `GET` `https://api.pyas.io/google/events/{id}` Gets a calendar event by id #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------ | | {id}\* | String | The event id | #### Query Parameters | Name | Type | Description | | -------------------------------------------- | ------ | --------------------------------------------------------------------------------- | | calendarId\* | String | The Google Calendar id | | accountId\* | String | The user's Pyas account id. This is returned when you connect an account to Pyas. | #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | x-api-key\* | String | API key | {% tabs %} {% tab title="200: OK Successfully retrieved the event" %} ```json { "success": true, "data": { "event": { "kind": "calendar#event", "etag": "\"00000000\"", "id": "string", "status": "string", "htmlLink": "string", "created": "2023-01-05T01:56:37.000Z", "updated": "2023-01-05T01:56:38.403Z", "summary": "some summary", "description": "some description" "email": "string" }, "organizer": { "email": "string" }, "start": { "dateTime": "2023-01-11T13:00:00-05:00", "timeZone": "UTC" }, "end": { "dateTime": "2023-01-11T13:15:00-05:00", "timeZone": "UTC" }, "iCalUID": "string", "sequence": 0, "attendees": [ { "email": "string", "organizer": true, "responseStatus": "accepted" }, { "email": "string", "self": true, "responseStatus": "accepted" } ], "reminders": { "useDefault": true }, "eventType": "default" } } } ``` {% endtab %} {% tab title="401: Unauthorized Invalid/Missing API key" %} ```json { "error": "Unauthorized. Invalid API key." } ``` {% endtab %} {% tab title="400: Bad Request Missing fields" %} ```json { "errors": [ { "msg": "calendar id is required", "param": "calendarId", "location": "query" }, { "msg": "calendar id must be a string", "param": "calendarId", "location": "query" } ] } ``` {% endtab %} {% tab title="404: Not Found Calendar Not Found" %} ```json { "success": false, "error": "Not Found", "code": 404 } ``` {% endtab %} {% tab title="404: Not Found Account Not Found. Invalid accountId" %} ```json { "success": false, "error": "Invalid account id. Account Not Found", "code": 404 } ``` {% endtab %} {% endtabs %} ## Create Event `POST` `https://api.pyas.io/google/events` Creates a calendar event #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | x-api-key\* | String | API key | #### Request Body | Name | Type | Description | | ------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- | | accountId\* | String | The user's Pyas account id. This is returned when you connect an account to Pyas. | | calendarId\* | String | The Google calendar id | | eventData\* | Object | The event data. See the Required [**Event Data Object**](#event-data-object-example) example below. | | eventData.title\* | String | The event title | | eventData.description\* | String | Event description | | eventData.startDate\* | DateTime | RFC3339 Timestamp | | eventData.endDate\* | DateTime | RFC3339 Timestamp | | eventData.timeZone | String | Time Zone in IANA format | | eventData.location | Object | Location object - See the example [**Event Location Object**](#event-location-object-example) | | eventData.attendees | Array | Array of [**Attendee Objects**](#attendee-object-example) | | eventData.conferencing | Object | An [**Event Conferencing Object**](#event-conferencing-object-example) | | eventData.phone | String | Phone number | | eventData.phonePin | String | Optional pin if one is required to join the meeting | | eventData.recurrence | Object | Recurrence object for recurring events. See the [**Recurrence Object**](#recurrence-object) below. | | eventData.meta | Object | Optional. Use this to add additional/extra event body fields. | {% tabs %} {% tab title="200: OK Event created" %} ```json { "success": true, "data": { "kind": "calendar#event", "etag": "\"000000000000000\"", "id": "string", "status": "confirmed", "htmlLink": "string", "created": "2023-03-06T23:06:14.000Z", "updated": "2023-03-06T23:06:14.350Z", "summary": "Example Event", "description": "example", "location": "712 Applesauce Rd Austin, TX 73301", "creator": { "email": "example@gmail.com", "self": true }, "organizer": { "email": "example@gmail.com", "self": true }, "start": { "dateTime": "2023-03-06T18:06:12-05:00", "timeZone": "America/New_York" }, "end": { "dateTime": "2023-03-06T18:36:12-05:00", "timeZone": "America/New_York" }, "iCalUID": "string", "sequence": 0, "attendees": [ { "email": "example@gmail.com", "displayName": "Jane Doe", "responseStatus": "needsAction" } ], "reminders": { "useDefault": true }, "eventType": "default" } } ``` {% endtab %} {% tab title="401: Unauthorized Invalid/Missing API key" %} ```json { "error": "Unauthorized. Invalid API key." } ``` {% endtab %} {% tab title="404: Not Found Account Not Found. Invalid accountId" %} ```json { "success": false, "error": "Invalid account id. Account Not Found", "code": 404 } ``` {% endtab %} {% tab title="404: Not Found Calendar Not Found" %} ```json { "success": false, "error": "Not Found", "code": 404 } ``` {% endtab %} {% tab title="400: Bad Request Missing required fields" %} ```json { "errors": [ { "value": { "description": "example", "startDate": "2023-03-06T23:12:25.069Z", "endDate": "2023-03-06T23:42:25.069Z", "timeZone": "America/New_York", "location": { "street": "712 Applesauce Rd", "city": "Austin", "state": "TX", "zipCode": "73301", "country": "USA" }, "attendees": [ { "name": "Jane Doe", "email": "example@gmail.com" } ] }, "msg": "eventData.title is required and must be a string", "param": "eventData", "location": "body" } ] } ``` {% endtab %} {% endtabs %} ### **Event Data Object Example**: ```json { "title": "Example Event", // String - Required. "description": "example", // String - Required. "startDate": "2023-03-06T22:51:08.434Z", // RFC3339 timestamp - Required. "endDate": "2023-03-06T23:21:08.434Z", // RFC3339 timestamp - Required. "timeZone": "America/New_York", // IANA Time Zone format - Optional. "location": { "street": "712 Applesauce Rd", "city": "Austin", "state": "TX", "zipCode": "73301", "country": "USA" }, // Object - Optional. (required when creating an event with a physocal location) "attendees": [ { "name": "Jane Doe", "email": "example@gmail.com" } ] // Required. } ``` ### Event Location Object Example: ```json { "street": "712 Applesauce Rd", // String - Required. "city": "Austin", // String - Required. "state": "TX", // String - Required. "zipCode": "73301", // String - Required. "country": "USA" // String - Required. }, ``` ### Attendee Object Example: ```json { "name": "Jane Doe", // String - Required. "email": "example@gmail.com" // String - Required. } ``` ### Event Conferencing Object: ```typescript { "provider": string, // Required. Possible values: "google-meet", "zoom" "accountId": string, // Optional. - Only Required if provider = zoom. This is the ID for the connected Zoom account in Pyas. "waitingRoom": boolean // Optional. - Only Required if provider = zoom } ``` ### Event Data With Google Meet Conferencing Example: ```json { "title": "Example Event 2", "description": "example", "startDate": "2023-03-06T22:51:08.434Z", "endDate": "", "conferencing": { "provider": "google-meet" }, "timeZone": "America/New_York", "attendees": [ { "name": "Jane Doe", "email": "example@gmail.com" } ] } ``` ### Recurrence Object: ```typescript { type: string // daily, weekly, or monthly - Required. interval: number|string // Define the interval at which the meeting should recur. (ex. 2 for every two weeks with type of weekly) - Required. startDate?: string // the dateTime of when the recurring meeting will start (used for Microsoft Outlook only) endDate?: string // the dateTime of when the recurring meeting will end dayOfMonth?: number|string // day of month for a monthly meeting. 1 - 31 (ex. 15 for the 15th of every month) daysOfWeek?: Array // days of week for a weekly meeting type (ex. ['monday', 'wednesday']) month?: number|string // The month in which the event occurs. This is a number from 1 to 12. (Microsoft and Google only) } ``` Here's an example of a recurrence object for a meeting that repeats weekly every Wednesday: 
{
    "type": "weekly",
    "interval": 1,
    "daysOfWeek": ["wednesday"],
    "endDate": "2023-08-01T22:26:39.109Z"
}
## Event Data Meta Object Example More request body fields from the official Google Docs can be found here: Simply include the extra fields you need to `eventData.meta`. If you need to store custom properties to the event, you can do so by adding a nested [**extendedProperties** ](https://developers.google.com/calendar/api/guides/extended-properties)object to `eventData.meta`. Please see the [example below](#example-eventdata-with-meta-object). Note: `eventData.meta` should only be used to include fields that aren't already a part of the standard body fields in the ***eventData*** object. Also note that there won't be a **meta** field on the event body/data returned in the response. Instead, any properties/fields that were sent in `eventData.meta` will be spread onto the event body that gets returned in the response. ```typescript { birthdayProperties?: { type: string //anniversary, birthday, custom, other, self } colorId?: string eventType?: string // birthday, default, focusTime, fromGmail, outOfOffice, workingLocation focusTimeProperties?: { autoDeclineMode?: string // declineNone, declineAllConflictingInvitations, declineOnlyNewConflictingInvitations chatStatus?: string // available, doNotDisturb declineMessage?: string } guestsCanModify?: boolean // false by default guestsCanInviteOthers?: boolean //true by default guestsCanSeeOtherGuests?: boolean //true by default visibility?: string // default, private, public transparency?: string // opaque, transparent // etc... } ``` ### Example EventData with Meta Object ```json { "title": "Test Event w/ Metadata", "description": "example with metadata", "startDate": "{{start_time}}", "endDate": "{{end_time}}", "timeZone": "America/New_York", "location": { "street": "712 Applesauce Rd", "city": "Austin", "state": "TX", "zipCode": "73301", "country": "USA" }, "attendees": [ { "name": "Jane Doe", "email": "user@gmail.com" } ], "meta": { "guestsCanModify": true, "guestsCanInviteOthers": false, "extendedProperties": { "private": { "petsAllowed": "yes", //more private extended properties } } } } ``` ## Update Event `PATCH` `https://api.pyas.io/google/events/{id}` Updates an Existing Event #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------ | | {id}\* | String | The event ID | #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | x-api-key\* | String | API Key | #### Request Body | Name | Type | Description | | -------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | | accountId\* | String | The user's Pyas account id. This is returned when you connect an account to Pyas. | | calendarId\* | String | The Google calendar id | | eventData\* | Object | Event data object with the fields to update. See the [**Example Update Event Date Object**](#update-event-data-object-example) below. | | eventData.meta | Object | Optional. Additional fields to include in the update request. See the [Event Data Meta Object Example](#event-data-meta-object-example) above. | {% tabs %} {% tab title="200: OK Event updated successfully" %} ```json { "success": true, "data": { "kind": "calendar#event", "etag": "\"000000000\"", "id": "ae019d68ac9b4ff6823d5c3b81d761f9", "status": "confirmed", "htmlLink": "string", "created": "2023-03-08T18:34:01.000Z", "updated": "2023-03-08T18:46:43.015Z", "summary": "Interview", "description": "Interview with Elon", "location": "712 Applesauce Rd Austin, TX 73301", "creator": { "email": "example@gmail.com", "self": true }, "organizer": { "email": "example@gmail.com", "self": true }, "start": { "dateTime": "2023-03-08T15:16:40-05:00", "timeZone": "America/New_York" }, "end": { "dateTime": "2023-03-08T15:46:40-05:00", "timeZone": "America/New_York" }, "iCalUID": "string", "sequence": 1, "attendees": [ { "email": "example@gmail.com", "displayName": "Jane Doe", "responseStatus": "needsAction" } ], "reminders": { "useDefault": true }, "eventType": "default" } } ``` {% endtab %} {% tab title="404: Not Found Calendar Not Found" %} ```json { "success": false, "error": "Not Found", "code": 404 } ``` {% endtab %} {% tab title="404: Not Found Account Not Found/Invalid Account Id" %} ```json { "success": false, "error": "Invalid account id. Account Not Found", "code": 404 } ``` {% endtab %} {% tab title="400: Bad Request Missing eventData" %} ```json { "errors": [ { "msg": "eventData is required.", "param": "eventData", "location": "body" }, { "msg": "eventData must be an object", "param": "eventData", "location": "body" }, { "msg": "Invalid value", "param": "eventData", "location": "body" } ] } ``` {% endtab %} {% endtabs %} ### Update Event Data Object Example: ```json { "title": "Interview", "description": "Interview with Elon", "startDate": "2023-03-06T22:51:08.434Z", "endDate": "2023-03-06T23:21:08.434Z", "timeZone": "America/New_York" } ``` ## Delete Event `DELETE` `https://api.pyas.io/google/events/{id}` Deletes an existing event #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------ | | {id}\* | String | The event ID | #### Query Parameters | Name | Type | Description | | -------------------------------------------- | ------ | --------------------------------------------------------------------------------- | | accountId | String | The user's Pyas account id. This is returned when you connect an account to Pyas. | | calendarId\* | String | The Google calendar ID | #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | x-api-key\* | String | API Key | {% tabs %} {% tab title="204: No Content Event was deleted successfully" %} ```javascript { // Response } ``` {% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.pyas.io/rest-api-reference/google-calendar/events.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.