The SavvyCal Meetings REST API enables developers to manage scheduling links, events, webhooks, workflows, and time zones programmatically. It uses OAuth 2.0 and personal access tokens for authentication and communicates in JSON format.
openapi: 3.0.3
info:
title: SavvyCal Meetings API
description: >
The SavvyCal Meetings REST API enables developers to manage scheduling
links, events, webhooks, workflows, and time zones programmatically.
It uses OAuth 2.0 and personal access tokens for authentication and
communicates in JSON format.
version: "1.0"
contact:
name: SavvyCal Developer Support
url: https://developers.savvycal.com/
termsOfService: https://savvycal.com/legal/terms
license:
name: Proprietary
url: https://savvycal.com/
servers:
- url: https://api.savvycal.com/v1
description: SavvyCal API v1
security:
- BearerAuth: []
tags:
- name: Events
description: Manage scheduled events and bookings.
- name: Scheduling Links
description: Create and manage scheduling links for booking.
- name: Current User
description: Retrieve information about the authenticated user.
- name: Time Zones
description: List and retrieve time zone information.
- name: Webhooks
description: Configure webhooks for real-time event notifications.
- name: Workflows
description: Manage automation workflows.
paths:
/me:
get:
operationId: getCurrentUser
summary: Get current user
description: Get the currently authenticated user's profile information.
tags:
- Current User
responses:
"200":
description: Successful response with user profile.
content:
application/json:
schema:
$ref: "#/components/schemas/User"
"401":
$ref: "#/components/responses/Unauthorized"
/events:
get:
operationId: listEvents
summary: List events
description: List your events scheduled via SavvyCal.
tags:
- Events
parameters:
- name: page
in: query
description: Page number for pagination.
schema:
type: integer
minimum: 1
default: 1
- name: per_page
in: query
description: Number of results per page.
schema:
type: integer
minimum: 1
maximum: 100
default: 20
responses:
"200":
description: Paginated list of events.
content:
application/json:
schema:
$ref: "#/components/schemas/EventList"
"401":
$ref: "#/components/responses/Unauthorized"
/events/{event_id}:
get:
operationId: getEvent
summary: Get event
description: Fetch a single event by its ID.
tags:
- Events
parameters:
- $ref: "#/components/parameters/EventId"
responses:
"200":
description: Event details.
content:
application/json:
schema:
$ref: "#/components/schemas/Event"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
/events/{event_id}/cancel:
post:
operationId: cancelEvent
summary: Cancel event
description: Cancel an event by its ID.
tags:
- Events
parameters:
- $ref: "#/components/parameters/EventId"
requestBody:
required: false
content:
application/json:
schema:
$ref: "#/components/schemas/CancelEventRequest"
responses:
"200":
description: Event successfully canceled.
content:
application/json:
schema:
$ref: "#/components/schemas/Event"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
/links/{link_id}/events:
post:
operationId: createEvent
summary: Create event
description: >
Create a new event via a scheduling link. You can only create events
that match an available time slot for the underlying scheduling link.
Use the List Available Slots endpoint to find suitable times.
tags:
- Events
parameters:
- $ref: "#/components/parameters/LinkId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateEventRequest"
responses:
"200":
description: Event successfully created.
content:
application/json:
schema:
$ref: "#/components/schemas/Event"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
"422":
$ref: "#/components/responses/UnprocessableEntity"
/links:
get:
operationId: listSchedulingLinks
summary: List scheduling links
description: Get a paginated list of scheduling links for the authenticated user.
tags:
- Scheduling Links
parameters:
- name: page
in: query
description: Page number for pagination.
schema:
type: integer
minimum: 1
default: 1
- name: per_page
in: query
description: Number of results per page.
schema:
type: integer
minimum: 1
maximum: 100
default: 20
responses:
"200":
description: Paginated list of scheduling links.
content:
application/json:
schema:
$ref: "#/components/schemas/LinkList"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
/links/{link_id}:
get:
operationId: getSchedulingLink
summary: Get scheduling link
description: Get a specific scheduling link by ID.
tags:
- Scheduling Links
parameters:
- $ref: "#/components/parameters/LinkId"
responses:
"200":
description: Scheduling link details.
content:
application/json:
schema:
$ref: "#/components/schemas/Link"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
patch:
operationId: updateSchedulingLink
summary: Update scheduling link
description: Update an existing scheduling link.
tags:
- Scheduling Links
parameters:
- $ref: "#/components/parameters/LinkId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateLinkRequest"
responses:
"200":
description: Updated scheduling link.
content:
application/json:
schema:
$ref: "#/components/schemas/Link"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"422":
$ref: "#/components/responses/UnprocessableEntity"
/time_zones:
get:
operationId: listTimeZones
summary: List time zones
description: Get a list of time zones with localized names and DST information.
tags:
- Time Zones
responses:
"200":
description: List of time zones.
content:
application/json:
schema:
$ref: "#/components/schemas/TimeZoneList"
"401":
$ref: "#/components/responses/Unauthorized"
/time_zones/{segments}:
get:
operationId: getTimeZone
summary: Get time zone
description: Get detailed information about a specific time zone.
tags:
- Time Zones
parameters:
- name: segments
in: path
required: true
description: >
The time zone identifier path segments (e.g., "America/New_York").
schema:
type: string
example: America/New_York
responses:
"200":
description: Time zone details.
content:
application/json:
schema:
$ref: "#/components/schemas/TimeZone"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
/webhooks:
get:
operationId: listWebhooks
summary: List webhooks
description: Get a paginated list of webhooks for the authenticated user.
tags:
- Webhooks
parameters:
- name: page
in: query
description: Page number for pagination.
schema:
type: integer
minimum: 1
default: 1
- name: per_page
in: query
description: Number of results per page.
schema:
type: integer
minimum: 1
maximum: 100
default: 20
responses:
"200":
description: Paginated list of webhooks.
content:
application/json:
schema:
$ref: "#/components/schemas/WebhookList"
"401":
$ref: "#/components/responses/Unauthorized"
post:
operationId: createWebhook
summary: Create webhook
description: Create a new webhook for receiving event notifications.
tags:
- Webhooks
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateWebhookRequest"
responses:
"201":
description: Webhook successfully created.
content:
application/json:
schema:
$ref: "#/components/schemas/Webhook"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
/webhooks/{webhook_id}:
get:
operationId: getWebhook
summary: Get webhook
description: Get a specific webhook by ID.
tags:
- Webhooks
parameters:
- $ref: "#/components/parameters/WebhookId"
responses:
"200":
description: Webhook details.
content:
application/json:
schema:
$ref: "#/components/schemas/Webhook"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
delete:
operationId: deleteWebhook
summary: Delete webhook
description: Delete an existing webhook.
tags:
- Webhooks
parameters:
- $ref: "#/components/parameters/WebhookId"
responses:
"200":
description: Webhook successfully deleted.
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
/workflows:
get:
operationId: listWorkflows
summary: List workflows
description: >
Get a paginated list of workflows for scopes the authenticated user manages.
tags:
- Workflows
parameters:
- name: page
in: query
description: Page number for pagination.
schema:
type: integer
minimum: 1
default: 1
- name: per_page
in: query
description: Number of results per page.
schema:
type: integer
minimum: 1
maximum: 100
default: 20
responses:
"200":
description: Paginated list of workflows.
content:
application/json:
schema:
$ref: "#/components/schemas/WorkflowList"
"401":
$ref: "#/components/responses/Unauthorized"
/workflows/{workflow_id}:
get:
operationId: getWorkflow
summary: Get workflow
description: Get a specific workflow by ID.
tags:
- Workflows
parameters:
- name: workflow_id
in: path
required: true
description: The unique identifier of the workflow.
schema:
type: string
responses:
"200":
description: Workflow details.
content:
application/json:
schema:
$ref: "#/components/schemas/Workflow"
"401":
$ref: "#/components/responses/Unauthorized"
"404":
$ref: "#/components/responses/NotFound"
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >
Personal access tokens (prefixed with `pt_secret_`) or OAuth 2.0
access tokens. Include in the Authorization header as:
`Authorization: Bearer <token>`
parameters:
EventId:
name: event_id
in: path
required: true
description: The unique identifier of the event.
schema:
type: string
LinkId:
name: link_id
in: path
required: true
description: The unique identifier of the scheduling link.
schema:
type: string
WebhookId:
name: webhook_id
in: path
required: true
description: The unique identifier of the webhook.
schema:
type: string
responses:
BadRequest:
description: Invalid request parameters.
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
Unauthorized:
description: Authentication credentials missing or invalid.
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
Forbidden:
description: Insufficient permissions to access the resource.
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
UnprocessableEntity:
description: Validation errors.
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
schemas:
Error:
type: object
description: Standard error response.
properties:
error:
type: string
description: Human-readable error message.
errors:
type: object
description: Field-level validation errors.
additionalProperties:
type: array
items:
type: string
User:
type: object
description: A SavvyCal user account.
properties:
id:
type: string
description: Unique user identifier.
email:
type: string
format: email
description: User's email address.
first_name:
type: string
description: User's first name.
last_name:
type: string
description: User's last name.
display_name:
type: string
description: User's full display name.
time_zone:
type: string
description: User's configured time zone identifier.
example: America/New_York
time_format:
type: string
description: User's preferred time format.
enum: ["12hr", "24hr"]
first_day_of_week:
type: integer
description: "First day of week (0=Sunday, 6=Saturday)."
minimum: 0
maximum: 6
plan:
type: string
description: User's current subscription plan.
enum: [free, basic, premium]
avatar_url:
type: string
format: uri
nullable: true
description: URL to the user's avatar image.
EventAttendee:
type: object
description: An attendee of a scheduled event.
properties:
id:
type: string
description: Unique attendee identifier.
name:
type: string
description: Attendee's name.
email:
type: string
format: email
description: Attendee's email address.
time_zone:
type: string
description: Attendee's time zone.
status:
type: string
description: Attendee's response status.
enum: [accepted, declined, tentative, awaiting]
Payment:
type: object
description: Payment information associated with an event.
properties:
amount:
type: number
description: Payment amount.
state:
type: string
description: Payment state.
enum: [awaiting_checkout, paid]
stripe_dashboard_url:
type: string
format: uri
nullable: true
description: Link to the Stripe dashboard record.
Conferencing:
type: object
description: Video conferencing details for an event.
properties:
join_url:
type: string
format: uri
nullable: true
description: URL to join the video call.
meeting_id:
type: string
nullable: true
description: Meeting ID for the video call.
integration_type:
type: string
description: The conferencing integration type (e.g., zoom, google_meet).
example: zoom
Scope:
type: object
description: A team or organizational scope.
properties:
id:
type: string
description: Unique scope identifier.
name:
type: string
description: Scope name.
slug:
type: string
description: URL slug for the scope.
Event:
type: object
description: A scheduled event/booking on SavvyCal.
properties:
id:
type: string
description: Unique event identifier.
status:
type: string
description: Current status of the event.
enum:
- confirmed
- canceled
- awaiting_reschedule
- awaiting_checkout
- awaiting_approval
start_time:
type: string
format: date-time
description: Event start time (ISO 8601).
end_time:
type: string
format: date-time
description: Event end time (ISO 8601).
duration:
type: integer
description: Event duration in minutes.
buffer_before:
type: integer
description: Buffer time before the event in minutes.
nullable: true
buffer_after:
type: integer
description: Buffer time after the event in minutes.
nullable: true
original_start_time:
type: string
format: date-time
nullable: true
description: Original start time if the event was rescheduled.
attendees:
type: array
description: All event attendees.
items:
$ref: "#/components/schemas/EventAttendee"
conferencing:
$ref: "#/components/schemas/Conferencing"
payment:
$ref: "#/components/schemas/Payment"
nullable: true
scope:
$ref: "#/components/schemas/Scope"
nullable: true
created_at:
type: string
format: date-time
description: When the event was created.
updated_at:
type: string
format: date-time
description: When the event was last updated.
EventList:
type: object
description: Paginated list of events.
properties:
data:
type: array
items:
$ref: "#/components/schemas/Event"
meta:
$ref: "#/components/schemas/PaginationMeta"
CancelEventRequest:
type: object
description: Request body for canceling an event.
properties:
reason:
type: string
description: Optional reason for canceling the event.
CreateEventRequest:
type: object
description: Request body for creating a new event via a scheduling link.
required:
- start_time
- attendee
properties:
start_time:
type: string
format: date-time
description: >
The start time for the event. Must match an available slot for
the scheduling link.
attendee:
type: object
description: Primary attendee information.
required:
- name
- email
properties:
name:
type: string
description: Attendee's full name.
email:
type: string
format: email
description: Attendee's email address.
time_zone:
type: string
description: Attendee's time zone.
example: America/Chicago
duration:
type: integer
description: Desired duration in minutes (must be one of the link's allowed durations).
fields:
type: object
description: Custom form field responses keyed by field ID.
additionalProperties: true
LinkField:
type: object
description: A custom form field on a scheduling link.
properties:
id:
type: string
description: Field identifier.
label:
type: string
description: Field label shown to the booker.
type:
type: string
description: Field input type.
enum: [text, textarea, select, checkbox, phone]
required:
type: boolean
description: Whether the field is required.
Link:
type: object
description: A SavvyCal scheduling link for booking appointments.
properties:
id:
type: string
description: Unique link identifier.
slug:
type: string
description: URL slug for the scheduling link.
name:
type: string
description: Public-facing name of the scheduling link.
private_name:
type: string
description: Owner-only name for the link.
nullable: true
description:
type: string
nullable: true
description: Optional description shown to bookers.
state:
type: string
description: Current state of the scheduling link.
enum: [active, pending, disabled]
default_duration:
type: integer
description: Default meeting duration in minutes.
durations:
type: array
description: Array of available meeting durations in minutes.
items:
type: integer
increment:
type: integer
description: Time slot interval in minutes.
fields:
type: array
description: Custom booking form fields.
items:
$ref: "#/components/schemas/LinkField"
scope:
$ref: "#/components/schemas/Scope"
nullable: true
created_at:
type: string
format: date-time
description: When the link was created.
updated_at:
type: string
format: date-time
description: When the link was last updated.
LinkList:
type: object
description: Paginated list of scheduling links.
properties:
data:
type: array
items:
$ref: "#/components/schemas/Link"
meta:
$ref: "#/components/schemas/PaginationMeta"
UpdateLinkRequest:
type: object
description: Request body for updating a scheduling link (all fields optional).
properties:
name:
type: string
description: New public-facing name.
private_name:
type: string
description: New owner-only name.
description:
type: string
description: New description.
state:
type: string
enum: [active, pending, disabled]
description: New state for the link.
default_duration:
type: integer
description: New default duration in minutes.
durations:
type: array
items:
type: integer
description: New set of available durations in minutes.
increment:
type: integer
description: New time slot interval in minutes.
TimeZone:
type: object
description: A time zone with localized name and DST information.
properties:
identifier:
type: string
description: IANA time zone identifier.
example: America/New_York
name:
type: string
description: Localized display name for the time zone.
example: Eastern Time (US & Canada)
utc_offset:
type: string
description: Current UTC offset (e.g., "-05:00").
example: "-05:00"
dst:
type: boolean
description: Whether daylight saving time is currently active.
TimeZoneList:
type: object
description: List of time zones.
properties:
data:
type: array
items:
$ref: "#/components/schemas/TimeZone"
Webhook:
type: object
description: A webhook configuration for receiving SavvyCal event notifications.
properties:
id:
type: string
description: Unique webhook identifier.
url:
type: string
format: uri
description: The endpoint URL where notifications are sent.
secret:
type: string
description: >
Secret used for authenticating webhook payloads via
HMAC-SHA256 signature in the x-savvycal-signature header.
state:
type: string
description: Current webhook state.
enum: [active, disabled, deleted]
version:
type: string
description: Payload format version.
example: "2020-11-18"
created_at:
type: string
format: date-time
description: When the webhook was created.
WebhookList:
type: object
description: Paginated list of webhooks.
properties:
data:
type: array
items:
$ref: "#/components/schemas/Webhook"
meta:
$ref: "#/components/schemas/PaginationMeta"
CreateWebhookRequest:
type: object
description: Request body for creating a new webhook.
required:
- url
properties:
url:
type: string
format: uri
description: The endpoint URL to receive webhook notifications.
events:
type: array
description: List of event types to subscribe to. Subscribes to all if omitted.
items:
type: string
enum:
- event.created
- event.requested
- event.approved
- event.declined
- event.rescheduled
- event.changed
- event.canceled
- event.checkout.pending
- event.checkout.expired
- event.checkout.completed
- event.attendee.added
- event.attendee.canceled
- event.attendee.rescheduled
- poll.response.created
- poll.response.updated
- workflow.action.triggered
Workflow:
type: object
description: An automation workflow in SavvyCal.
properties:
id:
type: string
description: Unique workflow identifier.
name:
type: string
description: Workflow name.
state:
type: string
description: Current workflow state.
enum: [active, disabled]
scope:
$ref: "#/components/schemas/Scope"
nullable: true
created_at:
type: string
format: date-time
description: When the workflow was created.
updated_at:
type: string
format: date-time
description: When the workflow was last updated.
WorkflowList:
type: object
description: Paginated list of workflows.
properties:
data:
type: array
items:
$ref: "#/components/schemas/Workflow"
meta:
$ref: "#/components/schemas/PaginationMeta"
PaginationMeta:
type: object
description: Pagination metadata for list responses.
properties:
current_page:
type: integer
description: Current page number.
per_page:
type: integer
description: Number of items per page.
total_count:
type: integer
description: Total number of items.
total_pages:
type: integer
description: Total number of pages.