# Calendar connections

Manage calendar provider connections for syncing events and enabling auto-join.

List all connected calendar providers for the authenticated user, including sync status and event counts.

## Returns

Returns a list of calendar connection objects.

### Calendar Connection Object

| Field | Type | Description |
|  --- | --- | --- |
| `credential_id` | string | Unique credential ID |
| `provider` | string | Calendar provider (`google_calendar`, `outlook_calendar`, `zoom`, `apple_calendar`) |
| `account_email` | string or null | Connected account email |
| `is_active` | boolean | Whether the connection is active |
| `last_sync_at` | string or null | Last successful sync time (ISO 8601) |
| `event_count` | integer | Number of synced events from this connection |


Request

```bash cURL
curl -s -X GET "https://api.aitronos.com/v1/meeting-buddy/calendar/connections" \
  -H "Authorization: Bearer $ACCESS_TOKEN" | python3 -m json.tool
```


```python Python SDK
from aitronos import Aitronos

client = Aitronos(api_key="your-api-key")

result = client.meeting_buddy.calendar.list_connections()
for conn in result.connections:
    print(f"{conn.provider}: {conn.account_email} ({conn.event_count} events)")
```


```python Python
import os
import requests

access_token = os.environ["ACCESS_TOKEN"]

url = "https://api.aitronos.com/v1/meeting-buddy/calendar/connections"
headers = {"Authorization": f"Bearer {access_token}"}

response = requests.get(url, headers=headers)
data = response.json()
for conn in data["connections"]:
    print(f"{conn['provider']}: {conn['account_email']}")
```


```javascript JavaScript
const accessToken = process.env.ACCESS_TOKEN;

const response = await fetch(
  'https://api.aitronos.com/v1/meeting-buddy/calendar/connections',
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
    },
  }
);

const data = await response.json();
data.connections.forEach(conn => {
  console.log(`${conn.provider}: ${conn.account_email}`);
});
```

Response

```json 200 OK
{
  "connections": [
    {
      "credential_id": "utcred_abc123",
      "provider": "google_calendar",
      "account_email": "user@gmail.com",
      "is_active": true,
      "last_sync_at": "2026-03-03T06:00:00Z",
      "event_count": 42
    },
    {
      "credential_id": "utcred_def456",
      "provider": "outlook_calendar",
      "account_email": "user@company.com",
      "is_active": true,
      "last_sync_at": "2026-03-03T06:00:00Z",
      "event_count": 15
    }
  ]
}
```

## Connect a calendar

Connect a new calendar provider. For OAuth-based providers (Google Calendar, Outlook Calendar, Zoom), this returns an authorization URL to complete the OAuth flow. For Apple Calendar, provide credentials directly.

#### Request Body

**`provider`** string required

Calendar provider to connect. Valid values: `google_calendar`, `outlook_calendar`, `zoom`, `apple_calendar`.

**`credentials`** object optional

Required for Apple Calendar. Must contain `apple_id` and `app_specific_password`.

## Returns

For OAuth providers, returns an authorization URL and state token. For Apple Calendar, returns the created connection object.

Request

```bash cURL (OAuth)
curl -s -X POST "https://api.aitronos.com/v1/meeting-buddy/calendar/connections" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider": "google_calendar"}' | python3 -m json.tool
```


```bash cURL (Apple)
curl -s -X POST "https://api.aitronos.com/v1/meeting-buddy/calendar/connections" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider": "apple_calendar", "credentials": {"apple_id": "user@icloud.com", "app_specific_password": "xxxx-xxxx-xxxx-xxxx"}}' | python3 -m json.tool
```


```python Python SDK
from aitronos import Aitronos

client = Aitronos(api_key="your-api-key")

# OAuth provider
result = client.meeting_buddy.calendar.connect(
    provider="google_calendar",
)
print(f"Authorize at: {result.authorization_url}")

# Apple Calendar
result = client.meeting_buddy.calendar.connect(
    provider="apple_calendar",
    credentials={
        "apple_id": "user@icloud.com",
        "app_specific_password": "xxxx-xxxx-xxxx-xxxx",
    },
)
print(f"Connected: {result.credential_id}")
```


```python Python
import os
import requests

access_token = os.environ["ACCESS_TOKEN"]

url = "https://api.aitronos.com/v1/meeting-buddy/calendar/connections"
headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json",
}

response = requests.post(url, headers=headers, json={"provider": "google_calendar"})
data = response.json()
print(f"Authorize at: {data['authorization_url']}")
```


```javascript JavaScript
const accessToken = process.env.ACCESS_TOKEN;

const response = await fetch(
  'https://api.aitronos.com/v1/meeting-buddy/calendar/connections',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ provider: 'google_calendar' }),
  }
);

const data = await response.json();
console.log(`Authorize at: ${data.authorization_url}`);
```

Response

```json 200 OK (OAuth)
{
  "authorization_url": "https://accounts.google.com/o/oauth2/auth?state=abc123&...",
  "state": "abc123def456"
}
```


```json 200 OK (Apple Calendar)
{
  "credential_id": "utcred_xyz789",
  "provider": "apple_calendar",
  "account_email": "user@icloud.com",
  "is_active": true,
  "last_sync_at": null,
  "event_count": 0
}
```


```json 409 Conflict
{
  "success": false,
  "error": {
    "code": "CALENDAR_ALREADY_CONNECTED",
    "message": "This calendar provider is already connected.",
    "system_message": "Calendar provider 'google_calendar' is already connected",
    "type": "client_error",
    "status": 409,
    "details": {
      "provider": "google_calendar"
    },
    "trace_id": "abc-123-def",
    "timestamp": "2026-03-03T10:00:00Z"
  }
}
```


```json 422 Validation Error
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is invalid.",
    "system_message": "Invalid provider. Must be one of: apple_calendar, google_calendar, outlook_calendar, zoom",
    "type": "client_error",
    "status": 422,
    "details": {
      "provider": "invalid_provider"
    },
    "trace_id": "abc-123-def",
    "timestamp": "2026-03-03T10:00:00Z"
  }
}
```

## Disconnect a calendar

Disconnect a calendar provider and remove all associated synced events.

#### Path Parameters

**`credential_id`** string required

The credential ID of the calendar connection to disconnect.

## Returns

Returns no content on success (204).

Request

```bash cURL
curl -s -X DELETE "https://api.aitronos.com/v1/meeting-buddy/calendar/connections/utcred_abc123" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```


```python Python SDK
from aitronos import Aitronos

client = Aitronos(api_key="your-api-key")

client.meeting_buddy.calendar.disconnect(
    credential_id="utcred_abc123",
)
print("Calendar disconnected")
```


```python Python
import os
import requests

access_token = os.environ["ACCESS_TOKEN"]
credential_id = "utcred_abc123"

url = f"https://api.aitronos.com/v1/meeting-buddy/calendar/connections/{credential_id}"
headers = {"Authorization": f"Bearer {access_token}"}

response = requests.delete(url, headers=headers)
assert response.status_code == 204
```


```javascript JavaScript
const accessToken = process.env.ACCESS_TOKEN;
const credentialId = 'utcred_abc123';

const response = await fetch(
  `https://api.aitronos.com/v1/meeting-buddy/calendar/connections/${credentialId}`,
  {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
    },
  }
);

console.log(response.status); // 204
```

Response

```text 204 No Content
(empty response body)
```


```json 404 Not Found
{
  "success": false,
  "error": {
    "code": "CALENDAR_CONNECTION_NOT_FOUND",
    "message": "The requested calendar connection could not be found.",
    "system_message": "Calendar connection not found",
    "type": "client_error",
    "status": 404,
    "details": {
      "credential_id": "utcred_nonexistent"
    },
    "trace_id": "abc-123-def",
    "timestamp": "2026-03-03T10:00:00Z"
  }
}
```

## Related Resources

- [Calendar Events](/docs/api-reference/meeting-buddy/calendar-events)
- [Calendar Sync](/docs/api-reference/meeting-buddy/calendar-sync)
- [Auto-Join Rules](/docs/api-reference/meeting-buddy/auto-join-rules)
- [Start Session](/docs/api-reference/meeting-buddy/start-session)