Get Calendar

This endpoint allows you to retrieve information about specific calendars and list all calendars with optional filtering and pagination.

🔹 Endpoint Details

Get Single Calendar

GET /api/v2/calendars/{id}

List Calendars

GET /api/v2/calendars

🔒 Authentication

Header	Required	Description
Authorization	Yes	Format: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature

📝 Request Parameters

Path Parameters (Get Single Calendar)

Parameter	Type	Required	Description	Example
id	string (UUID)	Yes	Unique identifier of the calendar	123e4567-e89b-12d3-a456-426614174000

Query Parameters (List Calendars)

Parameter	Type	Required	Description	Example
page	number	No	Page number for pagination	1
limit	number	No	Items per page	20
type	enum	No	Filter by calendar type (agent or asset)	"agent"
search	string	No	Search by name or tags	"Meeting"
extraFields	object	No	Additional fields for filtering	{ "location": "HQ" }
appointmentId	string	No	Filter by associated appointment ID (UUID)	"123e4567-e89b-12d3-a456-426614174000"
serviceId	string	No	Filter by associated service ID (UUID)	"01392598-e4b2-4810-ac7c-8c9cf4286a26"

🧩 Request Examples

Get Single Calendar

curl -X GET "https://openapi.onlive.site/api/v2/calendars/123e4567-e89b-12d3-a456-426614174000" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

List Calendars with Filtering

curl -X GET "https://openapi.onlive.site/api/v2/calendars?page=1&limit=10&type=agent&search=team&serviceId=01392598-e4b2-4810-ac7c-8c9cf4286a26" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

📤 Response Format

Single Calendar Response (200 OK)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Work Calendar",
  "timezone": "America/New_York",
  "type": "agent",
  "organizationId": "26d47eec-c742-4b1c-9d70-9a1486260abd",
  "extraFields": {
    "location": "New York Office",
    "capacity": 10
  },
  "email": "[email protected]",
  "canonicalId": "cal_12345",
  "tags": ["sales", "support"],
  "createdAt": "2025-05-22T10:30:00Z",
  "updatedAt": "2025-05-22T10:30:00Z"
}

List Response (200 OK)

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Work Calendar",
      "timezone": "America/New_York",
      "type": "agent",
      "organizationId": "26d47eec-c742-4b1c-9d70-9a1486260abd",
      "extraFields": {
        "location": "New York Office",
        "capacity": 10
      },
      "email": "[email protected]",
      "canonicalId": "cal_12345",
      "tags": ["sales", "support"]
    }
  ],
  "total": 45,
  "page": 1,
  "limit": 10,
  "pages": 5
}

❌ Error Responses

This endpoint follows the standard error format.

📘 Notes

• All timestamps are in ISO 8601 format with UTC timezone
• The list endpoint supports pagination through page and limit parameters
• Search is case-insensitive and matches:
  • Calendar name
  • Tags
  • Results are sorted by creation date in descending order (newest first)
  • The organizationId is automatically applied from your authentication token

✅ Common Use Cases

• 🔍 Calendar Lookup: Find specific calendars by ID
• 📊 Resource Directory: List all calendars in your organization

🔍 Search Tips

1. Partial Matching

   • Search "sales" matches calendars with "sales" tag or name
   • Search "room" matches "Meeting Room", "Room 101"
   • Search "NY" matches "NY Office Calendar"

2. Performance

   • Use appropriate page sizes (10-50 items)
   • Cache frequently accessed calendar details
   • Use specific filters when possible