# Calendars

## Get All Calendars

<mark style="color:blue;">`GET`</mark> `https://api.pyas.io/microsoft/calendars`

Gets all calendars that a user has access to.

#### Query Parameters

| Name                                        | Type   | Description                                                                       |
| ------------------------------------------- | ------ | --------------------------------------------------------------------------------- |
| accountId<mark style="color:red;">\*</mark> | String | The user's Pyas account id. This is returned when you connect an account to Pyas. |

#### Headers

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| x-api-key<mark style="color:red;">\*</mark> | String | API key     |

{% tabs %}
{% tab title="200: OK Successfully retrieved list of calendars" %}

```json
{
    "success": true,
    "data": {
        "calendars": [
            {
                "id": "some-calendar-id",
                "name": "Calendar",
                "color": "auto",
                "hexColor": "",
                "isDefaultCalendar": true,
                "changeKey": "some-key",
                "canShare": true,
                "canViewPrivateItems": true,
                "canEdit": true,
                "allowedOnlineMeetingProviders": [
                    "skypeForConsumer"
                ],
                "defaultOnlineMeetingProvider": "skypeForConsumer",
                "isTallyingResponses": true,
                "isRemovable": false,
                "owner": {
                    "name": "Jane Doe",
                    "address": "outlook_some-id@outlook.com"
                }
            }
        ]
    }
}
```

{% endtab %}

{% tab title="401: Unauthorized Invalid/missing API key" %}

```json
{
    "error": "Unauthorized. Invalid API key."
}
```

{% endtab %}

{% tab title="400: Bad Request Missing account id" %}

```json
{
    "errors": [
        {
            "msg": "an account id is required.",
            "param": "accountId",
            "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 %}
{% endtabs %}

## Get Calendar by ID

<mark style="color:blue;">`GET`</mark> `https://api.pyas.io/microsoft/calendars/{id}`

Gets a calendar by id

#### Path Parameters

| Name                                   | Type   | Description                        |
| -------------------------------------- | ------ | ---------------------------------- |
| {id}<mark style="color:red;">\*</mark> | String | The id of the calendar to retrieve |

#### Query Parameters

| Name                                        | Type   | Description                                                                      |
| ------------------------------------------- | ------ | -------------------------------------------------------------------------------- |
| accountId<mark style="color:red;">\*</mark> | String | The user's Pyas account id. This is returned when you connect an account to Pyas |

#### Headers

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| x-api-key<mark style="color:red;">\*</mark> | String | API key     |

{% tabs %}
{% tab title="200: OK Successfully retrieved the calendar" %}

```json
{
    "success": true,
    "calendar": {
        "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('outlook_some-id@outlook.com')/calendars/$entity",
        "id": "some-calendar-id",
        "name": "Calendar",
        "color": "auto",
        "hexColor": "",
        "isDefaultCalendar": true,
        "changeKey": "some-key",
        "canShare": true,
        "canViewPrivateItems": true,
        "canEdit": true,
        "allowedOnlineMeetingProviders": [
            "skypeForConsumer"
        ],
        "defaultOnlineMeetingProvider": "skypeForConsumer",
        "isTallyingResponses": true,
        "isRemovable": false,
        "owner": {
            "name": "Jane Doe",
            "address": "outlook_some-id@outlook.com"
        }
    }
}
```

{% 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="401: Unauthorized Invalid/missing API key" %}

```json
{
    "error": "Unauthorized. Invalid API key."
}
```

{% endtab %}

{% tab title="400: Bad Request Missing account id" %}

```json
{
    "errors": [
        {
            "msg": "an account id is required.",
            "param": "accountId",
            "location": "query"
        },
        {
            "msg": "account id must be a string",
            "param": "accountId",
            "location": "query"
        }
    ]
}
```

{% endtab %}

{% tab title="404: Not Found Calendar Not Found" %}

```json
{
    "success": false,
    "error": "Not Found",
    "code": 404
}
```

{% 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/microsoft-outlook/calendars.md?ask=<question>
```

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.