> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravan.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Cal.com Appointment

> Manage an appointment request for the AI agent; no X-Api-Key is required, and `org_id` is provided in the request body.

### Body

<ParamField body="action" type="string" required>
  The appointment operation to perform. Use values such as `create`, `reschedule`, `cancel`, or `list`, depending on the appointment workflow.
</ParamField>

<ParamField body="agent_id" type="string" required>
  The unique ID of the agent that should own, handle, or be assigned to this resource. Use the `id` returned by the Agent API.
</ParamField>

<ParamField body="org_id" type="string" required>
  The organization ID that owns the resource. Use the organization ID from your Agni account.
</ParamField>

<ParamField body="name" type="string">
  The customer's full name for the appointment.
</ParamField>

<ParamField body="email" type="string">
  The contact email address. Use a valid email format such as `alex@example.com`.
</ParamField>

<ParamField body="phone" type="string">
  The contact phone number in E.164 format. Example: `+14157774444`.
</ParamField>

<ParamField body="appointment_datetime" type="string">
  The appointment date and time in ISO 8601 format. Include a timezone offset when possible, for example `2026-03-14T15:00:00+05:30`.
</ParamField>

<ParamField body="appointment_id" type="string">
  The unique appointment ID. Use the ID returned when the appointment was created or listed.
</ParamField>

<ParamField body="call_session_id" type="string">
  The unique call session ID associated with the conversation or appointment. Use it to connect call activity with follow-up actions.
</ParamField>

<ParamField body="notes" type="string">
  Additional notes for the appointment, contact, or call. These notes can include context for follow-up.
</ParamField>

<ParamField body="days_ahead" type="integer">
  The number of days ahead to search for available appointment slots.
</ParamField>

***

### Response

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="message" type="string">
  Natural language message to relay directly to the user
</ResponseField>

<ResponseField name="data" type="object">
  data field.

  <Expandable title="data">
    <ResponseField name="success" type="boolean">
      success field.
    </ResponseField>

    <ResponseField name="message" type="string">
      message field.
    </ResponseField>

    <ResponseField name="summary" type="string">
      Short label (e.g. Appointment confirmed, Cancelled, Rescheduled)
    </ResponseField>

    <ResponseField name="action" type="string">
      The action that was performed
    </ResponseField>

    <ResponseField name="appointment_id" type="string">
      Appointment ID (returned for book, reschedule, cancel)
    </ResponseField>

    <ResponseField name="date_time" type="string">
      Confirmed appointment datetime in ISO 8601
    </ResponseField>

    <ResponseField name="agent_name" type="string">
      Name of the agent handling the appointment
    </ResponseField>

    <ResponseField name="action_required" type="string">
      Next action required if the request could not be completed (e.g. reschedule)
    </ResponseField>

    <ResponseField name="available_slots" type="object[]">
      Available time slots grouped by date (returned for suggest, availability, and slot-unavailable responses)

      <Expandable title="available_slots[]">
        <ResponseField name="date" type="string">
          Date in YYYY-MM-DD format
        </ResponseField>

        <ResponseField name="date_label" type="string">
          Human-readable date label (e.g. Today, Tomorrow)
        </ResponseField>

        <ResponseField name="slots" type="string[]">
          Available time slots (e.g. 9:00 AM)
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "message": "Appointment confirmed successfully",
    "data": {
      "success": true,
      "message": "Booked successfully",
      "summary": "Appointment confirmed",
      "action": "book",
      "appointment_id": "appt_123",
      "date_time": "2026-03-20T14:00:00Z",
      "agent_name": "Dr. Rivera",
      "action_required": "",
      "available_slots": [
        {
          "date": "2026-03-21",
          "date_label": "Tomorrow",
          "slots": [
            "9:00 AM",
            "11:30 AM"
          ]
        }
      ]
    }
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 422 theme={null}
  {
    "success": false,
    "message": "Requested slot is unavailable",
    "error": {
      "code": "SLOT_UNAVAILABLE",
      "message": "The selected time is no longer available",
      "details": {
        "summary": "Please choose a different slot",
        "action": "book",
        "action_required": "reschedule",
        "agent_name": "Dr. Rivera",
        "available_slots": [
          {
            "date": "2026-03-21",
            "date_label": "Tomorrow",
            "slots": [
              "10:00 AM",
              "1:00 PM"
            ]
          },
          {
            "date": "2026-03-22",
            "date_label": "Friday",
            "slots": [
              "9:30 AM",
              "3:00 PM"
            ]
          }
        ]
      }
    }
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /api/v1/calcom/appointments/manage
openapi: 3.0.1
info:
  title: Agni API
  version: 1.0.0
  description: >-
    Agni API for managing agents, tools, widget settings, telephony, and
    integrations.
servers:
  - url: https://api.ravan.ai
security:
  - X-Api-Key: []
tags:
  - name: AgentService
  - name: AgentToolService
  - name: WidgetSettingsService
  - name: PhoneService
  - name: AppointmentService
  - name: GHLService
  - name: CalComService
  - name: CampaignService
  - name: ContactService
  - name: CallingService
  - name: RAGService
  - name: ModelService
  - name: HealthService
paths:
  /api/v1/calcom/appointments/manage:
    post:
      tags:
        - AppointmentService
      summary: Manage Cal.com Appointment
      description: >-
        Unified appointment management endpoint for Cal.com. Supports book,
        reschedule, cancel, suggest, and availability actions. No X-Api-Key
        required — org_id comes from the request body.
      operationId: ManageCalcomAppointment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManageAppointmentRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManageAppointmentResponse'
        '422':
          description: Slot unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlotUnavailableResponse'
      security: []
components:
  schemas:
    ManageAppointmentRequest:
      type: object
      required:
        - action
        - agent_id
        - org_id
      properties:
        action:
          type: string
          enum:
            - book
            - reschedule
            - cancel
            - suggest
            - availability
          description: The appointment action to perform
        agent_id:
          type: string
          description: UUID of the agent handling the appointment
        org_id:
          type: string
          description: UUID of the organization
        name:
          type: string
          description: Customer full name (required for book)
        email:
          type: string
          description: Customer email (required for book if no phone)
        phone:
          type: string
          description: Customer phone in E.164 format (required for book if no email)
        appointment_datetime:
          type: string
          description: ISO 8601 datetime for book or reschedule
        appointment_id:
          type: string
          description: Existing appointment ID (required for cancel and reschedule)
        call_session_id:
          type: string
          description: Optional call session ID for book
        notes:
          type: string
          description: Optional notes for the appointment
        days_ahead:
          type: integer
          format: int32
          description: >-
            Days ahead to look for available slots (default: 7, max: 30). Used
            for suggest and availability.
    ManageAppointmentResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
          description: Natural language message to relay directly to the user
        data:
          type: object
          properties:
            success:
              type: boolean
            message:
              type: string
            summary:
              type: string
              description: Short label (e.g. Appointment confirmed, Cancelled, Rescheduled)
            action:
              type: string
              description: The action that was performed
            appointment_id:
              type: string
              description: Appointment ID (returned for book, reschedule, cancel)
            date_time:
              type: string
              description: Confirmed appointment datetime in ISO 8601
            agent_name:
              type: string
              description: Name of the agent handling the appointment
            action_required:
              type: string
              description: >-
                Next action required if the request could not be completed (e.g.
                reschedule)
            available_slots:
              type: array
              description: >-
                Available time slots grouped by date (returned for suggest,
                availability, and slot-unavailable responses)
              items:
                type: object
                properties:
                  date:
                    type: string
                    description: Date in YYYY-MM-DD format
                  date_label:
                    type: string
                    description: Human-readable date label (e.g. Today, Tomorrow)
                  slots:
                    type: array
                    items:
                      type: string
                    description: Available time slots (e.g. 9:00 AM)
    SlotUnavailableResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
        error:
          type: object
          properties:
            code:
              type: string
              example: SLOT_UNAVAILABLE
            message:
              type: string
            details:
              type: object
              properties:
                summary:
                  type: string
                action:
                  type: string
                action_required:
                  type: string
                  example: reschedule
                agent_name:
                  type: string
                available_slots:
                  type: array
                  items:
                    type: object
  securitySchemes:
    X-Api-Key:
      type: apiKey
      in: header
      name: X-Api-Key

````