### Install Node.js SDK

Source: https://docs.onecalunified.com/quickstart

Install the official Node.js SDK for easier interaction with the OneCal Unified API. This is optional.

```bash
npm install @onecal/unified-calendar-api-node-sdk
```

--------------------------------

### Get Calendar API Response

Source: https://docs.onecalunified.com/calendars

Example JSON response for a single calendar resource.

```JSON
{
  "id": "calendar_1",
  "name": "Shared Calendar",
  "readOnly": false,
  "hexColor": "#7bd148",
  "inviteEmail": "shared_calendar_1@group.calendar.google.com",
  "isShared": true,
  "timeZone": "Europe/Tirane",
  "allowedOnlineMeetingProviders": ["hangoutsMeet"]
},
```

--------------------------------

### Retrieve End User Account Details

Source: https://docs.onecalunified.com/end-user-accounts

Example response structure for listing end user accounts.

```json
{
  "data": [
    {
      "id": "user_account_1",
      "createdAt": "2025-09-10T13:22:35.983Z",
      "updatedAt": "2025-09-10T13:22:35.983Z",
      "email": "johndoe@example.com",
      "externalId": "",
      "authorizedScopes": [
        "openid",
        "email",
        "profile",
        "User.Read",
        "Calendars.ReadWrite"
      ],
      "providerAccountId": "johndoe_provider_account_id",
      "providerId": "provider_1",
      "applicationId": "application_1",
      "status": "ACTIVE",
      "providerType": "MICROSOFT"
    },
    {
      "id": "user_account_2",
      "createdAt": "2025-09-08T15:33:20.209Z",
      "updatedAt": "2025-09-08T15:33:20.209Z",
      "email": "johndoe@example.com",
      "externalId": "",
      "authorizedScopes": [
        "email",
        "profile",
        "https://www.googleapis.com/auth/calendar.events",
        "https://www.googleapis.com/auth/calendar",
        "https://www.googleapis.com/auth/userinfo.profile",
        "https://www.googleapis.com/auth/userinfo.email",
        "openid"
      ],
      "providerAccountId": "johndoe_provider_account_id",
      "providerId": "provider_2",
      "applicationId": "application_1",
      "status": "ACTIVE",
      "providerType": "GOOGLE"
    },
    {
      "id": "user_account_3",
      "createdAt": "2025-09-12T10:15:00.000Z",
      "updatedAt": "2025-09-12T10:15:00.000Z",
      "email": "johndoe@icloud.com",
      "externalId": "",
      "authorizedScopes": [],
      "providerAccountId": null,
      "providerId": "provider_3",
      "applicationId": "application_1",
      "status": "ACTIVE",
      "providerType": "APPLE"
    }
  ],
  "nextPageToken": null
}
```

--------------------------------

### Calendar Response Object

Source: https://docs.onecalunified.com/calendars

Example JSON response representing a calendar resource.

```json
{
  "id": "calendar_1",
  "name": "Created from API",
  "readOnly": false,
  "inviteEmail": "ff0d6a10e05abaed040a36fc68270bc6b0001b9dea9971162be8df0d5d5721312@group.calendar.google.com",
  "isShared": false,
  "timeZone": "America/New_York",
  "allowedOnlineMeetingProviders": [
      "hangoutsMeet"
  ]
}
```

--------------------------------

### Create a Calendar Subscription Response

Source: https://docs.onecalunified.com/webhooks

Example JSON response containing the subscription ID and endpoint secret.

```JSON
{
  "webhookSubscriptionId": "subscription_id",
  "endpointSecret": "endpoint_secret"
}
```

--------------------------------

### End User Account Creation Response

Source: https://docs.onecalunified.com/end-user-accounts

This is an example of a successful response when creating or updating an end user account.

```json
{
  "id": "user_account_1",
  "createdAt": "2025-09-10T13:22:35.983Z",
  "updatedAt": "2025-09-10T13:22:35.983Z",
  "email": "johndoe@example.com",
  "externalId": "1234567890",
  "authorizedScopes": [
    "openid",
    "email",
    "profile",
    "User.Read",
    "Calendars.ReadWrite"
  ],
  "providerAccountId": "johndoe_provider_account_id",
  "providerId": "provider_1",
  "applicationId": "application_1",
  "status": "ACTIVE",
  "providerType": "MICROSOFT"
}
```

--------------------------------

### List Calendar Subscriptions Response

Source: https://docs.onecalunified.com/webhooks

Example JSON response for a successful list calendar subscriptions request.

```JSON
{
  "data": [
    {
      "id": "sub_abc123",
      "provider": "GOOGLE",
      "url": "https://yourapp.com/webhooks/calendar",
      "calendarId": "primary",
      "expiration": "2025-01-15T00:00:00.000Z",
      "subscriptionId": "subscription_id",
      "resourceId": "resource_id",
      "endUserAccountId": "user_account_1",
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z"
    }
  ],
  "nextPageToken": null
}
```

--------------------------------

### Get Calendar Event Response

Source: https://docs.onecalunified.com/calendar-events

Example JSON response structure for a calendar event object.

```json
{
  "id": "4t2rmfbo4ohlla0jj9vjlhfrv3",
  "title": "Recurring Event",
  "etag": "\"3510023641690558\"",
  "createdAt": "2025-08-12T15:16:48.000Z",
  "updatedAt": "2025-08-12T15:17:00.845Z",
  "start": {
    "dateTime": "2025-08-13T00:00:00",
    "timeZone": "Etc/UTC"
  },
  "end": {
    "dateTime": "2025-08-14T00:00:00",
    "timeZone": "Etc/UTC"
  },
  "isAllDay": true,
  "isRecurring": true,
  "isException": false,
  "isCancelled": false,
  "recurrence": ["RRULE:FREQ=WEEKLY;BYDAY=WE"],
  "webLink": "https://www.google.com/calendar/event?eid=1234567890",
  "iCalUid": "4t2rmfbo4ohlla0jj9vjlhfrv3@google.com",
  "transparency": "transparent",
  "eventType": "default",
  "organizer": {
    "name": "Organizer",
    "email": "ddc4phg9nsqnf2k5t6dfbja0@group.calendar.google.com",
    "isSelf": true
  },
  "creator": {
    "email": "creator@example.com"
  },
  "reminders": {
    "useDefault": false
  }
}
```

--------------------------------

### Make GET Request to End User Accounts

Source: https://docs.onecalunified.com/quickstart

Send a GET request to the /v1/endUserAccounts endpoint to retrieve a list of end user accounts authorized to your application. Replace {API KEY} with your actual API key.

```curl
curl -G https://api.onecalunified.com/api/v1/endUserAccounts \
  -H "x-api-key: {API KEY}"
```

--------------------------------

### Get Calendar Event Request

Source: https://docs.onecalunified.com/calendar-events

Retrieves details for a specific calendar event using a GET request with an API key header.

```bash
curl -X GET https://api.onecalunified.com/api/v1/events/:endUserAccountId/:calendarId/:eventId \
  -H "x-api-key: {apiKey}"
```

--------------------------------

### End User Account Deletion Response

Source: https://docs.onecalunified.com/end-user-accounts

This is an example of a successful response when deleting an end user account.

```json
{
  "message": "End User Account deleted",
  "ok": true
}
```

--------------------------------

### List Calendars API Response

Source: https://docs.onecalunified.com/calendars

Example JSON response containing a list of calendar objects and a sync token.

```JSON
{
  "data": [
    {
      "id": "shared_calendar_1@group.calendar.google.com",
      "name": "Shared Calendar",
      "readOnly": false,
      "hexColor": "#7bd148",
      "inviteEmail": "shared_calendar_1@group.calendar.google.com",
      "isShared": true,
      "timeZone": "Europe/Tirane",
      "allowedOnlineMeetingProviders": ["hangoutsMeet"]
    },
    {
      "id": "en.generic#holiday@group.v.calendar.google.com",
      "name": "Holidays",
      "readOnly": true,
      "hexColor": "#9a9cff",
      "inviteEmail": "en.generic#holiday@group.v.calendar.google.com",
      "isShared": true,
      "timeZone": "Europe/Tirane",
      "allowedOnlineMeetingProviders": ["hangoutsMeet"]
    },
    {
      "id": "johndoe@example.com",
      "name": "johndoe@example.com",
      "readOnly": false,
      "hexColor": "#0e61b9",
      "inviteEmail": "johndoe@example.com",
      "isPrimary": true,
      "isShared": false,
      "timeZone": "Europe/Tirane",
      "allowedOnlineMeetingProviders": ["hangoutsMeet"]
    }
  ],
  "nextSyncToken": "example_sync_token"
}
```

--------------------------------

### Get End User Account by ID

Source: https://docs.onecalunified.com/end-user-accounts

Retrieve details for a specific end user account using cURL.

```bash
curl -X GET https://api.onecalunified.com/api/v1/endUserAccounts/user_account_1 \
  -H "x-api-key: {apiKey}"
```

```json
{
  "id": "user_account_1",
  "createdAt": "2025-09-10T13:22:35.983Z",
  "updatedAt": "2025-09-10T13:22:35.983Z",
  "email": "johndoe@example.com",
  "externalId": "",
  "authorizedScopes": [
    "openid",
    "email",
    "profile",
    "User.Read",
    "Calendars.ReadWrite"
  ],
  "providerAccountId": "johndoe_provider_account_id",
  "providerId": "provider_1",
  "applicationId": "application_1",
  "status": "ACTIVE",
  "providerType": "MICROSOFT"
}
```

--------------------------------

### Create a New Calendar Event

Source: https://docs.onecalunified.com/calendar-events

This endpoint creates a new calendar event. The request body should include `title` and `start` properties, along with their respective values. Authentication is handled via an API key.

```cURL
curl https://api.onecalunified.com/api/v1/events/:endUserAccountId/:calendarId \
  -H "x-api-key: {apiKey}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"title": "Created from API","start": {"dateTime": "2025-08-13T00:00:00", "timeZone": "Etc/UTC"},"end": {"dateTime": "2025-08-14T00:00:00", "timeZone": "Etc/UTC"}}'
```

--------------------------------

### Free Busy API Response Format

Source: https://docs.onecalunified.com/free-busy

Example JSON response structure containing busy slots for a calendar.

```JSON
  [
    {
      "calendarId": "shared_calendar_1@group.calendar.google.com",
      "busySlots": [
        {
          "start": {
            "dateTime": "2025-08-13T02:00:00+02:00",
            "timeZone": "Europe/Rome"
          },
          "end": {
            "dateTime": "2025-08-14T02:00:00+02:00",
            "timeZone": "Europe/Rome"
          }
        }
      ]
    }
  ]
```

--------------------------------

### Get Calendar

Source: https://docs.onecalunified.com/calendars

Retrieves the details of a specific Calendar using its unique identifier.

```APIDOC
## GET /v1/calendars/:endUserAccountId/:calendarId

### Description
This endpoint returns the details of a specific Calendar.

### Method
GET

### Endpoint
/v1/calendars/:endUserAccountId/:calendarId

### Path Parameters
- **calendarId** (string) - Required - The unique identifier of the Calendar to retrieve.

### Request Example
```curl
curl -X GET https://api.onecalunified.com/api/v1/calendars/user_account_1/calendar_1 \
  -H "x-api-key: {apiKey}"
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier of the calendar.
- **name** (string) - Display name of the calendar.
- **readOnly** (boolean) - Indicates whether the calendar is a read-only calendar.
- **hexColor** (string) - Hexadecimal color code representing the calendar's color.
- **inviteEmail** (string) - Email address used for calendar invitations.
- **isShared** (boolean) - Indicates whether the calendar is a shared calendar.
- **timeZone** (string) - Time zone associated with the calendar.
- **allowedOnlineMeetingProviders** (string[]) - List of allowed online meeting providers.

#### Response Example
```json
{
  "id": "calendar_1",
  "name": "Shared Calendar",
  "readOnly": false,
  "hexColor": "#7bd148",
  "inviteEmail": "shared_calendar_1@group.calendar.google.com",
  "isShared": true,
  "timeZone": "Europe/Tirane",
  "allowedOnlineMeetingProviders": ["hangoutsMeet"]
}
```
```

--------------------------------

### GET /v1/endUserAccounts/:id/credentials

Source: https://docs.onecalunified.com/end-user-accounts

Retrieves the credentials of a specific End User Account.

```APIDOC
## Get End User Account Credentials

This endpoint returns the credentials of a specific End User Account associated with your application. This is useful if you need to retrieve the access token or refresh token of an end user account, so you can perform operations on your end.
For Apple Calendar accounts, the credentials response will not include `accessToken` or `refreshToken`. Apple Calendar uses CalDAV with credentials managed by OneCal Unified.

### Path parameters

Name
  `id`

Type
  string

Description
  The unique identifier of the End User Account whose credentials you want to retrieve.

### Request

```curl
curl -X GET https://api.onecalunified.com/api/v1/endUserAccounts/user_account_1/credentials \
  -H "x-api-key: {apiKey}"
```

### Response

#### Success Response (200)

- **id** (string) - The unique identifier of the credentials.
- **endUserAccountId** (string) - The ID of the associated end user account.
- **accessToken** (string) - The access token for the provider.
- **refreshToken** (string) - The refresh token for the provider.
- **expiresAt** (string) - The expiration timestamp of the access token.
- **status** (string) - The status of the credentials.
- **createdAt** (string) - The timestamp when the credentials were created.
- **updatedAt** (string) - The timestamp when the credentials were last updated.

```json
{
    "id": "cmgfcdwez001joo2gpvl4dbmn",
    "endUserAccountId": "cmgfcdwer001hoo2g6wgyrqqp",
    "accessToken": "token",
    "refreshToken": "token",
    "expiresAt": "2025-10-14T12:02:05.334Z",
    "status": "ACTIVE",
    "createdAt": "2025-10-06T16:25:24.059Z",
    "updatedAt": "2025-10-14T11:02:06.335Z"
}
```
```

--------------------------------

### GET /v1/endUserAccounts/:id

Source: https://docs.onecalunified.com/end-user-accounts

Retrieves the details of a specific End User Account.

```APIDOC
## Get End User Account

This endpoint returns the details of a specific End User Account associated with your application.

### Path parameters

Name
  `id`

Type
  string

Description
  The unique identifier of the End User Account to retrieve.

### Request

```curl
curl -X GET https://api.onecalunified.com/api/v1/endUserAccounts/user_account_1 \
  -H "x-api-key: {apiKey}"
```

### Response

#### Success Response (200)

- **id** (string) - The unique identifier of the end user account.
- **createdAt** (string) - The timestamp when the end user account was created.
- **updatedAt** (string) - The timestamp when the end user account was last updated.
- **email** (string) - The email address of the end user.
- **externalId** (string) - An external identifier for the user.
- **authorizedScopes** (array) - A list of authorized scopes for the user.
- **providerAccountId** (string) - The provider's account ID for the user.
- **providerId** (string) - The unique identifier of the provider.
- **applicationId** (string) - The unique identifier of the application.
- **status** (string) - The status of the end user account (e.g., ACTIVE).
- **providerType** (string) - The type of the provider (e.g., MICROSOFT, GOOGLE, APPLE).

```json
{
  "id": "user_account_1",
  "createdAt": "2025-09-10T13:22:35.983Z",
  "updatedAt": "2025-09-10T13:22:35.983Z",
  "email": "johndoe@example.com",
  "externalId": "",
  "authorizedScopes": [
    "openid",
    "email",
    "profile",
    "User.Read",
    "Calendars.ReadWrite"
  ],
  "providerAccountId": "johndoe_provider_account_id",
  "providerId": "provider_1",
  "applicationId": "application_1",
  "status": "ACTIVE",
  "providerType": "MICROSOFT"
}
```
```

--------------------------------

### Get End User Account Credentials

Source: https://docs.onecalunified.com/end-user-accounts

Retrieve access and refresh tokens for an end user account. Note that Apple Calendar accounts do not return tokens.

```bash
curl -X GET https://api.onecalunified.com/api/v1/endUserAccounts/user_account_1/credentials \
  -H "x-api-key: {apiKey}"
```

```json
{
    "id": "cmgfcdwez001joo2gpvl4dbmn",
    "endUserAccountId": "cmgfcdwer001hoo2g6wgyrqqp",
    "accessToken": "token",
    "refreshToken": "token",
    "expiresAt": "2025-10-14T12:02:05.334Z",
    "status": "ACTIVE",
    "createdAt": "2025-10-06T16:25:24.059Z",
    "updatedAt": "2025-10-14T11:02:06.335Z"
}
```

--------------------------------

### POST /v1/events/:endUserAccountId/:calendarId

Source: https://docs.onecalunified.com/calendar-events

Creates a new Calendar Event in the specified Calendar. Requires title and start time.

```APIDOC
## POST /v1/events/:endUserAccountId/:calendarId

### Description
Creates a new Calendar Event in the specified Calendar. Requires title and start time.

### Method
POST

### Endpoint
/v1/events/:endUserAccountId/:calendarId

### Parameters
#### Path Parameters
- **endUserAccountId** (string) - Required - The unique identifier of the End User Account.
- **calendarId** (string) - Required - The unique identifier of the Calendar.

#### Request Body
- **title** (string) - Required - The title of the event.
- **start** (object) - Required - The start time of the event. Must include `dateTime` and optionally `timeZone`.
  - **dateTime** (string) - Required - ISO 8601 date-time.
  - **timeZone** (string) - Optional - Time zone of the event.
- **end** (object) - Optional - The end time of the event. Must include `dateTime` and optionally `timeZone`.
  - **dateTime** (string) - Required - ISO 8601 date-time.
  - **timeZone** (string) - Optional - Time zone of the event.

### Request Example
```curl
curl https://api.onecalunified.com/api/v1/events/:endUserAccountId/:calendarId \
  -H "x-api-key: {apiKey}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"title": "Created from API","start": {"dateTime": "2025-08-13T00:00:00", "timeZone": "Etc/UTC"},"end": {"dateTime": "2025-08-14T00:00:00", "timeZone": "Etc/UTC"}}'
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier of the created event.
- **title** (string) - Title of the event.
- **etag** (string) - ETag of the event.
- **createdAt** (string) - Timestamp when the event was created.
- **updatedAt** (string) - Timestamp when the event was last updated.
- **start** (object) - Start time details.
- **end** (object) - End time details.
- **isAllDay** (boolean) - Whether the event is an all-day event.
- **isRecurring** (boolean) - Whether the event is recurring.
- **isException** (boolean) - Whether the event is an exception to a recurrence.
- **isCancelled** (boolean) - Whether the event is cancelled.
- **recurrence** (null) - Recurrence rules (if any).
- **webLink** (string) - Link to the event on the web.
- **iCalUid** (string) - iCal unique identifier.
- **eventType** (string) - Type of the event.
- **organizer** (object) - Organizer details.
- **creator** (object) - Creator details.
- **reminders** (object) - Reminder settings.

#### Response Example
```json
{
  "id": "kv8tte1cge479ivm113i66bsjg",
  "title": "Created from API",
  "etag": "\"3519875915275934\"",
  "createdAt": "2025-10-08T15:39:17.000Z",
  "updatedAt": "2025-10-08T15:39:17.637Z",
  "start": {
    "dateTime": "2025-08-13T02:00:00+02:00",
    "timeZone": "Etc/UTC"
  },
  "end": {
    "dateTime": "2025-08-14T02:00:00+02:00",
    "timeZone": "Etc/UTC"
  },
  "isAllDay": false,
  "isRecurring": false,
  "isException": false,
  "isCancelled": false,
  "recurrence": null,
  "webLink": "https://www.google.com/calendar/event?eid=1234567890",
  "iCalUid": "kv8tte1cge479ivm113i66bsjg@google.com",
  "eventType": "default",
  "organizer": {
    "name": "Organizer",
    "email": "ddc4phg9nsqnf2k5t6dfbja0@group.calendar.google.com",
    "isSelf": true
  },
  "creator": {
    "email": "creator@example.com"
  },
  "reminders": {
    "useDefault": true
  }
}

```

--------------------------------

### Get Calendar API Request

Source: https://docs.onecalunified.com/calendars

Retrieves details for a specific calendar by its ID.

```cURL
curl -X GET https://api.onecalunified.com/api/v1/calendars/user_account_1/calendar_1 \
  -H "x-api-key: {apiKey}"
```

--------------------------------

### GET /v1/calendarSubscriptions/:endUserAccountId

Source: https://docs.onecalunified.com/webhooks

Retrieves a paginated list of all webhook subscriptions for a specific End User Account.

```APIDOC
## GET /v1/calendarSubscriptions/:endUserAccountId

### Description
This endpoint retrieves a paginated list of all webhook subscriptions for a specific End User Account.

### Method
GET

### Endpoint
`/v1/calendarSubscriptions/:endUserAccountId`

### Parameters
#### Path Parameters
* **endUserAccountId** (string) - Required - The unique identifier of the End User Account to retrieve subscriptions for.

#### Query Parameters
* **pageToken** (string) - Optional - Token for pagination to retrieve the next page of results.
* **limit** (number) - Optional - Maximum number of subscriptions to return per page.

### Request Example
```curl
curl -X GET https://api.onecalunified.com/api/v1/calendarSubscriptions/:endUserAccountId \
  -H "x-api-key: {apiKey}"
```

### Response
#### Success Response (200)
* **data** (array) - List of webhook subscriptions.
  * **id** (string) - Subscription ID.
  * **provider** (string) - Calendar provider (e.g., GOOGLE).
  * **url** (string) - Webhook URL.
  * **calendarId** (string) - ID of the subscribed calendar.
  * **expiration** (string) - Subscription expiration date.
  * **subscriptionId** (string) - Provider-specific subscription ID.
  * **resourceId** (string) - Provider-specific resource ID.
  * **endUserAccountId** (string) - The associated End User Account ID.
  * **createdAt** (string) - Timestamp when the subscription was created.
  * **updatedAt** (string) - Timestamp when the subscription was last updated.
* **nextPageToken** (string) - Token for the next page of results, or null if no more pages.

#### Response Example
```json
{
  "data": [
    {
      "id": "sub_abc123",
      "provider": "GOOGLE",
      "url": "https://yourapp.com/webhooks/calendar",
      "calendarId": "primary",
      "expiration": "2025-01-15T00:00:00.000Z",
      "subscriptionId": "subscription_id",
      "resourceId": "resource_id",
      "endUserAccountId": "user_account_1",
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-01-01T00:00:00.000Z"
    }
  ],
  "nextPageToken": null
}
```
```

--------------------------------

### GET /v1/endUserAccounts

Source: https://docs.onecalunified.com/end-user-accounts

Retrieves a paginated list of all End User Accounts associated with your application, with optional filtering by search term or status.

```APIDOC
## GET /v1/endUserAccounts

### Description
Retrieves a paginated list of all End User Accounts associated with your application.

### Method
GET

### Endpoint
/v1/endUserAccounts

### Parameters
#### Query Parameters
- **search** (string) - Optional - Filter end user accounts by email or external ID.
- **statusFilter** (enum) - Optional - Filter end user accounts by status. Possible values: `active`, `expired`.

### Request Example
curl -X GET https://api.onecalunified.com/api/v1/endUserAccounts \
  -H "x-api-key: {apiKey}"
```

--------------------------------

### GET /api/v1/endUserAccounts

Source: https://docs.onecalunified.com/pagination

Retrieves a paginated list of end user accounts. Supports limiting the number of results and using page tokens to navigate through the collection.

```APIDOC
## GET /api/v1/endUserAccounts

### Description
Retrieves a list of end user accounts with support for pagination.

### Method
GET

### Endpoint
/api/v1/endUserAccounts

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The number of items to return per page.
- **pageToken** (string) - Optional - The page token to return the next set of results.

### Request Example
curl -G https://api.onecalunified.com/api/v1/endUserAccounts?limit=10&pageToken=123abcd \
  -H "x-api-key: {API KEY}"

### Response
#### Success Response (200)
- **data** (array) - The list of end user account objects.
- **nextPageToken** (string|null) - The token to retrieve the next page, or null if no more pages exist.

#### Response Example
{
  "data": [
    {
      "id": "example-id-1",
      "email": "example-email-1@example.com",
      "status": "ACTIVE",
      "providerType": "MICROSOFT"
    }
  ],
  "nextPageToken": null
}
```

--------------------------------

### Initialize Node.js SDK Client

Source: https://docs.onecalunified.com/quickstart

Initialize the UnifiedCalendarApi client with your API key. Ensure your API key is kept secure and not exposed in client-side code.

```typescript
import { UnifiedCalendarApi } from '@onecal/unified-calendar-api-node-sdk'

const client = new UnifiedCalendarApi({
  apiKey: 'your-api-key-here',
})
```

--------------------------------

### Authenticate API requests with an API key

Source: https://docs.onecalunified.com/authentication

Pass your API key in the x-api-key header for all requests to the Unified Calendar API.

```bash
curl https://api.onecalunified.com/api/v1/endUserAccounts \
  -H "x-api-key: {API KEY}"
```

--------------------------------

### Connect to Apple Account via Basic Auth

Source: https://docs.onecalunified.com/authentication

Use this cURL command to connect an Apple account using basic authentication. Ensure you replace placeholders like {APP_ID}, {apiKey}, and provide the user's email and password.

```curl
curl -X POST https://api.onecalunified.com/api/v1/basicAuth/connect/{APP_ID}/apple \
  -H "x-api-key: {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@icloud.com", "password": "xxxx-xxxx-xxxx-xxxx"}'
```

--------------------------------

### Create Calendar

Source: https://docs.onecalunified.com/calendars

Creates a new Calendar under the specified End User Account. Requires calendar name and time zone.

```APIDOC
## POST /v1/calendars/:endUserAccountId

### Description
Creates a new Calendar under the specified End User Account.

### Method
POST

### Endpoint
/v1/calendars/:endUserAccountId

### Request Body
This endpoint accepts the same properties as the Calendar model except the properties marked as `Read-Only`.
- **name** (string) - Required - Display name of the calendar.
- **timeZone** (string) - Required - Time zone associated with the calendar.

### Request Example
```curl
curl https://api.onecalunified.com/api/v1/calendars/user_account_1 \
  -H "x-api-key: {apiKey}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"name": "Created from API", "timeZone": "America/New_York"}'
```
```

--------------------------------

### GET /v1/events/:endUserAccountId/:calendarId/:eventId/occurrences

Source: https://docs.onecalunified.com/calendar-events

Retrieves the individual occurrences of a recurring event.

```APIDOC
## GET /v1/events/:endUserAccountId/:calendarId/:eventId/occurrences

### Description
This endpoint returns the individual occurrences of a recurring event. It behaves similarly to the Get Calendar Events endpoint with the `expandRecurrences` query parameter set to `true`, but for a single event.

### Method
GET

### Endpoint
/v1/events/:endUserAccountId/:calendarId/:eventId/occurrences

### Parameters
#### Path Parameters
- **endUserAccountId** (string) - Required - The unique identifier of the End User Account.
- **calendarId** (string) - Required - The unique identifier of the Calendar.
- **eventId** (string) - Required - The unique identifier of the recurring Event.
```

--------------------------------

### Create a Calendar Subscription

Source: https://docs.onecalunified.com/webhooks

Creates a new webhook subscription for a specific calendar using a POST request.

```cURL
curl https://api.onecalunified.com/api/v1/calendarSubscriptions/:endUserAccountId \
  -H "x-api-key: {apiKey}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"calendarId": "primary", "webhookUrl": "https://yourapp.com/webhooks/calendar"}'
```

--------------------------------

### POST /v1/endUserAccounts

Source: https://docs.onecalunified.com/end-user-accounts

Creates or updates an End User Account.

```APIDOC
## Create or Update End User Account

An End User Account is automatically created when a user authenticates your application through the steps outlined in the End User Authentication guide. It is also possible to manually create an End User Account for a user by sending an API request. This is useful for when you want to sync your existing authorized users with OneCal Unified, or for when you want full control over the OAuth2 flow. This endpoint can also be used to update the credentials of an existing End User Account. To create or update an Apple Calendar End User Account, use the Apple Calendar Authentication endpoint instead of this endpoint.
```

--------------------------------

### Create or Update End User Account

Source: https://docs.onecalunified.com/end-user-accounts

Use this endpoint to create a new end user account or update an existing one. Requires email, providerType, and refreshToken. ExternalId is optional.

```cURL
curl https://api.onecalunified.com/api/v1/endUserAccounts \
  -H "x-api-key: {apiKey}" \
  -H "Content-Type: application/json" \
  -d '{"email": "johndoe@email.com", "externalId": "1234567890", "providerType": "MICROSOFT", "refreshToken": "refresh_token"}'
```

--------------------------------

### Create Calendar API Request

Source: https://docs.onecalunified.com/calendars

Creates a new calendar by sending a POST request with the calendar properties.

```cURL
curl https://api.onecalunified.com/api/v1/calendars/user_account_1 \
  -H "x-api-key: {apiKey}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"name": "Created from API", "timeZone": "America/New_York"}'
```

--------------------------------

### Request paginated data with cURL

Source: https://docs.onecalunified.com/pagination

Use the limit and pageToken query parameters to retrieve specific pages of data.

```bash
curl -G https://api.onecalunified.com/api/v1/endUserAccounts?limit=10&pageToken=123abcd \
  -H "x-api-key: {API KEY}"
```

--------------------------------

### GET /v1/events/:endUserAccountId/:calendarId/:eventId

Source: https://docs.onecalunified.com/calendar-events

Retrieves the details of a specific calendar event using the end user account, calendar, and event identifiers.

```APIDOC
## GET /v1/events/:endUserAccountId/:calendarId/:eventId

### Description
This endpoint returns the details of a specific Calendar Event.

### Method
GET

### Endpoint
/v1/events/:endUserAccountId/:calendarId/:eventId

### Parameters
#### Path Parameters
- **endUserAccountId** (string) - Required - The unique identifier of the End User Account to retrieve.
- **calendarId** (string) - Required - The unique identifier of the Calendar to retrieve.
- **eventId** (string) - Required - The unique identifier of the Event to retrieve.

### Response
#### Success Response (200)
- **id** (string) - Event identifier
- **title** (string) - Event title
- **start** (object) - Start date/time and timezone
- **end** (object) - End date/time and timezone
- **isRecurring** (boolean) - Whether the event is recurring

#### Response Example
{
  "id": "4t2rmfbo4ohlla0jj9vjlhfrv3",
  "title": "Recurring Event",
  "start": {
    "dateTime": "2025-08-13T00:00:00",
    "timeZone": "Etc/UTC"
  },
  "end": {
    "dateTime": "2025-08-14T00:00:00",
    "timeZone": "Etc/UTC"
  }
}
```

--------------------------------

### POST /v1/endUserAccounts

Source: https://docs.onecalunified.com/end-user-accounts

Creates or updates an End User Account by providing the user's email, provider type, and refresh token.

```APIDOC
## POST /v1/endUserAccounts

### Description
Creates or updates an End User Account for a specific provider.

### Method
POST

### Endpoint
/v1/endUserAccounts

### Parameters
#### Request Body
- **email** (string) - Required - The email address of End User Account you want to create or update.
- **externalId** (string) - Optional - Set or update the external ID of the End User Account.
- **providerType** (enum) - Required - The type of provider. Possible values: `GOOGLE`, `MICROSOFT`, `APPLE`.
- **refreshToken** (string) - Required - The refresh token received from the Provider. Required for `GOOGLE` and `MICROSOFT`.

### Request Example
{
  "email": "johndoe@email.com",
  "externalId": "1234567890",
  "providerType": "MICROSOFT",
  "refreshToken": "refresh_token"
}

### Response
#### Success Response (200)
- **id** (string) - Unique identifier of the account
- **createdAt** (string) - Creation timestamp
- **updatedAt** (string) - Last update timestamp
- **email** (string) - User email
- **externalId** (string) - External ID
- **authorizedScopes** (array) - List of authorized scopes
- **providerAccountId** (string) - Provider account ID
- **providerId** (string) - Provider ID
- **applicationId** (string) - Application ID
- **status** (string) - Account status
- **providerType** (string) - Provider type

#### Response Example
{
  "id": "user_account_1",
  "createdAt": "2025-09-10T13:22:35.983Z",
  "updatedAt": "2025-09-10T13:22:35.983Z",
  "email": "johndoe@example.com",
  "externalId": "1234567890",
  "authorizedScopes": ["openid", "email", "profile", "User.Read", "Calendars.ReadWrite"],
  "providerAccountId": "johndoe_provider_account_id",
  "providerId": "provider_1",
  "applicationId": "application_1",
  "status": "ACTIVE",
  "providerType": "MICROSOFT"
}
```

--------------------------------

### Generate OAuth URL using the SDK

Source: https://docs.onecalunified.com/authentication

Use the getOAuthUrl function to retrieve the authorization URL for Google or Microsoft providers.

```typescript
import { getOAuthUrl } from '@onecal/unified-calendar-api-node-sdk/oauth'

const googleUrl = getOAuthUrl('your-app-id', 'GOOGLE', {
  redirectUrl: 'https://your-app.com/callback',
  externalId: 'user-123',
  loginHint: 'user@example.com',
})
```

--------------------------------

### GET /v1/events/:endUserAccountId/:calendarId/:eventId/occurrences

Source: https://docs.onecalunified.com/calendar-events

Retrieves occurrences of a specific event within a given time range. It supports filtering by date, time zone, metadata, search terms, and ordering.

```APIDOC
## GET /v1/events/:endUserAccountId/:calendarId/:eventId/occurrences

### Description
Retrieves occurrences of a specific event within a given time range. It supports filtering by date, time zone, metadata, search terms, and ordering.

### Method
GET

### Endpoint
/v1/events/:endUserAccountId/:calendarId/:eventId/occurrences

### Parameters
#### Path Parameters
- **endUserAccountId** (string) - Required - The unique identifier of the End User Account to retrieve.
- **calendarId** (string) - Required - The unique identifier of the Calendar to retrieve.
- **eventId** (string) - Required - The unique identifier of the Event to retrieve.

#### Query Parameters
- **syncToken** (string) - Optional - Token used at a later point in time to retrieve only the entries that have changed since this result was returned. Omitted if further results are available, in which case nextPageToken is provided.
- **startDateTime** (string) - Required - ISO 8601 date-time to filter events that start after this time.
- **endDateTime** (string) - Required - ISO 8601 date-time to filter events that end before this time.
- **timeZone** (string) - Optional - Display all events in the specified time zone.
- **metadataFilters** (string) - Optional - JSON object to filter events by custom properties.
- **search** (string) - Optional - Search for events by title.
- **orderBy** (string) - Optional - Field to order events by. If not provided, events should be considered unordered.

### Request Example
```curl
curl -X GET https://api.onecalunified.com/api/v1/events/:endUserAccountId/:calendarId/:eventId/occurrences?startDateTime=2025-08-13T00:00:00&endDateTime=2025-08-14T00:00:00 \
  -H "x-api-key: {apiKey}"
```

### Response
#### Success Response (200)
- **data** (array) - List of event occurrences.
- **nextSyncToken** (string) - Token for subsequent synchronization.

#### Response Example
```json
{
  "data": [
    {
      "id": "4t2rmfbo4ohlla0jj9vjlhfrv3_20250813",
      "title": "Recurring Event",
      "etag": "\"3510023641690558\"",
      "createdAt": "2025-08-12T15:16:48.000Z",
      "updatedAt": "2025-08-12T15:17:00.845Z",
      "start": {
        "dateTime": "2025-08-13T00:00:00",
        "timeZone": "Etc/UTC"
      },
      "end": {
        "dateTime": "2025-08-14T00:00:00",
        "timeZone": "Etc/UTC"
      },
      "isAllDay": true,
      "isRecurring": false,
      "isException": true,
      "isCancelled": false,
      "recurrence": null,
      "originalStart": {
        "date": "2025-08-13"
      },
      "recurringEventId": "4t2rmfbo4ohlla0jj9vjlhfrv3",
      "webLink": "",
      "iCalUid": "4t2rmfbo4ohlla0jj9vjlhfrv3@google.com",
      "transparency": "transparent",
      "eventType": "default",
      "organizer": {
        "name": "Organizer",
        "email": "ddc4phg9nsqnf2k5t6dfbja0@group.calendar.google.com",
        "isSelf": true
      },
      "creator": {
        "email": "creator@example.com"
      },
      "reminders": {
        "useDefault": false
      }
    }
  ],
  "nextSyncToken": "CM_equb3lJADEM_equb3lJADGAUgx7T7hAMox7T7hAM="
}

```

--------------------------------

### List Calendar Subscriptions

Source: https://docs.onecalunified.com/webhooks

Retrieves a paginated list of webhook subscriptions for a specific End User Account.

```cURL
curl -X GET https://api.onecalunified.com/api/v1/calendarSubscriptions/:endUserAccountId \
  -H "x-api-key: {apiKey}"
```

--------------------------------

### List End User Accounts

Source: https://docs.onecalunified.com/end-user-accounts

Retrieves a paginated list of all End User Accounts associated with your application. Supports filtering by email, external ID, and status.

```bash
curl -X GET https://api.onecalunified.com/api/v1/endUserAccounts \
  -H "x-api-key: {apiKey}"
```

--------------------------------

### Apple Account Connection Response

Source: https://docs.onecalunified.com/authentication

This JSON object represents a successful response after connecting an Apple account. It includes user details, account status, and provider information.

```json
{
  "id": "user_account_1",
  "createdAt": "2025-09-12T10:15:00.000Z",
  "updatedAt": "2025-09-12T10:15:00.000Z",
  "email": "user@icloud.com",
  "externalId": "",
  "authorizedScopes": [],
  "providerAccountId": null,
  "providerId": "provider_1",
  "applicationId": "application_1",
  "status": "ACTIVE",
  "providerType": "APPLE"
}
```

--------------------------------

### Webhook Subscription Model Properties

Source: https://docs.onecalunified.com/webhooks

Properties related to the webhook subscription model.

```APIDOC
## The Webhook Subscription model

### Properties

* **webhookSubscriptionId** (string) - Unique identifier for the webhook subscription. Read-Only
* **endpointSecret** (string) - Secret key used to verify webhook signatures. Store this securely. Read-Only
```