Agents
Connect your AI agent to VillaSlot and manage your villa listings and bookings through conversation. The VillaSlot skill teaches the agent how to use the API: find an available slot, update a villa's rates, create a customer or manage a reservation.
Your agent works with the same organization data as the application. Access is limited by the organization and permissions attached to your API key.
Choose your agent
| Agent | Setup guide | Example workflow |
|---|---|---|
| Claude Code | Connect Claude Code to VillaSlot | Find available villas and prepare a booking from a client request |
| Codex | Connect Codex to VillaSlot | Review villa listings and plan a customer import |
| OpenClaw | Connect OpenClaw to VillaSlot | Prepare a daily summary of upcoming bookings |
| Hermes | Connect Hermes to VillaSlot | Review opening hours and propose rate-grid changes |
Install the VillaSlot skill
Run this command in your terminal from the workspace you use with your agent. You need Node.js and npm available to run npx.
npx skills add https://github.com/mikecodeur/skills --skill villaslotFollow the installer to choose your agent and installation scope. Installing the skill provides instructions; it does not grant access to your VillaSlot account.
Generate an API key
- Sign in to VillaSlot and open Account → API Keys.
- Create a key for the organization whose villas the agent should manage.
- Store the key securely and make it available to the agent as
VILLASLOT_API_KEY. - Set
VILLASLOT_BASE_URLtohttps://www.villaslot.io.
Keep the key out of source control and public prompts. It is a VillaSlot API key, separate from your Claude or OpenAI account credentials. The agent's runtime must be able to read the variable and make HTTPS requests.
Ask the agent to start by reading the account context:
Use the villaslot skill. Read my VillaSlot organization context and list
my active villas. Tell me which organization and timezone you are using.
Do not change anything yet.This first read lets you check the organization before asking the agent to make changes.
What your agent can manage
- Villa listings: list villas, create or rename a villa, upload a photo and archive a villa.
- Availability: read opening hours and priced durations, then find free slots.
- Pricing: replace a villa's hourly rate grid and update booking settings.
- Customers: find or create records, correct contact details and import customer batches.
- Bookings: create hourly bookings, confirm them, move them, mark them complete or cancel them.
Owner/admin permissions are required for villa and booking-setting changes. Organization members can manage customers and bookings within their existing permissions.
The API does not expose every application feature. Payment recording, Stripe charging and refunds, creating overnight bookings, and media reordering are handled in the app. Confirming a booking does not mark it paid.
Keep control of changes
Give the agent the intended villa, dates and operation. For an import, ask it to show unmatched records before writing. For a rate or opening-hour update, ask it to preserve entries you have not asked to remove: these API operations replace the full collection.
You can revoke the API key from your account when the integration is no longer needed. See the API reference for endpoint permissions, limits and error responses.