> ## Documentation Index > Fetch the complete documentation index at: https://chatbotx.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # List appointments > Use this to find appointments by calendar or next/past tab before opening one with `appointments.get`. Returns paginated workspace appointments for scheduling workflows. ## OpenAPI ````yaml /api-reference/platform-api.json get /v1/appointments openapi: 3.1.1 info: title: ChatbotX version: 0.0.1 servers: - url: https://app.chatbotx.io/api security: - bearerAuth: [] - developerAccessToken: [] - tokenInSearchParams: [] paths: /v1/appointments: get: tags: - Appointments summary: List appointments description: >- Use this to find appointments by calendar or next/past tab before opening one with `appointments.get`. Returns paginated workspace appointments for scheduling workflows. operationId: appointments.list parameters: - name: page in: query schema: type: integer minimum: 1 maximum: 9007199254740991 default: 1 description: Page number, starting at 1. allowEmptyValue: true allowReserved: true - name: perPage in: query schema: type: integer minimum: 1 maximum: 50 default: 50 description: Number of items per page, up to 50. allowEmptyValue: true allowReserved: true - name: calendarId in: query schema: type: string pattern: ^\d+$ description: >- Restrict to appointments on this calendar. Get it from `appointmentCalendars.list`. allowEmptyValue: true allowReserved: true - name: tab in: query schema: enum: - next - past type: string description: Restrict to upcoming (`next`) or past appointments. allowEmptyValue: true allowReserved: true - name: search in: query schema: type: string description: Case-insensitive substring match against the contact's name. allowEmptyValue: true allowReserved: true responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string calendarId: type: string contactId: type: string conversationId: anyOf: - type: string - type: 'null' startAt: type: string format: date-time x-native-type: date endAt: type: string format: date-time x-native-type: date inviteeTimezone: type: string status: enum: - scheduled - cancelled type: string locationType: enum: - inPerson - phoneCall - onlineMeeting type: string locationDetail: anyOf: - type: string - type: 'null' externalEventId: anyOf: - type: string - type: 'null' cancelledAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' createdAt: type: string format: date-time x-native-type: date updatedAt: type: string format: date-time x-native-type: date calendarName: type: string scheduleUrl: type: string cancellable: type: boolean deletable: type: boolean required: - id - calendarId - contactId - conversationId - startAt - endAt - inviteeTimezone - status - locationType - locationDetail - externalEventId - cancelledAt - createdAt - updatedAt - calendarName - scheduleUrl - cancellable - deletable description: Items on this page. pageCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Total number of pages for the requested perPage; stop when page >= pageCount. required: - data - pageCount '400': description: '400' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: businessError status: const: 400 message: type: string default: An error occurred while processing your request data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '401': description: '401' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: UNAUTHORIZED status: const: 401 message: type: string default: Authentication required data: {} required: - defined - code - status - message - type: object properties: defined: const: true code: const: INVALID_CHATBOT_TOKEN status: const: 401 message: type: string default: Invalid or missing workspace API token data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '403': description: '403' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: FORBIDDEN status: const: 403 message: type: string default: You do not have permission to perform this action data: {} required: - defined - code - status - message - type: object properties: defined: const: true code: const: trialExpired status: const: 403 message: type: string default: Trial expired data: {} required: - defined - code - status - message - type: object properties: defined: const: true code: const: macLimitReached status: const: 403 message: type: string default: Monthly active contact limit reached data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '422': description: '422' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: invalidRequestData status: const: 422 message: type: string default: Input validation failed data: type: object properties: issues: type: array items: type: object properties: message: type: string path: type: array items: anyOf: - type: string - type: number - type: object properties: key: anyOf: - type: string - type: number required: - key additionalProperties: {} required: - message additionalProperties: {} required: - issues additionalProperties: {} required: - defined - code - status - message - data - type: object properties: defined: const: true code: const: validation status: const: 422 message: type: string default: Validation error data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '429': description: '429' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: tooManyRequests status: const: 429 message: type: string default: Too many requests data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '500': description: '500' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: INTERNAL_SERVER_ERROR status: const: 500 message: type: string default: An unexpected error occurred data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' components: schemas: UndefinedError: type: object properties: defined: const: false code: type: string status: type: number message: type: string data: {} required: - defined - code - status - message securitySchemes: bearerAuth: type: http scheme: bearer developerAccessToken: type: http scheme: bearer tokenInSearchParams: type: apiKey in: query name: token ````