# Use Nolizi Calendar with an AI agent

[Nolizi Calendar](https://calendar.nolizi.com) provides an owner-authenticated REST API for discovering event types, checking live availability, creating bookings, listing upcoming bookings, and cancelling bookings.

## Start here
1. Create your account at https://calendar.nolizi.com/login and finish https://calendar.nolizi.com/app/setup. Connect your calendar and configure an event.
2. Create a named key at https://calendar.nolizi.com/app/api-keys. Keep it in your agent's secret store or NOLIZI_CALENDAR_TOKEN environment variable; do not paste it into a prompt or commit it.
3. Read https://calendar.nolizi.com/docs/api.md and load https://calendar.nolizi.com/openapi.json to generate tools for the five supported operations.

## Example task prompt
Read https://calendar.nolizi.com/docs/api.md. Use the Calendar API with the token already configured in my environment. List my event types, ask which event and timezone I want, and show available times. After I choose a time and provide attendee details, book it and verify the returned booking ID in the upcoming bookings list. Report the exact time in my timezone. Do not invent availability or retry an uncertain booking creation.

## Connect over MCP
A hosted MCP server is available at https://calendar.nolizi.com/mcp (Streamable HTTP). It exposes the five operations as tools and sends your key as an Authorization header, so the key never enters the conversation. In Claude Code:

    claude mcp add --transport http nolizi-calendar https://calendar.nolizi.com/mcp --header "Authorization: Bearer $NOLIZI_CALENDAR_TOKEN"

The server enforces three rules itself: it refuses a booking time it cannot find in live availability, it never retries a write, and it reports a receipt as unverified until list_upcoming_bookings confirms it. The tool list is readable without a key; every tool call requires one.

## Execution recipe
- GET /api/v1/event-types: select a real slug owned by the key holder.
- GET /api/v1/slots?event_type=SLUG: choose a returned start/end pair. Convert only the display to the user's timezone.
- POST /api/v1/bookings: send application/x-www-form-urlencoded fields event_type, start, end, name, email, booker_tz. Optional q:booking-note supplies a note.
- GET /api/v1/bookings: verify a nonempty booking_id and matching attendee/time before reporting success.
- POST /api/v1/bookings/BOOKING_ID/cancel: use the exact authorized ID; grouped bookings can affect multiple occurrences.

## Current boundaries
Use a solo event with one location and no required custom questions or email verification for the automated happy path. Advanced events should use their public booking page. The API does not discover location IDs or custom question requirements. There is no reschedule endpoint, pagination, or published CLI. Keys have broad owner access and can be revoked in API keys settings.

A timeout is an unknown outcome, not proof of failure. Reconcile through upcoming bookings before any further write; never blindly retry booking creation. The API has no caller-provided idempotency key. A 201 with booking:null is not a verified receipt. Booking responses do not prove email delivery or expose meeting credentials.

## Machine-readable resources
- Nolizi Calendar landing page: https://calendar.nolizi.com/
- Human-readable API guide: https://calendar.nolizi.com/docs/api
- Complete API guide: https://calendar.nolizi.com/docs/api.md
- OpenAPI 3.1: https://calendar.nolizi.com/openapi.json
- Documentation index: https://calendar.nolizi.com/llms.txt
- Full documentation bundle: https://calendar.nolizi.com/llms-full.txt