Using API v1? See what changes in v2, or the v1 docs

Calendars

Manage calendars, calendar sharing, categories, feeds and calendar groups.

The examples use IDs from a sample sandbox. Your sandbox has the same people, calendars and events with its own IDs, which GET /v2/sandbox returns. When you're signed in to the dashboard, Try it fills in your IDs and sends the request to your sandbox, never to live data.

GET/v2/calendar-groups

List calendar groups

Calendar groups are Outlook folders that contain calendars. Google Calendar doesn't have calendar groups, so requests for Google accounts are rejected.

Sends the request to your sandbox, never to live data.

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. Required here or in the request body of a write.

Errors

Request

GET
/v2/calendar-groups
curl 'https://api.pyas.io/v2/calendar-groups?accountId=sbx_fda58c5980_outlook' \  -H "x-api-key: $PYAS_API_KEY"

Response

200 OK
{  "success": true,  "data": [    {      "id": "AAMkAPtDnBoVMLgLIu-5ZykUH3m3F8jh-vhqP8YlJhgiZLHEAAA=",      "name": "My Calendars",      "calendarIds": [        "AAMkAU662pGNAu0JgQ5Fpjf1wipv7j82pYQuBvDbbTPOq8h4AAA="      ]    },    {      "id": "AAMkAyCWrTohk9tAZoyL6-kuuLYadpDmD-3sFfQAb6CXpof0AAA=",      "name": "Other calendars",      "calendarIds": [        "AAMkAPZCx8r3fRaim7oP6DyRH-4h12pnbtU0iizh-r7n7VpQAAA="      ]    },    {      "id": "AAMkAFDoRdCjiMqrQ0gUzJhGn7fWP7a-kYNGIymOmCmTrT7cAAA=",      "name": "Clients",      "calendarIds": [        "AAMkA-M9ePPI-lDjuHutrLL7ee-FjiW4n60cpd6GPnyDTv84AAA="      ]    },    {      "id": "AAMkAYE1Kc3zrnSLkXx5fXHBEPOfQSybhu8nRccpNiIpXWVwAAA=",      "name": "Projects",      "calendarIds": []    }  ],  "provider": "microsoft",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
POST/v2/calendar-groups

Create a calendar group

Calendar groups are Outlook folders that contain calendars. Google Calendar doesn't have calendar groups, so requests for Google accounts are rejected.

In the sandbox: Calendar groups are an Outlook feature. For Google accounts, the API returns an error explaining that Google doesn't support them.

Sends the request to your sandbox, never to live data.

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. Required here or in the request body of a write.

Headers

  • Name
    Idempotency-Key
    Type
    string
    Description

    A unique key that makes the request safe to retry. A retry with the same key returns the original response and does not make the change twice. Keys are kept for 24 hours.

Body

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. You can send it here or in the query.

  • Name
    name
    Type
    string
    Required
    required
    Description

Errors

Request

POST
/v2/calendar-groups
curl -X POST 'https://api.pyas.io/v2/calendar-groups?accountId=sbx_fda58c5980_outlook' \  -H "x-api-key: $PYAS_API_KEY" \  -H "content-type: application/json" \  -d '{  "name": "Partners"}'

Response

201 Created
{  "success": true,  "data": {    "id": "AAMkAkhQyt3s2NcmZzvgLwdE68IZ07bC7gBnR6Qr6TyKO3qYAAA=",    "name": "Partners",    "calendarIds": []  },  "provider": "microsoft",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
GET/v2/calendars

List calendars

Returns the calendars of one connected account, one page at a time. With accountIds or subjectId, returns every calendar of each account in one response, grouped by account.

Sends the request to your sandbox, never to live data.

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. Required here or in the request body of a write.

  • Name
    limit
    Type
    integer
    Description

    The maximum number of results in one page. From 1 to 250.

  • Name
    cursor
    Type
    string
    Description

    The nextCursor from the previous page.

  • Name
    accountIds
    Type
    string
    Description

    The Pyas accountId values of up to 20 connected accounts. Send a comma-separated list or repeat the parameter.

  • Name
    subjectId
    Type
    string
    Description

    Selects every connected account labeled with this subjectId.

  • Name
    provider
    Type
    string
    Description

    Limits accountIds or subjectId to accounts on this provider. One of google, microsoft, pyas.

Errors

Request

GET
/v2/calendars
curl 'https://api.pyas.io/v2/calendars?accountId=sbx_fda58c5980_1' \  -H "x-api-key: $PYAS_API_KEY"

Response

200 OK
{  "success": true,  "data": [    {      "id": "calfda58c59801p",      "name": "Avery Brooks",      "description": null,      "timezone": "America/New_York",      "isPrimary": true,      "color": null,      "accessRole": "owner",      "location": null,      "conferencing": {        "default": null,        "allowed": [          "zoom"        ]      },      "tallyResponses": null,      "hidden": false,      "provider": "pyas",      "providerRefs": {        "calendarId": "calfda58c59801p",        "accountId": "sbx_fda58c5980_1"      },      "metadata": null    },    {      "id": "calfda58c59801w",      "name": "Work",      "description": null,      "timezone": "America/New_York",      "isPrimary": false,      "color": "#039be5",      "accessRole": "owner",      "location": null,      "conferencing": {        "default": null,        "allowed": [          "zoom"        ]      },      "tallyResponses": null,      "hidden": false,      "provider": "pyas",      "providerRefs": {        "calendarId": "calfda58c59801w",        "accountId": "sbx_fda58c5980_1"      },      "metadata": null    }  ],  "provider": "pyas",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {    "nextCursor": null  }}
POST/v2/calendars

Create a calendar

Sends the request to your sandbox, never to live data.

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. Required here or in the request body of a write.

Headers

  • Name
    Idempotency-Key
    Type
    string
    Description

    A unique key that makes the request safe to retry. A retry with the same key returns the original response and does not make the change twice. Keys are kept for 24 hours.

Body

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. You can send it here or in the query.

  • Name
    name
    Type
    string
    Required
    required
    Description
  • Name
    description
    Type
    string | null
    Description
  • Name
    timezone
    Type
    string | null
    Description
  • Name
    color
    Type
    string | null
    Description

    The color, as #rrggbb.

  • Name
    location
    Type
    string | null
    Description

    Google Calendar only.

  • Name
    conferencing
    Type
    object
    Description
  • Name
    conferencing.default
    Type
    string | null
    Description
  • Name
    conferencing.allowed
    Type
    array of string
    Description
  • Name
    tallyResponses
    Type
    boolean
    Description

    Outlook only.

  • Name
    hidden
    Type
    boolean
    Description

    Google Calendar only. Whether to hide the calendar from the calendar list.

  • Name
    groupId
    Type
    string
    Description

    Outlook only, when creating a calendar. The calendar group to create it in.

  • Name
    metadata
    Type
    Metadata
    Description

    Your own key-value pairs, stored by Pyas with the object. A value is text, a number, a boolean or a list of those.

  • Name
    providerOptions
    Type
    ProviderOptions
    Description

    Provider-specific fields that have no equivalent in v2, grouped by provider. Each group applies only to accounts on that provider.

Errors

Request

POST
/v2/calendars
curl -X POST 'https://api.pyas.io/v2/calendars' \  -H "x-api-key: $PYAS_API_KEY" \  -H "content-type: application/json" \  -d '{  "accountId": "sbx_fda58c5980_1",  "name": "Client meetings",  "timezone": "America/New_York",  "color": "#33b679",  "metadata": {    "team": "sales"  }}'

Response

201 Created
{  "success": true,  "data": {    "id": "calba3nh0btrcap9js6fcfv",    "name": "Client meetings",    "description": null,    "timezone": "America/New_York",    "isPrimary": false,    "color": "#33b679",    "accessRole": "owner",    "location": null,    "conferencing": {      "default": null,      "allowed": [        "zoom"      ]    },    "tallyResponses": null,    "hidden": false,    "provider": "pyas",    "providerRefs": {      "calendarId": "calba3nh0btrcap9js6fcfv",      "accountId": "sbx_fda58c5980_1"    },    "metadata": {      "team": "sales"    }  },  "provider": "pyas",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
GET/v2/colors

Get color palettes

Returns the calendar and event colors that the account's provider offers, as #rrggbb values.

Sends the request to your sandbox, never to live data.

Query parameters

  • Name
    accountId
    Type
    string
    Required
    required
    Description

    The Pyas accountId of the connected account.

Errors

Request

GET
/v2/colors
curl 'https://api.pyas.io/v2/colors?accountId=sbx_fda58c5980_google' \  -H "x-api-key: $PYAS_API_KEY"

Response

200 OK
{  "success": true,  "data": {    "calendarColors": [      {        "id": "1",        "color": "#ac725e"      },      {        "id": "2",        "color": "#d06b64"      },      {        "id": "3",        "color": "#f83a22"      },      {        "id": "4",        "color": "#fa573c"      },      {        "id": "5",        "color": "#ff7537"      },      {        "id": "6",        "color": "#ffad46"      },      {        "id": "7",        "color": "#42d692"      },      {        "id": "8",        "color": "#16a765"      },      {        "id": "9",        "color": "#7bd148"      },      {        "id": "10",        "color": "#b3dc6c"      },      {        "id": "11",        "color": "#fbe983"      },      {        "id": "12",        "color": "#fad165"      },      {        "id": "13",        "color": "#92e1c0"      },      {        "id": "14",        "color": "#9fe1e7"      },      {        "id": "15",        "color": "#9fc6e7"      },      {        "id": "16",        "color": "#4986e7"      },      {        "id": "17",        "color": "#9a9cff"      },      {        "id": "18",        "color": "#b99aff"      },      {        "id": "19",        "color": "#c2c2c2"      },      {        "id": "20",        "color": "#cabdbf"      },      {        "id": "21",        "color": "#cca6ac"      },      {        "id": "22",        "color": "#f691b2"      },      {        "id": "23",        "color": "#cd74e6"      },      {        "id": "24",        "color": "#a47ae2"      }    ],    "eventColors": [      {        "id": "1",        "color": "#a4bdfc"      },      {        "id": "2",        "color": "#7ae7bf"      },      {        "id": "3",        "color": "#dbadff"      },      {        "id": "4",        "color": "#ff887c"      },      {        "id": "5",        "color": "#fbd75b"      },      {        "id": "6",        "color": "#ffb878"      },      {        "id": "7",        "color": "#46d6db"      },      {        "id": "8",        "color": "#e1e1e1"      },      {        "id": "9",        "color": "#5484ed"      },      {        "id": "10",        "color": "#51b749"      },      {        "id": "11",        "color": "#dc2127"      }    ]  },  "provider": "google",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
PATCH/v2/calendar-groups/{groupId}

Rename a calendar group

Calendar groups are Outlook folders that contain calendars. Google Calendar doesn't have calendar groups, so requests for Google accounts are rejected.

Sends the request to your sandbox, never to live data.

Path parameters

  • Name
    groupId
    Type
    string
    Required
    required
    Description

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. Required here or in the request body of a write.

Headers

  • Name
    Idempotency-Key
    Type
    string
    Description

    A unique key that makes the request safe to retry. A retry with the same key returns the original response and does not make the change twice. Keys are kept for 24 hours.

Body

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. You can send it here or in the query.

  • Name
    name
    Type
    string
    Required
    required
    Description

Errors

Request

PATCH
/v2/calendar-groups/{groupId}
curl -X PATCH 'https://api.pyas.io/v2/calendar-groups/AAMkAYE1Kc3zrnSLkXx5fXHBEPOfQSybhu8nRccpNiIpXWVwAAA%3D?accountId=sbx_fda58c5980_outlook' \  -H "x-api-key: $PYAS_API_KEY" \  -H "content-type: application/json" \  -d '{  "name": "Key projects"}'

Response

200 OK
{  "success": true,  "data": {    "id": "AAMkAYE1Kc3zrnSLkXx5fXHBEPOfQSybhu8nRccpNiIpXWVwAAA=",    "name": "Key projects",    "calendarIds": []  },  "provider": "microsoft",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
DELETE/v2/calendar-groups/{groupId}

Delete a calendar group

Calendar groups are Outlook folders that contain calendars. Google Calendar doesn't have calendar groups, so requests for Google accounts are rejected.

In the sandbox: Outlook doesn't delete a group that still contains calendars, and the API returns an error explaining why.

Sends the request to your sandbox, never to live data.

Path parameters

  • Name
    groupId
    Type
    string
    Required
    required
    Description

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. Required here or in the request body of a write.

Headers

  • Name
    Idempotency-Key
    Type
    string
    Description

    A unique key that makes the request safe to retry. A retry with the same key returns the original response and does not make the change twice. Keys are kept for 24 hours.

Errors

Request

DELETE
/v2/calendar-groups/{groupId}
curl -X DELETE 'https://api.pyas.io/v2/calendar-groups/AAMkAYE1Kc3zrnSLkXx5fXHBEPOfQSybhu8nRccpNiIpXWVwAAA%3D?accountId=sbx_fda58c5980_outlook' \  -H "x-api-key: $PYAS_API_KEY"

Response

200 OK
{  "success": true,  "data": null,  "provider": "microsoft",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
GET/v2/calendars/{calendarRef}

Get a calendar

Sends the request to your sandbox, never to live data.

Path parameters

  • Name
    calendarRef
    Type
    string
    Required
    required
    Description

    The calendar ID returned by the provider, or primary for the account's primary calendar.

Query parameters

  • Name
    accountId
    Type
    string
    Required
    required
    Description

    The accountId of the connected account.

Errors

Request

GET
/v2/calendars/{calendarRef}
curl 'https://api.pyas.io/v2/calendars/calfda58c59801w?accountId=sbx_fda58c5980_1' \  -H "x-api-key: $PYAS_API_KEY"

Response

200 OK
{  "success": true,  "data": {    "id": "calfda58c59801w",    "name": "Work",    "description": null,    "timezone": "America/New_York",    "isPrimary": false,    "color": "#039be5",    "accessRole": "owner",    "location": null,    "conferencing": {      "default": null,      "allowed": [        "zoom"      ]    },    "tallyResponses": null,    "hidden": false,    "provider": "pyas",    "providerRefs": {      "calendarId": "calfda58c59801w",      "accountId": "sbx_fda58c5980_1"    },    "metadata": null  },  "provider": "pyas",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
PATCH/v2/calendars/{calendarRef}

Update a calendar

Updates the calendar. Send only the fields to update. Set description, timezone, color or location to null to clear it.

Sends the request to your sandbox, never to live data.

Path parameters

  • Name
    calendarRef
    Type
    string
    Required
    required
    Description

    The calendar ID returned by the provider, or primary for the account's primary calendar.

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. Required here or in the request body of a write.

Headers

  • Name
    Idempotency-Key
    Type
    string
    Description

    A unique key that makes the request safe to retry. A retry with the same key returns the original response and does not make the change twice. Keys are kept for 24 hours.

Body

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. You can send it here or in the query.

  • Name
    name
    Type
    string
    Description
  • Name
    description
    Type
    string | null
    Description
  • Name
    timezone
    Type
    string | null
    Description
  • Name
    color
    Type
    string | null
    Description

    The color, as #rrggbb.

  • Name
    location
    Type
    string | null
    Description

    Google Calendar only.

  • Name
    conferencing
    Type
    object
    Description
  • Name
    conferencing.default
    Type
    string | null
    Description
  • Name
    conferencing.allowed
    Type
    array of string
    Description
  • Name
    tallyResponses
    Type
    boolean
    Description

    Outlook only.

  • Name
    hidden
    Type
    boolean
    Description

    Google Calendar only. Whether to hide the calendar from the calendar list.

  • Name
    groupId
    Type
    string
    Description

    Outlook only, when creating a calendar. The calendar group to create it in.

  • Name
    metadata
    Type
    Metadata
    Description

    Your own key-value pairs, stored by Pyas with the object. A value is text, a number, a boolean or a list of those.

  • Name
    providerOptions
    Type
    ProviderOptions
    Description

    Provider-specific fields that have no equivalent in v2, grouped by provider. Each group applies only to accounts on that provider.

Errors

Request

PATCH
/v2/calendars/{calendarRef}
curl -X PATCH 'https://api.pyas.io/v2/calendars/calfda58c59801w?accountId=sbx_fda58c5980_1' \  -H "x-api-key: $PYAS_API_KEY" \  -H "content-type: application/json" \  -d '{  "name": "Work (team)"}'

Response

200 OK
{  "success": true,  "data": {    "id": "calfda58c59801w",    "name": "Work (team)",    "description": null,    "timezone": "America/New_York",    "isPrimary": false,    "color": "#039be5",    "accessRole": "owner",    "location": null,    "conferencing": {      "default": null,      "allowed": [        "zoom"      ]    },    "tallyResponses": null,    "hidden": false,    "provider": "pyas",    "providerRefs": {      "calendarId": "calfda58c59801w",      "accountId": "sbx_fda58c5980_1"    },    "metadata": null  },  "provider": "pyas",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
DELETE/v2/calendars/{calendarRef}

Delete a calendar

Deletes the calendar and its events at the provider. A primary calendar cannot be deleted.

Sends the request to your sandbox, never to live data.

Path parameters

  • Name
    calendarRef
    Type
    string
    Required
    required
    Description

    The calendar ID returned by the provider, or primary for the account's primary calendar.

Query parameters

  • Name
    accountId
    Type
    string
    Required
    required
    Description

    The accountId of the connected account.

Headers

  • Name
    Idempotency-Key
    Type
    string
    Description

    A unique key that makes the request safe to retry. A retry with the same key returns the original response and does not make the change twice. Keys are kept for 24 hours.

Errors

Request

DELETE
/v2/calendars/{calendarRef}
curl -X DELETE 'https://api.pyas.io/v2/calendars/calfda58c59804w?accountId=sbx_fda58c5980_4' \  -H "x-api-key: $PYAS_API_KEY"

Response

200 OK
{  "success": true,  "data": null,  "provider": "pyas",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
POST/v2/calendars/subscribe

Subscribe to a calendar

Adds a calendar that the account has access to, such as a colleague's calendar or a shared calendar, to the account's calendar list.

In the sandbox: Google adds any calendar the account has access to. The sandbox accepts any calendar ID, but a live account must have access to the calendar. Outlook adds a shared calendar only when the person accepts the invitation, so for Outlook accounts the API returns an error explaining that it can't add the calendar.

Sends the request to your sandbox, never to live data.

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. Required here or in the request body of a write.

Headers

  • Name
    Idempotency-Key
    Type
    string
    Description

    A unique key that makes the request safe to retry. A retry with the same key returns the original response and does not make the change twice. Keys are kept for 24 hours.

Body

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. You can send it here or in the query.

  • Name
    calendarId
    Type
    string
    Required
    required
    Description

    The ID of the calendar to add, such as a colleague's email address.

Errors

Request

POST
/v2/calendars/subscribe
curl -X POST 'https://api.pyas.io/v2/calendars/subscribe' \  -H "x-api-key: $PYAS_API_KEY" \  -H "content-type: application/json" \  -d '{  "accountId": "sbx_fda58c5980_google",  "calendarId": "team-calendar@example.com"}'

Response

201 Created
{  "success": true,  "data": {    "id": "team-calendar@example.com",    "name": "team-calendar@example.com",    "description": null,    "timezone": "America/New_York",    "isPrimary": false,    "color": "#9fc6e7",    "accessRole": "reader",    "location": null,    "conferencing": {      "default": null,      "allowed": []    },    "tallyResponses": null,    "hidden": false,    "provider": "google",    "providerRefs": {      "calendarId": "team-calendar@example.com",      "accountId": "sbx_fda58c5980_google"    }  },  "provider": "google",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
GET/v2/calendars/{calendarRef}/categories

List categories

Lists the values that events accept in categories. On Outlook, there is one list for the whole mailbox. On Google Calendar, these are the calendar's event labels.

Sends the request to your sandbox, never to live data.

Path parameters

  • Name
    calendarRef
    Type
    string
    Required
    required
    Description

    The calendar ID returned by the provider, or primary for the account's primary calendar.

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. Required here or in the request body of a write.

Errors

Request

GET
/v2/calendars/{calendarRef}/categories
curl 'https://api.pyas.io/v2/calendars/primary/categories?accountId=sbx_fda58c5980_outlook' \  -H "x-api-key: $PYAS_API_KEY"

Response

200 OK
{  "success": true,  "data": [    {      "id": "2eb82094-ec40-4d5d-a8b8-15cf273998c1",      "name": "Red category",      "color": "#e74856"    },    {      "id": "945326ef-02ee-47a7-a625-8364f33d9abd",      "name": "Orange category",      "color": "#f7630c"    },    {      "id": "d4c5c9cb-5502-42de-a335-3f8f85322a98",      "name": "Yellow category",      "color": "#fce100"    },    {      "id": "109ef2a3-89fc-4525-a7b8-d4d3eddfec23",      "name": "Green category",      "color": "#16c60c"    },    {      "id": "0eed55fa-f6a2-4cb2-a808-1ab178ff93b5",      "name": "Blue category",      "color": "#0078d7"    },    {      "id": "18d6d65c-6b1e-47ac-ac6f-5ae45fad5968",      "name": "Purple category",      "color": "#8764b8"    }  ],  "provider": "microsoft",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
POST/v2/calendars/{calendarRef}/categories

Create a category

In the sandbox: Outlook categories belong to the mailbox, so they are the same for every calendar, and they use Outlook's own colors (the nearest color is used). Google categories are per-calendar labels and accept any color.

Sends the request to your sandbox, never to live data.

Path parameters

  • Name
    calendarRef
    Type
    string
    Required
    required
    Description

    The calendar ID returned by the provider, or primary for the account's primary calendar.

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. Required here or in the request body of a write.

Headers

  • Name
    Idempotency-Key
    Type
    string
    Description

    A unique key that makes the request safe to retry. A retry with the same key returns the original response and does not make the change twice. Keys are kept for 24 hours.

Body

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. You can send it here or in the query.

  • Name
    name
    Type
    string
    Required
    required
    Description
  • Name
    color
    Type
    string
    Description

Errors

Request

POST
/v2/calendars/{calendarRef}/categories
curl -X POST 'https://api.pyas.io/v2/calendars/primary/categories?accountId=sbx_fda58c5980_outlook' \  -H "x-api-key: $PYAS_API_KEY" \  -H "content-type: application/json" \  -d '{  "name": "Client work",  "color": "#33b679"}'

Response

201 Created
{  "success": true,  "data": {    "id": "ee111d87-0428-40cf-875f-2f0f2b7c5d4a",    "name": "Client work",    "color": "#16c60c"  },  "provider": "microsoft",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
GET/v2/calendars/{calendarRef}/feed

Get a calendar's feed

Returns the state and link of a virtual calendar's iCalendar subscription feed, which calendar apps can subscribe to.

Sends the request to your sandbox, never to live data.

Path parameters

  • Name
    calendarRef
    Type
    string
    Required
    required
    Description

    The calendar ID returned by the provider, or primary for the account's primary calendar.

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the virtual calendar account.

Errors

Request

GET
/v2/calendars/{calendarRef}/feed
curl 'https://api.pyas.io/v2/calendars/primary/feed?accountId=sbx_fda58c5980_2' \  -H "x-api-key: $PYAS_API_KEY"

Response

200 OK
{  "success": true,  "data": {    "enabled": false,    "url": null,    "webcalUrl": null,    "details": null,    "createdAt": null,    "expiresAt": null  },  "provider": "pyas",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
PUT/v2/calendars/{calendarRef}/feed

Enable a calendar's feed

Publishes a virtual calendar as an iCalendar feed that people can subscribe to. If the feed is already enabled, only details is updated, and the link stays the same.

Sends the request to your sandbox, never to live data.

Path parameters

  • Name
    calendarRef
    Type
    string
    Required
    required
    Description

    The calendar ID returned by the provider, or primary for the account's primary calendar.

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the virtual calendar account.

Headers

  • Name
    Idempotency-Key
    Type
    string
    Description

    A unique key that makes the request safe to retry. A retry with the same key returns the original response and does not make the change twice. Keys are kept for 24 hours.

Body

  • Name
    accountId
    Type
    string
    Description

    The accountId of the virtual calendar account. You can also send it as a query parameter.

  • Name
    details
    Type
    string
    Description

    full (the default) includes titles, locations and notes. busy shows only when the calendar is busy. One of full, busy.

Errors

Request

PUT
/v2/calendars/{calendarRef}/feed
curl -X PUT 'https://api.pyas.io/v2/calendars/primary/feed?accountId=sbx_fda58c5980_2' \  -H "x-api-key: $PYAS_API_KEY" \  -H "content-type: application/json" \  -d '{  "details": "busy"}'

Response

200 OK
{  "success": true,  "data": {    "enabled": true,    "url": "https://cal.pyas.io/feeds/D_Gflr0xO2HNSXG26-HC1jZIOauvvfJyBo_S7MbS8IA.ics",    "webcalUrl": "webcal://cal.pyas.io/feeds/D_Gflr0xO2HNSXG26-HC1jZIOauvvfJyBo_S7MbS8IA.ics",    "details": "busy",    "createdAt": "2026-11-14T20:00:25.503Z",    "expiresAt": "2026-11-21T20:00:25.503Z"  },  "provider": "pyas",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
DELETE/v2/calendars/{calendarRef}/feed

Disable a calendar's feed

Disables the feed. The feed link stops working, and subscribers stop receiving updates.

Sends the request to your sandbox, never to live data.

Path parameters

  • Name
    calendarRef
    Type
    string
    Required
    required
    Description

    The calendar ID returned by the provider, or primary for the account's primary calendar.

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the virtual calendar account.

Headers

  • Name
    Idempotency-Key
    Type
    string
    Description

    A unique key that makes the request safe to retry. A retry with the same key returns the original response and does not make the change twice. Keys are kept for 24 hours.

Errors

Request

DELETE
/v2/calendars/{calendarRef}/feed
curl -X DELETE 'https://api.pyas.io/v2/calendars/primary/feed?accountId=sbx_fda58c5980_2' \  -H "x-api-key: $PYAS_API_KEY"

Response

200 OK
{  "success": true,  "data": {    "enabled": false,    "url": null,    "webcalUrl": null,    "details": null,    "createdAt": null,    "expiresAt": null  },  "provider": "pyas",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
GET/v2/calendars/{calendarRef}/permissions

List calendar permissions

Sends the request to your sandbox, never to live data.

Path parameters

  • Name
    calendarRef
    Type
    string
    Required
    required
    Description

    The calendar ID returned by the provider, or primary for the account's primary calendar.

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. Required here or in the request body of a write.

Errors

Request

GET
/v2/calendars/{calendarRef}/permissions
curl 'https://api.pyas.io/v2/calendars/primary/permissions?accountId=sbx_fda58c5980_google' \  -H "x-api-key: $PYAS_API_KEY"

Response

200 OK
{  "success": true,  "data": [    {      "id": "user:avery.brooks@example.com",      "grantee": {        "type": "user",        "email": "avery.brooks@example.com",        "domain": null,        "name": null      },      "role": "owner",      "removable": false    },    {      "id": "user:sam.patel@example.org",      "grantee": {        "type": "user",        "email": "sam.patel@example.org",        "domain": null,        "name": null      },      "role": "read",      "removable": true    }  ],  "provider": "google",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
POST/v2/calendars/{calendarRef}/permissions

Share a calendar

In the sandbox: Each provider supports its own set of roles. Google supports freeBusy, read, write and owner. Outlook also supports limitedRead, and has delegate roles instead of owner. If a provider doesn't support a role, the request is rejected with an error that explains why.

Sends the request to your sandbox, never to live data.

Path parameters

  • Name
    calendarRef
    Type
    string
    Required
    required
    Description

    The calendar ID returned by the provider, or primary for the account's primary calendar.

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. Required here or in the request body of a write.

Headers

  • Name
    Idempotency-Key
    Type
    string
    Description

    A unique key that makes the request safe to retry. A retry with the same key returns the original response and does not make the change twice. Keys are kept for 24 hours.

Body

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. You can send it here or in the query.

  • Name
    grantee
    Type
    object
    Required
    required
    Description

    Who to share the calendar with.

  • Name
    grantee.type
    Type
    string
    Required
    required
    Description

    One of user, group, domain, public, organization.

  • Name
    grantee.email
    Type
    string
    Description

    The email address. Required for a user or group.

  • Name
    grantee.domain
    Type
    string
    Description

    The domain, such as example.com. Required for a domain.

  • Name
    grantee.name
    Type
    string
    Description
  • Name
    role
    Type
    PermissionRole
    Required
    required
    Description

    The level of access, from least to most: freeBusy (free/busy only), limitedRead (titles and locations, Outlook only), read (everything except private events), write (editing), delegate and delegateWithPrivate (a delegate, Outlook only), and owner (full control, Google Calendar only). One of freeBusy, limitedRead, read, write, delegate, delegateWithPrivate, owner.

  • Name
    notify
    Type
    boolean
    Description

    Whether to email the grantee about the new permission. Google Calendar only, because Outlook decides whether to send the email.

Errors

Request

POST
/v2/calendars/{calendarRef}/permissions
curl -X POST 'https://api.pyas.io/v2/calendars/primary/permissions?accountId=sbx_fda58c5980_google' \  -H "x-api-key: $PYAS_API_KEY" \  -H "content-type: application/json" \  -d '{  "grantee": {    "type": "user",    "email": "assistant@example.com"  },  "role": "read"}'

Response

201 Created
{  "success": true,  "data": {    "id": "user:assistant@example.com",    "grantee": {      "type": "user",      "email": "assistant@example.com",      "domain": null,      "name": null    },    "role": "read",    "removable": true  },  "provider": "google",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
DELETE/v2/calendars/{calendarRef}/subscription

Unsubscribe from a calendar

Removes the calendar from the account's calendar list. The calendar itself isn't deleted.

Sends the request to your sandbox, never to live data.

Path parameters

  • Name
    calendarRef
    Type
    string
    Required
    required
    Description

    The calendar ID returned by the provider, or primary for the account's primary calendar.

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. Required here or in the request body of a write.

Headers

  • Name
    Idempotency-Key
    Type
    string
    Description

    A unique key that makes the request safe to retry. A retry with the same key returns the original response and does not make the change twice. Keys are kept for 24 hours.

Errors

Request

DELETE
/v2/calendars/{calendarRef}/subscription
curl -X DELETE 'https://api.pyas.io/v2/calendars/en.usa%23holiday@group.v.calendar.google.com/subscription?accountId=sbx_fda58c5980_google' \  -H "x-api-key: $PYAS_API_KEY"

Response

200 OK
{  "success": true,  "data": null,  "provider": "google",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
PATCH/v2/calendars/{calendarRef}/categories/{categoryId}

Update a category

In the sandbox: On Outlook, you can update a category's color but not its name. On Google, you can also rename labels.

Sends the request to your sandbox, never to live data.

Path parameters

  • Name
    calendarRef
    Type
    string
    Required
    required
    Description

    The calendar ID returned by the provider, or primary for the account's primary calendar.

  • Name
    categoryId
    Type
    string
    Required
    required
    Description

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. Required here or in the request body of a write.

Headers

  • Name
    Idempotency-Key
    Type
    string
    Description

    A unique key that makes the request safe to retry. A retry with the same key returns the original response and does not make the change twice. Keys are kept for 24 hours.

Body

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. You can send it here or in the query.

  • Name
    name
    Type
    string
    Description
  • Name
    color
    Type
    string
    Description

Errors

Request

PATCH
/v2/calendars/{calendarRef}/categories/{categoryId}
curl -X PATCH 'https://api.pyas.io/v2/calendars/primary/categories/0eed55fa-f6a2-4cb2-a808-1ab178ff93b5?accountId=sbx_fda58c5980_outlook' \  -H "x-api-key: $PYAS_API_KEY" \  -H "content-type: application/json" \  -d '{  "color": "#f6bf26"}'

Response

200 OK
{  "success": true,  "data": {    "id": "0eed55fa-f6a2-4cb2-a808-1ab178ff93b5",    "name": "Blue category",    "color": "#fce100"  },  "provider": "microsoft",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
DELETE/v2/calendars/{calendarRef}/categories/{categoryId}

Delete a category

Sends the request to your sandbox, never to live data.

Path parameters

  • Name
    calendarRef
    Type
    string
    Required
    required
    Description

    The calendar ID returned by the provider, or primary for the account's primary calendar.

  • Name
    categoryId
    Type
    string
    Required
    required
    Description

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. Required here or in the request body of a write.

Headers

  • Name
    Idempotency-Key
    Type
    string
    Description

    A unique key that makes the request safe to retry. A retry with the same key returns the original response and does not make the change twice. Keys are kept for 24 hours.

Errors

Request

DELETE
/v2/calendars/{calendarRef}/categories/{categoryId}
curl -X DELETE 'https://api.pyas.io/v2/calendars/primary/categories/d4c5c9cb-5502-42de-a335-3f8f85322a98?accountId=sbx_fda58c5980_outlook' \  -H "x-api-key: $PYAS_API_KEY"

Response

200 OK
{  "success": true,  "data": null,  "provider": "microsoft",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
POST/v2/calendars/{calendarRef}/feed/rotate

Rotate a feed's link

Creates a new link for the feed. The old link stops working immediately. Use this when a link was shared too widely.

Sends the request to your sandbox, never to live data.

Path parameters

  • Name
    calendarRef
    Type
    string
    Required
    required
    Description

    The calendar ID returned by the provider, or primary for the account's primary calendar.

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the virtual calendar account.

Headers

  • Name
    Idempotency-Key
    Type
    string
    Description

    A unique key that makes the request safe to retry. A retry with the same key returns the original response and does not make the change twice. Keys are kept for 24 hours.

Errors

Request

POST
/v2/calendars/{calendarRef}/feed/rotate
curl -X POST 'https://api.pyas.io/v2/calendars/primary/feed/rotate?accountId=sbx_fda58c5980_2' \  -H "x-api-key: $PYAS_API_KEY"

Response

200 OK
{  "success": true,  "data": {    "enabled": true,    "url": "https://cal.pyas.io/feeds/lWpiTMfSX4Gl5H8tvoNz966qj6jeZuWGltO0U_1tdYw.ics",    "webcalUrl": "webcal://cal.pyas.io/feeds/lWpiTMfSX4Gl5H8tvoNz966qj6jeZuWGltO0U_1tdYw.ics",    "details": "busy",    "createdAt": "2026-11-14T20:00:25.510Z",    "expiresAt": "2026-11-21T20:00:25.510Z"  },  "provider": "pyas",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
PATCH/v2/calendars/{calendarRef}/permissions/{permissionId}

Update a calendar permission

In the sandbox: Google identifies a share by its grantee (user:email), and Outlook uses its own ID. Use an ID from the list.

Sends the request to your sandbox, never to live data.

Path parameters

  • Name
    calendarRef
    Type
    string
    Required
    required
    Description

    The calendar ID returned by the provider, or primary for the account's primary calendar.

  • Name
    permissionId
    Type
    string
    Required
    required
    Description

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. Required here or in the request body of a write.

Headers

  • Name
    Idempotency-Key
    Type
    string
    Description

    A unique key that makes the request safe to retry. A retry with the same key returns the original response and does not make the change twice. Keys are kept for 24 hours.

Body

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. You can send it here or in the query.

  • Name
    role
    Type
    PermissionRole
    Required
    required
    Description

    The level of access, from least to most: freeBusy (free/busy only), limitedRead (titles and locations, Outlook only), read (everything except private events), write (editing), delegate and delegateWithPrivate (a delegate, Outlook only), and owner (full control, Google Calendar only). One of freeBusy, limitedRead, read, write, delegate, delegateWithPrivate, owner.

Errors

Request

PATCH
/v2/calendars/{calendarRef}/permissions/{permissionId}
curl -X PATCH 'https://api.pyas.io/v2/calendars/primary/permissions/user%3Asam.patel@example.org?accountId=sbx_fda58c5980_google' \  -H "x-api-key: $PYAS_API_KEY" \  -H "content-type: application/json" \  -d '{  "role": "write"}'

Response

200 OK
{  "success": true,  "data": {    "id": "user:sam.patel@example.org",    "grantee": {      "type": "user",      "email": "sam.patel@example.org",      "domain": null,      "name": null    },    "role": "write",    "removable": true  },  "provider": "google",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}
DELETE/v2/calendars/{calendarRef}/permissions/{permissionId}

Delete a calendar permission

In the sandbox: Deleting a share that no longer exists also returns 200, on every provider.

Sends the request to your sandbox, never to live data.

Path parameters

  • Name
    calendarRef
    Type
    string
    Required
    required
    Description

    The calendar ID returned by the provider, or primary for the account's primary calendar.

  • Name
    permissionId
    Type
    string
    Required
    required
    Description

Query parameters

  • Name
    accountId
    Type
    string
    Description

    The accountId of the connected account. Required here or in the request body of a write.

Headers

  • Name
    Idempotency-Key
    Type
    string
    Description

    A unique key that makes the request safe to retry. A retry with the same key returns the original response and does not make the change twice. Keys are kept for 24 hours.

Errors

Request

DELETE
/v2/calendars/{calendarRef}/permissions/{permissionId}
curl -X DELETE 'https://api.pyas.io/v2/calendars/primary/permissions/user%3Aassistant@example.com?accountId=sbx_fda58c5980_google' \  -H "x-api-key: $PYAS_API_KEY"

Response

200 OK
{  "success": true,  "data": null,  "provider": "google",  "traceId": "trc_5f2a9c1e7b3d4a6f8e0c2b1d",  "meta": {}}