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/v1/calendars/{id}

List Calendars

GET /api/v1/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	Default
page	number	No	Page number for pagination	1
limit	number	No	Items per page	20
type	string	No	Filter by calendar type (agent/asset)	-
search	string	No	Search in name or tags	-
userGroupId	string	No	Filter by user group ID	-

🧩 Request Examples

Get Single Calendar

curl -X GET "https://openapi.onlive.site/api/v1/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/v1/calendars?page=1&limit=10&type=agent&userGroupId=123e4567-e89b-12d3-a456-426614174000" \
-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",
  "externalId": "cal-12345",
  "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]",
  "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",
      "externalId": "cal-12345",
      "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]",
      "tags": ["sales", "support"]
    }
  ],
  "total": 45,
  "page": 1,
  "limit": 10,
  "pages": 5
}

❌ Error Responses

401 Unauthorized

{
  "statusCode": 401,
  "message": "Invalid or missing authorization credentials"
}

403 Forbidden

{
  "statusCode": 403,
  "message": "User does not have permission to access this calendar"
}

404 Not Found

{
  "statusCode": 404,
  "message": "Calendar not found"
}

📘 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
  • External ID
• 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
• 🔎 Resource Search: Find calendars by name or tags
• 👥 Group Management: List calendars in a specific group
• 📱 Type Filtering: Filter agent or asset calendars
• 📋 Pagination: Handle large sets of calendars efficiently

🔍 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

---