Acuity Scheduling

Lightweight, dependency-free, in-memory Acuity Scheduling API fake for testing scheduling code.

Default port: 4850

Quick start

import { AcuitySchedulingServer } from "./services/acuity-scheduling/src/server.js";

const server = new AcuitySchedulingServer(4850);
await server.start();
// ... run your app/tests ...
await server.stop();

Point an Acuity client at http://127.0.0.1:4850. Authenticate with HTTP Basic auth using userId:apiKey (any non-empty Basic credentials accepted):

const basic = Buffer.from("parlel:parlel").toString("base64");
const res = await fetch("http://127.0.0.1:4850/api/v1/me", {
  headers: { Authorization: `Basic ${basic}` },
});

Implemented operations

All /api/v1/* routes require HTTP Basic auth (numeric userId : apiKey), matching the real Acuity Scheduling API. Requests and responses use JSON. State is in-memory. Created appointments use the real Acuity appointment shape:

{ "id": 1000001, "firstName": "Alice", "lastName": "Smith", "phone": "",
  "email": "alice@parlel.dev", "date": "June 1, 2024", "time": "9:00am",
  "endTime": "9:30am", "datetime": "2024-06-01T09:00:00-0000",
  "price": "0.00", "paid": "no", "amountPaid": "0.00",
  "type": "Initial Consultation", "appointmentTypeID": 1, "classID": null,
  "category": "", "duration": "30", "calendar": "Parlel", "calendarID": 1,
  "location": "", "certificate": null, "confirmationPage": "https://...",
  "formsText": "", "notes": "", "timezone": "UTC", "canceled": false,
  "forms": [], "labels": [] }

• GET /api/v1/meta — public service metadata ({ "hooks": [] }), no auth required.
• GET /api/v1/me — the authenticated account (parlel convenience; Acuity has no /me).
• GET /api/v1/appointment-types — list appointment types.
• GET /api/v1/availability/dates?month=YYYY-MM — available dates (deterministic).
• GET /api/v1/availability/times?date=&appointmentTypeID= — available times (deterministic).
• GET /api/v1/appointments — list appointments. Canceled appointments are excluded by default; pass ?canceled=true for canceled only or ?showall=true for both.
• POST /api/v1/appointments — create (book) an appointment. Required attributes, validated in order: datetime, appointmentTypeID, firstName, lastName, email. An unknown appointmentTypeID is rejected. Form values may be supplied via the fields array ([{ "id": 1, "value": "..." }]) and are echoed back in the forms array using the real { id, name, values: [{ value, name, fieldID, id }] } shape.
• GET /api/v1/appointments/:id — retrieve an appointment.
• PUT /api/v1/appointments/:id — update appointment details from the real white-list: firstName, lastName, phone, email, certificate, notes, fields, labels, smsOptIn. datetime is not updatable here (Acuity rescheduling is a separate endpoint).
• PUT /api/v1/appointments/:id/cancel — cancel an appointment (canceled: true).

Service & inspection (parlel extensions)

• GET / — service metadata.
• GET /health — health check.
• POST /__parlel/reset — reset state.
• OPTIONS * — CORS preflight (204).

Access via MCP / preview URL

The emulator is reachable at ACUITY_SCHEDULING_BASE_URL (http://127.0.0.1:4850). When running in the parlel pool, an MCP tool / preview URL proxies to this base URL — point your Acuity client at that URL with Basic auth and every /api/v1/* endpoint above works as documented.

Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ fully supported · ◐ accepted (stored, not strictly enforced) · ✓ by design · ⟳ on the roadmap.

Error codes & shapes

Errors use the real Acuity envelope { status_code, message, error }, where error is a stable machine-readable code:

Manifest

See services/acuity-scheduling/manifest.json:

• name: acuity-scheduling, port: 4850, protocol: http, healthcheck: /health, startup ≈ 100ms
• env: ACUITY_SCHEDULING_USER_ID, ACUITY_SCHEDULING_API_KEY, ACUITY_SCHEDULING_BASE_URL

Configuration — test.env

Copy these into your test.env (used by the bridge sidecar flow). Tokens are Parlel's seeded test credentials — any non-empty value is accepted by the emulator, so you rarely need to change them. Swap in real credentials only when pointing at the live service in prod.env.

ACUITY_SCHEDULING_USER_ID=parlel
ACUITY_SCHEDULING_API_KEY=parlel
ACUITY_SCHEDULING_BASE_URL=http://parlel-bridge:4850