Add a calendar to an assistant

POST/assistants/{id}/calendars

Add a calendar on a provider, before any account is connected to it. Then create an invite link for the account owner to connect it: connecting gives it the handle the prompt mentions, named after the account (google_calendar_jane_at_example.com).

Request

curl -X POST "https://www.getrevox.com/api/assistants/3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34/calendars" \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "google-calendar" }'

const res = await fetch("https://www.getrevox.com/api/assistants/3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34/calendars", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.REVOX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    provider: "google-calendar",
  }),
});
const data = await res.json();
console.log(data);

import os

import requests

response = requests.post(
    "https://www.getrevox.com/api/assistants/3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34/calendars",
    headers={"Authorization": f"Bearer {os.environ['REVOX_API_KEY']}"},
    json={
        "provider": "google-calendar",
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())

Adds a calendar with no account yet: its status is not_connected.

Try itSend this request live

Response

Success

{
  "calendar": {
    "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e",
    "assistant_id": "3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34",
    "handle": "google_calendar_jane_at_example.com",
    "provider": "google-calendar",
    "status": "ready",
    "connection": {
      "provider": "google-calendar",
      "connection_id": "9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
      "settings": {
        "calendar_id": "primary",
        "time_zone": "Europe/Paris",
        "duration_minutes": 30,
        "days": [1, 2, 3, 4, 5],
        "start_time": "09:00",
        "end_time": "18:00",
        "google_meet": false,
        "location": "{{site_address}}"
      }
    },
    "account_label": "Main line",
    "connected_via_invite": false,
    "invite": {
      "url": "https://example.com",
      "status": "completed",
      "created_at": "2026-11-05T09:00:00Z",
      "expires_at": "2026-11-05T09:00:00Z"
    },
    "created_at": "2026-11-05T09:00:00Z"
  }
}

{
  "message": "Request validation failed",
  "bodyErrors": {
    "issues": [
      {
        "path": ["provider"],
        "message": "Invalid input: expected string, received undefined",
        "code": "invalid_type"
      }
    ]
  }
}

{ "error": "Not found" }

Path parameters

idstringrequired
ID of the assistant, as returned by GET /assistants.

Request body

application/json

provider"google-calendar" | "calendly" | "cal-com-oauth"required
Calendar provider.
"google-calendar"
Google Calendar: books on a calendar of the account, with the opening hours and meeting length of its settings.
"calendly"
Calendly: books an event type of the account.
"cal-com-oauth"
Cal.com: books an event type of the account.

Response

200

calendarAssistantCalendar
- idstring
  Unique ID of the calendar: the {calendarId} of the calendar endpoints.
- assistant_idstring
  ID of the assistant that books on this calendar.
- handlestringnullable
  How the prompt names this calendar, as @handle: the provider, then the connected account (e.g. google_calendar_jane_at_example.com). Null until an account is connected, unique within the assistant, kept when it is disconnected.
  Example "google_calendar_jane_at_example.com"at most 255 characters
- provider"google-calendar" | "calendly" | "cal-com-oauth"
  Calendar provider.
  "google-calendar"
  Google Calendar: books on a calendar of the account, with the opening hours and meeting length of its settings.
  "calendly"
  Calendly: books an event type of the account.
  "cal-com-oauth"
  Cal.com: books an event type of the account.
- status"not_connected" | "needs_setup" | "ready"
  Whether the calendar takes bookings.
  "not_connected"
  No account is connected yet: send the invite link to the account owner, or connect an account of your organization.
  "needs_setup"
  An account is connected, but the calendar (Google) or event type (Calendly, Cal.com) to book on is not picked: list them with GET .../options and pick one with PUT .../selection.
  "ready"
  Takes bookings: the agent can book on it during calls.
- connectionobjectnullable
  The connected account, on the calendar's provider. Null until one is connected.
- account_labelstringnullable
  The connected account, usually its email. Null when not connected, or when the provider did not say.
- connected_via_inviteboolean
  True when the account was connected by a colleague from the invite link.
- inviteobjectnullable
  The invite link a colleague can use to connect their own account to this calendar (POST /assistants/{id}/calendars/{calendarId}/invite). Null when no link was created, once it was revoked, and once an account was connected from the dashboard or the API instead.
- created_atstring (date-time)
  When the calendar was added to the assistant (ISO 8601).

Errors

400Invalid request: a field or parameter failed validation{ "message"?: string, "error"?: string, "bodyErrors"?: {…} }
404Not found in your organization{ "message"?: string, "error"?: string, "bodyErrors"?: {…} }

Error bodies carry an error (or message) string; a 400 adds bodyErrors.issues. See Errors.