KosmoKrator

other

Acuity Scheduling Lua API for KosmoKrator Agents

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

8 functions 7 read 1 write Manual OAuth token auth
Submit Acuity Scheduling feedback View package source

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.

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 API Reference

list_appointments

List appointments with optional filters.

Parameters

NameTypeRequiredDescription
minDatestringnoEarliest appointment date (ISO 8601, e.g., "2026-01-01")
maxDatestringnoLatest appointment date (ISO 8601, e.g., "2026-12-31")
calendarIDintegernoFilter by calendar ID
appointmentTypeIDintegernoFilter by appointment type ID
maxintegernoMaximum number of results (default: 100)
directionstringnoSort direction: "asc" or "desc" (default: "desc")

Example

local result = app.integrations["acuity-scheduling"].list_appointments({
  minDate = "2026-04-01",
  maxDate = "2026-04-30",
  direction = "asc"
})

for _, appt in ipairs(result) do
  print(appt.id .. ": " .. appt.firstName .. " " .. appt.lastName .. " on " .. appt.date .. " at " .. appt.time)
end

get_appointment

Get full details of a specific appointment.

Parameters

NameTypeRequiredDescription
idintegeryesThe appointment ID

Example

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

print("Appointment: " .. result.name)
print("Date: " .. result.date .. " at " .. result.time)
print("Client: " .. result.firstName .. " " .. result.lastName)
print("Email: " .. result.email)
print("Status: " .. result.status)

list_clients

List and search clients.

Parameters

NameTypeRequiredDescription
searchstringnoSearch by name, email, or phone
emailstringnoFilter by exact email address
maxintegernoMaximum number of results

Example

local result = app.integrations["acuity-scheduling"].list_clients({
  search = "john"
})

for _, client in ipairs(result) do
  print(client.id .. ": " .. client.firstName .. " " .. client.lastName .. " (" .. client.email .. ")")
end

list_calendars

List all calendars. No parameters required.

Example

local result = app.integrations["acuity-scheduling"].list_calendars()

for _, cal in ipairs(result) do
  print(cal.id .. ": " .. cal.name .. " (timezone: " .. cal.timezone .. ")")
end

list_appointment_types

List all appointment types (services). No parameters required.

Example

local result = app.integrations["acuity-scheduling"].list_appointment_types()

for _, t in ipairs(result) do
  print(t.id .. ": " .. t.name .. " (" .. t.duration .. " min, $" .. t.price .. ")")
end

cancel_appointment

Cancel an existing appointment.

Parameters

NameTypeRequiredDescription
idintegeryesThe appointment ID to cancel

Example

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

print(result.message)

get_availability

Get available time slots for a given appointment type and date.

Parameters

NameTypeRequiredDescription
appointmentTypeIDintegeryesThe appointment type ID
datestringyesDate in YYYY-MM-DD format
calendarIDintegernoFilter by specific calendar
timezonestringnoTimezone (e.g., "America/New_York")

Example

-- First, get appointment types to find the right ID
local types = app.integrations["acuity-scheduling"].list_appointment_types()
local typeID = types[1].id

-- Then check availability
local result = app.integrations["acuity-scheduling"].get_availability({
  appointmentTypeID = typeID,
  date = "2026-04-10",
  timezone = "America/New_York"
})

for _, slot in ipairs(result) do
  print(slot.time)
end

get_current_user

Get the authenticated user’s profile. No parameters required.

Example

local result = app.integrations["acuity-scheduling"].get_current_user()

print("User: " .. result.name)
print("Email: " .. result.email)
print("Timezone: " .. result.timezone)

Multi-Account Usage

If you have multiple Acuity Scheduling accounts configured, use account-specific namespaces:

-- Default account (always works)
app.integrations["acuity-scheduling"].list_appointments({...})

-- Explicit default (portable across setups)
app.integrations["acuity-scheduling"].default.list_appointments({...})

-- Named accounts
app.integrations["acuity-scheduling"].work.list_appointments({...})
app.integrations["acuity-scheduling"].personal.list_appointments({...})

All functions are identical across accounts — only the credentials differ.

Raw agent markdown 
# Acuity Scheduling — Lua API Reference

## list_appointments

List appointments with optional filters.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `minDate` | string | no | Earliest appointment date (ISO 8601, e.g., `"2026-01-01"`) |
| `maxDate` | string | no | Latest appointment date (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 results (default: 100) |
| `direction` | string | no | Sort direction: `"asc"` or `"desc"` (default: `"desc"`) |

### Example

```lua
local result = app.integrations["acuity-scheduling"].list_appointments({
  minDate = "2026-04-01",
  maxDate = "2026-04-30",
  direction = "asc"
})

for _, appt in ipairs(result) do
  print(appt.id .. ": " .. appt.firstName .. " " .. appt.lastName .. " on " .. appt.date .. " at " .. appt.time)
end
```

---

## get_appointment

Get full details of a specific appointment.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | The appointment ID |

### Example

```lua
local result = app.integrations["acuity-scheduling"].get_appointment({
  id = 12345
})

print("Appointment: " .. result.name)
print("Date: " .. result.date .. " at " .. result.time)
print("Client: " .. result.firstName .. " " .. result.lastName)
print("Email: " .. result.email)
print("Status: " .. result.status)
```

---

## list_clients

List and search clients.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `search` | string | no | Search by name, email, or phone |
| `email` | string | no | Filter by exact email address |
| `max` | integer | no | Maximum number of results |

### Example

```lua
local result = app.integrations["acuity-scheduling"].list_clients({
  search = "john"
})

for _, client in ipairs(result) do
  print(client.id .. ": " .. client.firstName .. " " .. client.lastName .. " (" .. client.email .. ")")
end
```

---

## list_calendars

List all calendars. No parameters required.

### Example

```lua
local result = app.integrations["acuity-scheduling"].list_calendars()

for _, cal in ipairs(result) do
  print(cal.id .. ": " .. cal.name .. " (timezone: " .. cal.timezone .. ")")
end
```

---

## list_appointment_types

List all appointment types (services). No parameters required.

### Example

```lua
local result = app.integrations["acuity-scheduling"].list_appointment_types()

for _, t in ipairs(result) do
  print(t.id .. ": " .. t.name .. " (" .. t.duration .. " min, $" .. t.price .. ")")
end
```

---

## cancel_appointment

Cancel an existing appointment.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | integer | yes | The appointment ID to cancel |

### Example

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

print(result.message)
```

---

## get_availability

Get available time slots for a given appointment type and date.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `appointmentTypeID` | integer | yes | The appointment type ID |
| `date` | string | yes | Date in `YYYY-MM-DD` format |
| `calendarID` | integer | no | Filter by specific calendar |
| `timezone` | string | no | Timezone (e.g., `"America/New_York"`) |

### Example

```lua
-- First, get appointment types to find the right ID
local types = app.integrations["acuity-scheduling"].list_appointment_types()
local typeID = types[1].id

-- Then check availability
local result = app.integrations["acuity-scheduling"].get_availability({
  appointmentTypeID = typeID,
  date = "2026-04-10",
  timezone = "America/New_York"
})

for _, slot in ipairs(result) do
  print(slot.time)
end
```

---

## get_current_user

Get the authenticated user's profile. No parameters required.

### Example

```lua
local result = app.integrations["acuity-scheduling"].get_current_user()

print("User: " .. result.name)
print("Email: " .. result.email)
print("Timezone: " .. result.timezone)
```

---

## Multi-Account Usage

If you have multiple Acuity Scheduling accounts configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations["acuity-scheduling"].list_appointments({...})

-- Explicit default (portable across setups)
app.integrations["acuity-scheduling"].default.list_appointments({...})

-- Named accounts
app.integrations["acuity-scheduling"].work.list_appointments({...})
app.integrations["acuity-scheduling"].personal.list_appointments({...})
```

All functions are identical across accounts — only the credentials differ.

Metadata-Derived Lua Example

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

Functions

acuity_list_appointments

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.

Operation
Read read
Full name
acuity-scheduling.acuity_list_appointments
ParameterTypeRequiredDescription
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".

acuity_get_appointment

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

Operation
Read read
Full name
acuity-scheduling.acuity_get_appointment
ParameterTypeRequiredDescription
id integer yes The appointment ID.

acuity_list_clients

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

Operation
Read read
Full name
acuity-scheduling.acuity_list_clients
ParameterTypeRequiredDescription
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.

acuity_list_calendars

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

Operation
Read read
Full name
acuity-scheduling.acuity_list_calendars
ParameterTypeRequiredDescription
No parameters.

acuity_list_appointment_types

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.

Operation
Read read
Full name
acuity-scheduling.acuity_list_appointment_types
ParameterTypeRequiredDescription
No parameters.

acuity_cancel_appointment

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.

Operation
Write write
Full name
acuity-scheduling.acuity_cancel_appointment
ParameterTypeRequiredDescription
id integer yes The appointment ID to cancel.

acuity_get_availability

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

Operation
Read read
Full name
acuity-scheduling.acuity_get_availability
ParameterTypeRequiredDescription
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.

acuity_get_current_user

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

Operation
Read read
Full name
acuity-scheduling.acuity_get_current_user
ParameterTypeRequiredDescription
No parameters.