Create, read, update, cancel, and reschedule bookings. Supports recurring, seated, and round-robin booking flows.
{
"openapi": "3.0.0",
"paths": {
"/v2/api-keys/refresh": {
"post": {
"operationId": "ApiKeysController_refresh",
"summary": "Refresh API Key",
"description": "Generate a new API key and delete the current one. Provide API key to refresh as a Bearer token in the Authorization header (e.g. \"Authorization: Bearer <apiKey>\").",
"parameters": [
{
"name": "Authorization",
"in": "header",
"description": "value must be `Bearer <token>` where `<token>` is api key prefixed with cal_",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RefreshApiKeyInput"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RefreshApiKeyOutput"
}
}
}
}
},
"tags": ["Api Keys"]
}
},
"/v2/bookings": {
"post": {
"operationId": "BookingsController_2024_08_13_createBooking",
"summary": "Create a booking",
"description": "\n POST /v2/bookings is used to create regular bookings, recurring bookings and instant bookings. The request bodies for all 3 are almost the same except:\n If eventTypeId in the request body is id of a regular event, then regular booking is created.\n\n If it is an id of a recurring event type, then recurring booking is created.\n\n Meaning that the request bodies are equal but the outcome depends on what kind of event type it is with the goal of making it as seamless for developers as possible.\n\n The start needs to be in UTC aka if the timezone is GMT+2 in Rome and meeting should start at 11, then UTC time should have hours 09:00 aka without time zone.\n\n Finally, there are 2 ways to book an event type belonging to an individual user:\n 1. Provide `eventTypeId` in the request body.\n 2. Provide `eventTypeSlug` and `username` and optionally `organizationSlug` if the user with the username is within an organization.\n\n And 2 ways to book and event type belonging to a team:\n 1. Provide `eventTypeId` in the request body.\n 2. Provide `eventTypeSlug` and `teamSlug` and optionally `organizationSlug` if the team with the teamSlug is within an organization.\n\n If you are creating a seated booking for an event type with 'show attendees' disabled, then to retrieve attendees in the response either set 'show attendees' to true on event type level or\n you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner.\n\n For event types that have SMS reminders enabled, you need to pass the attendee's phone number in the request body via `attendee.phoneNumber` (e.g., \"+19876543210\" in international format). This is an optional field, but becomes required when SMS reminders are enabled for the event type. For the complete attendee object structure, see the attendee schema in the `/docs` Swagger endpoint.\n\n <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>\n ",
"parameters": [
{
"name": "cal-api-version",
"in": "header",
"description": "Must be set to 2024-08-13. If not set to this value, the endpoint will default to an older version.",
"required": true,
"schema": {
"type": "string",
"default": "2024-08-13"
}
},
{
"name": "Authorization",
"in": "header",
"description": "value must be `Bearer <token>` where `<token>` is api key prefixed with cal_ or managed user access token",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "x-cal-secret-key",
"in": "header",
"description": "For platform customers - OAuth client secret key",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "x-cal-client-id",
"in": "header",
"description": "For platform customers - OAuth client ID",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"description": "Accepts different types of booking input: Create Booking (Option 1) or Create Recurring Booking (Option 2)",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/CreateBookingInput_2024_08_13"
},
{
"$ref": "#/components/schemas/CreateRecurringBookingInput_2024_08_13"
}
]
}
}
}
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateBookingOutput_2024_08_13"
}
}
}
}
},
"tags": ["Bookings"]
},
"get": {
"operationId": "BookingsController_2024_08_13_getBookings",
"summary": "Get all bookings",
"description": "<Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>",
"parameters": [
{
"name": "cal-api-version",
"in": "header",
"description": "Must be set to 2024-08-13. If not set to this value, the endpoint will default to an older version.",
"required": true,
"schema": {
"type": "string",
"default": "2024-08-13"
}
},
{
"name": "status",
"required": false,
"in": "query",
"description": "Filter bookings by status. If you want to filter by multiple statuses, separate them with a comma.",
"schema": {
"example": "?status=upcoming,past",
"type": "array",
"items": {
"type": "string",
"enum": ["upcoming", "recurring", "past", "cancelled", "unconfirmed"]
}
}
},
{
"name": "attendeeEmail",
"required": false,
"in": "query",
"description": "Filter bookings by the attendee's email address.",
"schema": {
"example": "example@domain.com",
"type": "string"
}
},
{
"name": "attendeeName",
"required": false,
"in": "query",
"description": "Filter bookings by the attendee's name.",
"schema": {
"example": "John Doe",
"type": "string"
}
},
{
"name": "bookingUid",
"required": false,
"in": "query",
"description": "Filter bookings by the booking Uid.",
"schema": {
"example": "2NtaeaVcKfpmSZ4CthFdfk",
"type": "string"
}
},
{
"name": "eventTypeIds",
"required": false,
"in": "query",
"description": "Filter bookings by event type ids belonging to the user. Event type ids must be separated by a comma.",
"schema": {
"example": "?eventTypeIds=100,200",
"type": "string"
}
},
{
"name": "eventTypeId",
"required": false,
"in": "query",
"description": "Filter bookings by event type id belonging to the user.",
"schema": {
"example": "?eventTypeId=100",
"type": "string"
}
},
{
"name": "teamsIds",
"required": false,
"in": "query",
"description": "Filter bookings by team ids that user is part of. Team ids must be separated by a comma.",
"schema": {
"example": "?teamIds=50,60",
"type": "string"
}
},
{
"name": "teamId",
"required": false,
"in": "query",
"description": "Filter bookings by team id that user is part of",
"schema": {
"example": "?teamId=50",
"type": "string"
}
},
{
"name": "afterStart",
"required": false,
"in": "query",
"description": "Filter bookings with start after this date string.",
"schema": {
"example": "?afterStart=2025-03-07T10:00:00.000Z",
"type": "string"
}
},
{
"name": "beforeEnd",
"required": false,
"in": "query",
"description": "Filter bookings with end before this date string.",
"schema": {
"example": "?beforeEnd=2025-03-07T11:00:00.000Z",
"type": "string"
}
},
{
"name": "afterCreatedAt",
"required": false,
"in": "query",
"description": "Filter bookings that have been created after this date string.",
"schema": {
"example": "?afterCreatedAt=2025-03-07T10:00:00.000Z",
"type": "string"
}
},
{
"name": "beforeCreatedAt",
"required": false,
"in": "query",
"description": "Filter bookings that have been created before this date string.",
"schema": {
"example": "?beforeCreatedAt=2025-03-14T11:00:00.000Z",
"type": "string"
}
},
{
"name": "afterUpdatedAt",
"required": false,
"in": "query",
"description": "Filter bookings that have been updated after this date string.",
"schema": {
"example": "?afterUpdatedAt=2025-03-07T10:00:00.000Z",
"type": "string"
}
},
{
"name": "beforeUpdatedAt",
"required": false,
"in": "query",
"description": "Filter bookings that have been updated before this date string.",
"schema": {
"example": "?beforeUpdatedAt=2025-03-14T11:00:00.000Z",
"type": "string"
}
},
{
"name": "sortStart",
"required": false,
"in": "query",
"description": "Sort results by their start time in ascending or descending order.",
"schema": {
"example": "?sortStart=asc OR ?sortStart=desc",
"enum": ["asc", "desc"],
"type": "string"
}
},
{
"name": "sortEnd",
"required": false,
"in": "query",
"description": "Sort results by their end time in ascending or descending order.",
"schema": {
"example": "?sortEnd=asc OR ?sortEnd=desc",
"enum": ["asc", "desc"],
"type": "string"
}
},
{
"name": "sortCreated",
"required": false,
"in": "query",
"description": "Sort results by their creation time (when booking was made) in ascending or descending order.",
"schema": {
"example": "?sortCreated=asc OR ?sortCreated=desc",
"enum": ["asc", "desc"],
"type": "string"
}
},
{
"name": "sortUpdatedAt",
"required": false,
"in": "query",
"description": "Sort results by their updated time (for example when booking status changes) in ascending or descending order.",
"schema": {
"example": "?sortUpdated=asc OR ?sortUpdated=desc",
"enum": ["asc", "desc"],
"type": "string"
}
},
{
"name": "take",
"required": false,
"in": "query",
"description": "The number of items to return",
"schema": {
"default": 100,
"example": 10,
"type": "number"
}
},
{
"name": "skip",
"required": false,
"in": "query",
"description": "The number of items to skip",
"schema": {
"default": 0,
"example": 0,
"type": "number"
}
},
{
"name": "Authorization",
"in": "header",
"description": "value must be `Bearer <token>` where `<token>` is api key prefixed with cal_ or managed user access token",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetBookingsOutput_2024_08_13"
}
}
}
}
},
"tags": ["Bookings"]
}
},
"/v2/bookings/by-seat/{seatUid}": {
"get": {
"operationId": "BookingsController_2024_08_13_getBookingBySeatUid",
"summary": "Get a booking by seat UID",
"description": "Get a seated booking by its seat reference UID. This is useful when you have a seatUid from a seated booking and want to retrieve the full booking details.\n\n If you are fetching a seated booking for an event type with 'show attendees' disabled, then to retrieve attendees in the response either set 'show attendees' to true on event type level or\n you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner.\n\n <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>\n ",
"parameters": [
{
"name": "cal-api-version",
"in": "header",
"description": "Must be set to 2024-08-13. If not set to this value, the endpoint will default to an older version.",
"required": true,
"schema": {
"type": "string",
"default": "2024-08-13"
}
},
{
"name": "seatUid",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "Authorization",
"in": "header",
"description": "value must be `Bearer <token>` where `<token>` is api key prefixed with cal_ or managed user access token",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "x-cal-secret-key",
"in": "header",
"description": "For platform customers - OAuth client secret key",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "x-cal-client-id",
"in": "header",
"description": "For platform customers - OAuth client ID",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetBookingOutput_2024_08_13"
}
}
}
}
},
"tags": ["Bookings"]
}
},
"/v2/bookings/{bookingUid}": {
"get": {
"operationId": "BookingsController_2024_08_13_getBooking",
"summary": "Get a booking",
"description": "`:bookingUid` can be\n\n 1. uid of a normal booking\n\n 2. uid of one of the recurring booking recurrences\n\n 3. uid of recurring booking which will return an array of all recurring booking recurrences (stored as recurringBookingUid on one of the individual recurrences).\n\n If you are fetching a seated booking for an event type with 'show attendees' disabled, then to retrieve attendees in the response either set 'show attendees' to true on event type level or\n you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner.\n\n <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>\n ",
"parameters": [
{
"name": "cal-api-version",
"in": "header",
"description": "Must be set to 2024-08-13. If not set to this value, the endpoint will default to an older version.",
"required": true,
"schema": {
"type": "string",
"default": "2024-08-13"
}
},
{
"name": "bookingUid",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "Authorization",
"in": "header",
"description": "value must be `Bearer <token>` where `<token>` is api key prefixed with cal_ or managed user access token",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "x-cal-secret-key",
"in": "header",
"description": "For platform customers - OAuth client secret key",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "x-cal-client-id",
"in": "header",
"description": "For platform customers - OAuth client ID",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetBookingOutput_2024_08_13"
}
}
}
}
},
"tags": ["Bookings"]
}
},
"/v2/bookings/{bookingUid}/recordings": {
"get": {
"operationId": "BookingsController_2024_08_13_getBookingRecordings",
"summary": "Get all the recordings for the booking",
"description": "Fetches all the recordings for the booking `:bookingUid`. Requires authentication and proper authorization. Access is granted if you are the booking organizer, team admin or org admin/owner.\n\n <Note>cal-api-version: `2024-08-13` is required in the request header.</Note>\n ",
"parameters": [
{
"name": "cal-api-version",
"in": "header",
"description": "Must be set to 2024-08-13. If not set to this value, the endpoint will default to an older version.",
"required": true,
"schema": {
"type": "string",
"default": "2024-08-13"
}
},
{
"name": "bookingUid",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "Authorization",
"in": "header",
"description": "value must be `Bearer <token>` where `<token>` is api key prefixed with cal_ or managed user access token",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetBookingRecordingsOutput"
}
}
}
}
},
"tags": ["Bookings"]
}
},
"/v2/bookings/{bookingUid}/transcripts": {
"get": {
"operationId": "BookingsController_2024_08_13_getBookingTranscripts",
"summary": "Get Cal Video real time transcript download links for the booking",
"description": "Fetches all the transcript download links for the booking `:bookingUid`\n\n <Note>\n Transcripts are generated when clicking \"Transcribe\" during a Cal Video meeting. Download links are valid for 1 hour only - make a new request to generate fresh links after expiration.\n\n Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.\n </Note>\n ",
"parameters": [
{
"name": "cal-api-version",
"in": "header",
"description": "Must be set to 2024-08-13. If not set to this value, the endpoint will default to an older version.",
"required": true,
"schema": {
"type": "string",
"default": "2024-08-13"
}
},
{
"name": "bookingUid",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "Authorization",
"in": "header",
"description": "value must be `Bearer <token>` where `<token>` is api key prefixed with cal_ or managed user access token",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetBookingTranscriptsOutput"
}
}
}
}
},
"tags": ["Bookings"]
}
},
"/v2/bookings/{bookingUid}/reschedule": {
"post": {
"operationId": "BookingsController_2024_08_13_rescheduleBooking",
"summary": "Reschedule a booking",
"description": "Reschedule a booking or seated booking\n\n <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>\n ",
"parameters": [
{
"name": "cal-api-version",
"in": "header",
"description": "Must be set to 2024-08-13. If not set to this value, the endpoint will default to an older version.",
"required": true,
"schema": {
"type": "string",
"default": "2024-08-13"
}
},
{
"name": "bookingUid",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "Authorization",
"in": "header",
"description": "value must be `Bearer <token>` where `<token>` is api key prefixed with cal_ or managed user access token",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "x-cal-secret-key",
"in": "header",
"description": "For platform customers - OAuth client secret key",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "x-cal-client-id",
"in": "header",
"description": "For platform customers - OAuth client ID",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"description": "Accepts different types of reschedule booking input: Reschedule Booking (Option 1) or Reschedule Seated Booking (Option 2). If you're rescheduling a seated booking as org admin of booking host, pass booking input for Reschedule Booking (Option 1) along with your access token in the request header.\n\n If you are rescheduling a seated booking for an event type with 'show attendees' disabled, then to retrieve attendees in the response either set 'show attendees' to true on event type level or\n you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/RescheduleBookingInput_2024_08_13"
},
{
"$ref": "#/components/schemas/RescheduleSeatedBookingInput_2024_08_13"
}
]
}
}
}
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RescheduleBookingOutput_2024_08_13"
}
}
}
}
},
"tags": ["Bookings"]
}
},
"/v2/bookings/{bookingUid}/cancel": {
"post": {
"operationId": "BookingsController_2024_08_13_cancelBooking",
"summary": "Cancel a booking",
"description": ":bookingUid can be :bookingUid of an usual booking, individual recurrence or recurring booking to cancel all recurrences.\n\n \nCancelling normal bookings:\n If the booking is not seated and not recurring, simply pass :bookingUid in the request URL `/bookings/:bookingUid/cancel` and optionally cancellationReason in the request body `{\"cancellationReason\": \"Will travel\"}`.\n\n \nCancelling seated bookings:\n It is possible to cancel specific seat within a booking as an attendee or all of the seats as the host.\n \n1. As an attendee - provide :bookingUid in the request URL `/bookings/:bookingUid/cancel` and seatUid in the request body `{\"seatUid\": \"123-123-123\"}` . This will remove this particular attendance from the booking.\n \n2. As the host or org admin of host - host can cancel booking for all attendees aka for every seat, this also applies to org admins. Provide :bookingUid in the request URL `/bookings/:bookingUid/cancel` and cancellationReason in the request body `{\"cancellationReason\": \"Will travel\"}` and `Authorization: Bearer token` request header where token is event type owner (host) credential. This will cancel the booking for all attendees.\n\n \nCancelling recurring seated bookings:\n For recurring seated bookings it is not possible to cancel all of them with 1 call\n like with non-seated recurring bookings by providing recurring bookind uid - you have to cancel each recurrence booking by its bookingUid + seatUid.\n\n If you are cancelling a seated booking for an event type with 'show attendees' disabled, then to retrieve attendees in the response either set 'show attendees' to true on event type level or\n you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner.\n\n <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>\n ",
"parameters": [
{
"name": "cal-api-version",
"in": "header",
"description": "Must be set to 2024-08-13. If not set to this value, the endpoint will default to an older version.",
"required": true,
"schema": {
"type": "string",
"default": "2024-08-13"
}
},
{
"name": "bookingUid",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "Authorization",
"in": "header",
"description": "value must be `Bearer <token>` where `<token>` is api key prefixed with cal_ or managed user access token",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "x-cal-secret-key",
"in": "header",
"description": "For platform customers - OAuth client secret key",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "x-cal-client-id",
"in": "header",
"description": "For platform customers - OAuth client ID",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"description": "Accepts different types of cancel booking input: Cancel Booking (Option 1 which is for normal or recurring bookings) or Cancel Seated Booking (Option 2 which is for seated bookings)",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/CancelBookingInput_2024_08_13"
},
{
"$ref": "#/components/schemas/CancelSeatedBookingInput_2024_08_13"
}
]
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CancelBookingOutput_2024_08_13"
}
}
}
}
},
"tags": ["Bookings"]
}
},
"/v2/bookings/{bookingUid}/mark-absent": {
"post": {
"operationId": "BookingsController_2024_08_13_markNoShow",
"summary": "Mark a booking absence",
"description": "The provided authorization header refers to the owner of the booking.\n\n <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>\n ",
"parameters": [
{
"name": "cal-api-version",
"in": "header",
"description": "Must be set to 2024-08-13. If not set to this value, the endpoint will default to an older version.",
"required": true,
"schema": {
"type": "string",
"default": "2024-08-13"
}
},
{
"name": "bookingUid",
"required": true,
"in": "path",
"schema": {
"type": "string"
}
},
{
"name": "Authorization",
"in": "header",
"descri
# --- truncated at 32 KB (546 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cal-com/refs/heads/main/openapi/cal-com-openapi.json