Can I use Acuity Scheduling as a CLI?

Yes. KosmoKrator exposes a Acuity Scheduling CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Acuity Scheduling through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Acuity Scheduling tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Acuity Scheduling credentials stored?

Acuity Scheduling credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Acuity Scheduling MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

productivity

Acuity Scheduling Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Acuity Scheduling KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.acuity_scheduling.*. Use lua_read_doc("integrations.acuity-scheduling") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Acuity Scheduling workflow without starting an interactive agent session.

Inline Lua call

kosmo integrations:lua --eval 'dump(app.integrations.acuity_scheduling.list_appointments({minDate = "example_minDate", maxDate = "example_maxDate", calendarID = 1, appointmentTypeID = 1, max = 1, direction = "example_direction"}))' --json

Read Lua docs headlessly

kosmo integrations:lua --eval 'print(docs.read("acuity-scheduling"))' --json
kosmo integrations:lua --eval 'print(docs.read("acuity-scheduling.list_appointments"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua

local acuity_scheduling = app.integrations.acuity_scheduling
local result = acuity_scheduling.list_appointments({minDate = "example_minDate", maxDate = "example_maxDate", calendarID = 1, appointmentTypeID = 1, max = 1, direction = "example_direction"})

dump(result)

Run the workflow

kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json

Namespace note. integrations:lua exposes app.integrations.acuity_scheduling, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.acuity_scheduling.default.* or app.integrations.acuity_scheduling.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Acuity Scheduling, use the narrower mcp:lua command.

MCP Lua command

# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Acuity Scheduling Lua Reference

Namespace: acuity-scheduling

Acuity Scheduling tools target the API v1 base URL https://acuityscheduling.com/api/v1. For one Acuity account, configure Basic Auth with numeric user_id and api_key. OAuth bearer tokens are also supported for multi-user applications.

Core Appointments

local appointments = app.integrations["acuity-scheduling"].list_appointments({
  minDate = "2026-05-01",
  maxDate = "2026-05-31",
  direction = "ASC",
})

local appointment = app.integrations["acuity-scheduling"].get_appointment({ id = 12345 })
local payments = app.integrations["acuity-scheduling"].list_appointment_payments({ id = 12345 })

Create, update, cancel, and reschedule appointments:

local created = app.integrations["acuity-scheduling"].create_appointment({
  body = {
    datetime = "2026-05-07T10:00:00-0400",
    appointmentTypeID = 123,
    firstName = "Jane",
    lastName = "Example",
    email = "jane@example.test",
    timezone = "America/New_York",
  },
})

local updated = app.integrations["acuity-scheduling"].update_appointment({
  id = 12345,
  body = { notes = "Prefers video call." },
})

local rescheduled = app.integrations["acuity-scheduling"].reschedule_appointment({
  id = 12345,
  body = { datetime = "2026-05-08T10:00:00-0400", admin = true, noEmail = true },
})

local cancelled = app.integrations["acuity-scheduling"].cancel_appointment({ id = 12345 })

Clients And Setup Data

local clients = app.integrations["acuity-scheduling"].list_clients({
  email = "jane@example.test",
})

local client = app.integrations["acuity-scheduling"].create_client({
  body = { firstName = "Jane", lastName = "Example", email = "jane@example.test" },
})

local calendars = app.integrations["acuity-scheduling"].list_calendars({})
local types = app.integrations["acuity-scheduling"].list_appointment_types({})
local forms = app.integrations["acuity-scheduling"].list_forms({})

Availability

Use dates and times together when building a booking flow.

local dates = app.integrations["acuity-scheduling"].get_availability_dates({
  params = { appointmentTypeID = 123, month = "2026-05" },
})

local times = app.integrations["acuity-scheduling"].get_availability({
  appointmentTypeID = 123,
  date = "2026-05-07",
  timezone = "America/New_York",
})

local classes = app.integrations["acuity-scheduling"].get_availability_classes({
  params = { month = "2026-05" },
})

Store, Blocks, And Webhooks

local products = app.integrations["acuity-scheduling"].list_products({})
local orders = app.integrations["acuity-scheduling"].list_orders({})
local order = app.integrations["acuity-scheduling"].get_order({ id = 987 })

local certificate = app.integrations["acuity-scheduling"].create_certificate({
  body = { productID = 55, email = "jane@example.test" },
})

local block = app.integrations["acuity-scheduling"].create_block({
  body = { calendarID = 1, start = "2026-05-07T13:00:00-0400", end = "2026-05-07T14:00:00-0400" },
})

local webhooks = app.integrations["acuity-scheduling"].list_webhooks({})
local webhook = app.integrations["acuity-scheduling"].create_webhook({
  body = { event = "appointment.scheduled", target = "https://example.test/acuity" },
})

Generic API

Use generic tools for Acuity API v1 endpoints without dedicated wrappers:

local result = app.integrations["acuity-scheduling"].api_get({
  path = "/forms",
})

local posted = app.integrations["acuity-scheduling"].api_post({
  path = "/webhooks",
  body = { event = "appointment.changed", target = "https://example.test/acuity" },
})

Generic write tools:

api_post({ path, body })
api_put({ path, body })
api_delete({ path, body })

Raw agent markdown

# Acuity Scheduling Lua Reference

Namespace: `acuity-scheduling`

Acuity Scheduling tools target the API v1 base URL
`https://acuityscheduling.com/api/v1`. For one Acuity account, configure Basic
Auth with numeric `user_id` and `api_key`. OAuth bearer tokens are also
supported for multi-user applications.

## Core Appointments

```lua
local appointments = app.integrations["acuity-scheduling"].list_appointments({
  minDate = "2026-05-01",
  maxDate = "2026-05-31",
  direction = "ASC",
})

local appointment = app.integrations["acuity-scheduling"].get_appointment({ id = 12345 })
local payments = app.integrations["acuity-scheduling"].list_appointment_payments({ id = 12345 })
```

Create, update, cancel, and reschedule appointments:

```lua
local created = app.integrations["acuity-scheduling"].create_appointment({
  body = {
    datetime = "2026-05-07T10:00:00-0400",
    appointmentTypeID = 123,
    firstName = "Jane",
    lastName = "Example",
    email = "jane@example.test",
    timezone = "America/New_York",
  },
})

local updated = app.integrations["acuity-scheduling"].update_appointment({
  id = 12345,
  body = { notes = "Prefers video call." },
})

local rescheduled = app.integrations["acuity-scheduling"].reschedule_appointment({
  id = 12345,
  body = { datetime = "2026-05-08T10:00:00-0400", admin = true, noEmail = true },
})

local cancelled = app.integrations["acuity-scheduling"].cancel_appointment({ id = 12345 })
```

## Clients And Setup Data

```lua
local clients = app.integrations["acuity-scheduling"].list_clients({
  email = "jane@example.test",
})

local client = app.integrations["acuity-scheduling"].create_client({
  body = { firstName = "Jane", lastName = "Example", email = "jane@example.test" },
})

local calendars = app.integrations["acuity-scheduling"].list_calendars({})
local types = app.integrations["acuity-scheduling"].list_appointment_types({})
local forms = app.integrations["acuity-scheduling"].list_forms({})
```

## Availability

Use dates and times together when building a booking flow.

```lua
local dates = app.integrations["acuity-scheduling"].get_availability_dates({
  params = { appointmentTypeID = 123, month = "2026-05" },
})

local times = app.integrations["acuity-scheduling"].get_availability({
  appointmentTypeID = 123,
  date = "2026-05-07",
  timezone = "America/New_York",
})

local classes = app.integrations["acuity-scheduling"].get_availability_classes({
  params = { month = "2026-05" },
})
```

## Store, Blocks, And Webhooks

```lua
local products = app.integrations["acuity-scheduling"].list_products({})
local orders = app.integrations["acuity-scheduling"].list_orders({})
local order = app.integrations["acuity-scheduling"].get_order({ id = 987 })

local certificate = app.integrations["acuity-scheduling"].create_certificate({
  body = { productID = 55, email = "jane@example.test" },
})

local block = app.integrations["acuity-scheduling"].create_block({
  body = { calendarID = 1, start = "2026-05-07T13:00:00-0400", end = "2026-05-07T14:00:00-0400" },
})

local webhooks = app.integrations["acuity-scheduling"].list_webhooks({})
local webhook = app.integrations["acuity-scheduling"].create_webhook({
  body = { event = "appointment.scheduled", target = "https://example.test/acuity" },
})
```

## Generic API

Use generic tools for Acuity API v1 endpoints without dedicated wrappers:

```lua
local result = app.integrations["acuity-scheduling"].api_get({
  path = "/forms",
})

local posted = app.integrations["acuity-scheduling"].api_post({
  path = "/webhooks",
  body = { event = "appointment.changed", target = "https://example.test/acuity" },
})
```

Generic write tools:

- `api_post({ path, body })`
- `api_put({ path, body })`
- `api_delete({ path, body })`

Metadata-derived Lua example

local result = app.integrations.acuity_scheduling.list_appointments({minDate = "example_minDate", maxDate = "example_maxDate", calendarID = 1, appointmentTypeID = 1, max = 1, direction = "example_direction"})
print(result)

Functions

list_appointments Read

List appointments from Acuity Scheduling. Returns upcoming and past appointments with client details, date/time, and status. Use filters to narrow results by date range, calendar, or appointment type.

Lua path: app.integrations.acuity_scheduling.list_appointments
Full name: acuity-scheduling.acuity_list_appointments

Parameter	Type	Required	Description
`minDate`	string	no	Earliest appointment date to return (ISO 8601, e.g., "2026-01-01").
`maxDate`	string	no	Latest appointment date to return (ISO 8601, e.g., "2026-12-31").
`calendarID`	integer	no	Filter by calendar ID.
`appointmentTypeID`	integer	no	Filter by appointment type ID.
`max`	integer	no	Maximum number of appointments to return (default: 100).
`direction`	string	no	Sort direction: "asc" (oldest first) or "desc" (newest first). Default: "desc".

get_appointment Read

Get full details of a specific appointment in Acuity Scheduling by its ID. Returns client info, date/time, location, forms, and status.

Lua path: app.integrations.acuity_scheduling.get_appointment
Full name: acuity-scheduling.acuity_get_appointment

Parameter	Type	Required	Description
`id`	integer	yes	The appointment ID.

create_appointment Write

Create an appointment in Acuity Scheduling.

Lua path: app.integrations.acuity_scheduling.create_appointment
Full name: acuity-scheduling.acuity_create_appointment

Parameter	Type	Required	Description
`body`	object	yes	Appointment body with datetime, appointmentTypeID, firstName, lastName, email, and optional calendarID, timezone, fields, notes, labels, or smsOptIn.

update_appointment Write

Update editable Acuity Scheduling appointment details such as client info, notes, fields, labels, or smsOptIn.

Lua path: app.integrations.acuity_scheduling.update_appointment
Full name: acuity-scheduling.acuity_update_appointment

Parameter	Type	Required	Description
`id`	integer	yes	Appointment ID.
`body`	object	yes	Editable appointment fields.

reschedule_appointment Write

Reschedule an appointment to a new datetime, calendar, or both.

Lua path: app.integrations.acuity_scheduling.reschedule_appointment
Full name: acuity-scheduling.acuity_reschedule_appointment

Parameter	Type	Required	Description
`id`	integer	yes	Appointment ID.
`body`	object	yes	Reschedule payload such as datetime, calendarID, admin, and noEmail.

list_appointment_payments Read

Retrieve payment transactions for a specific Acuity Scheduling appointment.

Lua path: app.integrations.acuity_scheduling.list_appointment_payments
Full name: acuity-scheduling.acuity_list_appointment_payments

Parameter	Type	Required	Description
`id`	integer	yes	Appointment ID.

list_clients Read

List clients from Acuity Scheduling. Search by name, email, or phone. Returns client contact information and history.

Lua path: app.integrations.acuity_scheduling.list_clients
Full name: acuity-scheduling.acuity_list_clients

Parameter	Type	Required	Description
`search`	string	no	Search query to filter clients by name, email, or phone.
`email`	string	no	Filter clients by exact email address.
`max`	integer	no	Maximum number of clients to return.

create_client Write

Create a new Acuity Scheduling client record.

Lua path: app.integrations.acuity_scheduling.create_client
Full name: acuity-scheduling.acuity_create_client

Parameter	Type	Required	Description
`body`	object	yes	Client body such as firstName, lastName, email, and phone.

update_client Write

Update an Acuity Scheduling client by lookup parameters and replacement fields.

Lua path: app.integrations.acuity_scheduling.update_client
Full name: acuity-scheduling.acuity_update_client

Parameter	Type	Required	Description
`lookup`	object	yes	Query parameters used to identify the client, such as email.
`body`	object	yes	Client fields to update.

list_calendars Read

List all calendars in Acuity Scheduling. Returns calendar IDs, names, and timezone info. Use calendar IDs to filter appointments.

Lua path: app.integrations.acuity_scheduling.list_calendars
Full name: acuity-scheduling.acuity_list_calendars

Parameter	Type	Required	Description
No parameters.

list_appointment_types Read

List all appointment types (services) in Acuity Scheduling. Returns type IDs, names, duration, price, and category. Use type IDs to filter appointments or check availability.

Lua path: app.integrations.acuity_scheduling.list_appointment_types
Full name: acuity-scheduling.acuity_list_appointment_types

Parameter	Type	Required	Description
No parameters.

cancel_appointment Write

Cancel an existing appointment in Acuity Scheduling. Requires the appointment ID. The appointment will be marked as cancelled and the client will be notified according to notification settings.

Lua path: app.integrations.acuity_scheduling.cancel_appointment
Full name: acuity-scheduling.acuity_cancel_appointment

Parameter	Type	Required	Description
`id`	integer	yes	The appointment ID to cancel.

get_availability Read

Get available time slots for booking in Acuity Scheduling. Returns open times for a given appointment type, date, and optional calendar.

Lua path: app.integrations.acuity_scheduling.get_availability
Full name: acuity-scheduling.acuity_get_availability

Parameter	Type	Required	Description
`appointmentTypeID`	integer	yes	The appointment type ID to check availability for.
`date`	string	yes	The date to check availability for (YYYY-MM-DD format, e.g., "2026-04-10").
`calendarID`	integer	no	Filter availability for a specific calendar.
`timezone`	string	no	Timezone for the returned times (e.g., "America/New_York"). Defaults to the account timezone.

get_availability_dates Read

Return dates with availability for a month and appointment type.

Lua path: app.integrations.acuity_scheduling.get_availability_dates
Full name: acuity-scheduling.acuity_get_availability_dates

Parameter	Type	Required	Description
`params`	object	yes	Query parameters such as appointmentTypeID and month.

get_availability_classes Read

Return available classes for a month.

Lua path: app.integrations.acuity_scheduling.get_availability_classes
Full name: acuity-scheduling.acuity_get_availability_classes

Parameter	Type	Required	Description
`params`	object	no	Query parameters such as appointmentTypeID and month.

list_forms Read

List intake forms and their fields from Acuity Scheduling.

Lua path: app.integrations.acuity_scheduling.list_forms
Full name: acuity-scheduling.acuity_list_forms

Parameter	Type	Required	Description
No parameters.

list_products Read

List products and packages from Acuity Scheduling.

Lua path: app.integrations.acuity_scheduling.list_products
Full name: acuity-scheduling.acuity_list_products

Parameter	Type	Required	Description
No parameters.

list_orders Read

List package, gift certificate, subscription, and product orders from Acuity Scheduling.

Lua path: app.integrations.acuity_scheduling.list_orders
Full name: acuity-scheduling.acuity_list_orders

Parameter	Type	Required	Description
`params`	object	no	Optional order query parameters.

get_order Read

Get details about a single Acuity Scheduling order by ID.

Lua path: app.integrations.acuity_scheduling.get_order
Full name: acuity-scheduling.acuity_get_order

Parameter	Type	Required	Description
`id`	integer	yes	Order ID.

create_certificate Write

Create a package or coupon certificate code in Acuity Scheduling.

Lua path: app.integrations.acuity_scheduling.create_certificate
Full name: acuity-scheduling.acuity_create_certificate

Parameter	Type	Required	Description
`body`	object	yes	Certificate body. Submit productID or couponID, with optional certificate and email.

list_blocks Read

List blocked-off times for the authenticated Acuity Scheduling user.

Lua path: app.integrations.acuity_scheduling.list_blocks
Full name: acuity-scheduling.acuity_list_blocks

Parameter	Type	Required	Description
`params`	object	no	Optional block query parameters.

create_block Write

Block off time on an Acuity Scheduling calendar.

Lua path: app.integrations.acuity_scheduling.create_block
Full name: acuity-scheduling.acuity_create_block

Parameter	Type	Required	Description
`body`	object	yes	Block body with date/time, calendar, and duration fields accepted by Acuity.

delete_block Write

Delete a blocked-off time by ID.

Lua path: app.integrations.acuity_scheduling.delete_block
Full name: acuity-scheduling.acuity_delete_block

Parameter	Type	Required	Description
`id`	integer	yes	Block ID.

list_webhooks Read

List dynamic webhook subscriptions in Acuity Scheduling.

Lua path: app.integrations.acuity_scheduling.list_webhooks
Full name: acuity-scheduling.acuity_list_webhooks

Parameter	Type	Required	Description
No parameters.

create_webhook Write

Create a dynamic webhook subscription for Acuity Scheduling events.

Lua path: app.integrations.acuity_scheduling.create_webhook
Full name: acuity-scheduling.acuity_create_webhook

Parameter	Type	Required	Description
`body`	object	yes	Webhook body with event and target URL.

delete_webhook Write

Delete a dynamic webhook subscription by ID.

Lua path: app.integrations.acuity_scheduling.delete_webhook
Full name: acuity-scheduling.acuity_delete_webhook

Parameter	Type	Required	Description
`id`	integer	yes	Webhook ID.

api_get Read

Call any Acuity Scheduling API v1 GET endpoint.

Lua path: app.integrations.acuity_scheduling.api_get
Full name: acuity-scheduling.acuity_api_get

Parameter	Type	Required	Description
`path`	string	yes	API path such as /forms or /orders.
`params`	object	no	Query parameters.

api_post Write

Call any Acuity Scheduling API v1 POST endpoint.

Lua path: app.integrations.acuity_scheduling.api_post
Full name: acuity-scheduling.acuity_api_post

Parameter	Type	Required	Description
`path`	string	yes	API path.
`body`	object	no	JSON body.

api_put Write

Call any Acuity Scheduling API v1 PUT endpoint.

Lua path: app.integrations.acuity_scheduling.api_put
Full name: acuity-scheduling.acuity_api_put

Parameter	Type	Required	Description
`path`	string	yes	API path.
`body`	object	no	JSON body.

api_delete Write

Call any Acuity Scheduling API v1 DELETE endpoint.

Lua path: app.integrations.acuity_scheduling.api_delete
Full name: acuity-scheduling.acuity_api_delete

Parameter	Type	Required	Description
`path`	string	yes	API path.
`body`	object	no	JSON body.

get_current_user Read

Get the currently authenticated Acuity Scheduling user profile. Returns user name, email, timezone, and account details.

Lua path: app.integrations.acuity_scheduling.get_current_user
Full name: acuity-scheduling.acuity_get_current_user

Parameter	Type	Required	Description
No parameters.