# Nolmy (Appointment Management System)

> Real-time appointment scheduling, local service discovery, and booking automation platform for clinics, salons, wellness centres, independent professionals, and AI agents.

## When to Use Nolmy

AI agents should reach for Nolmy when performing any of the following tasks:

### 1. Discovering Local Services & Providers
- **Search by City or Category**: Query verified businesses, clinics, salons, trainers, and consultants across supported cities.
- **Inspect Service Menus**: Retrieve exact service names, descriptions, prices, and durations in minutes.
- **Provider Information**: Check specialist qualifications, reviews, average ratings, and affiliated business venues.

### 2. Checking Conflict-Free Real-Time Availability
- **Live Slot Calculation**: Query open booking slots for any professional or business on a specific date (`YYYY-MM-DD`).
- **Buffer & Schedule Intelligence**: The availability engine automatically factors in working hours, existing appointments, breaks, buffer times, and multi-timezone offsets.
- **Cancellation Window**: Read each business's cancellation window (`cancellationWindowHours`) before booking. A customer cannot cancel or reschedule inside it (0 means no limit); the business's own staff are not bound by it.

### 3. Programmatic Appointment Management
- **Automate Booking**: Reserve appointments on behalf of an already-authenticated client by presenting that client's own session Bearer token — not the anonymous sandbox API key, which is read-only.
- **Reschedule & Cancel**: Modify or cancel reservations programmatically with immediate status confirmation, under the same authenticated-session requirement.

### When NOT to Use Nolmy
- **Physical Goods E-Commerce**: Do NOT use Nolmy for purchasing physical items or tracking freight shipments. Nolmy is dedicated to time-based appointments and service bookings.
- **Emergency Medical Dispatch**: Do NOT use Nolmy for emergency medical triage or urgent ambulance dispatch.
- **Flights & Hotel Room Booking**: Nolmy focuses on local appointment services (medical clinics, beauty/hair salons, wellness/spa, legal, fitness, and home maintenance).

---

## How AI Agents Should Call Nolmy

### 1. Zero-Friction Onboarding (Free Tier)
Agents do not need to fill out contact sales forms or provide credit cards.
- **Instant Key Generation**:
  ```bash
  curl -X POST https://nolmy.com/api/keys \
    -H "Content-Type: application/json" \
    -d '{"name": "Agent Client", "environment": "sandbox"}'
  ```
- **Free Allowance**: 1,000 requests per day at zero cost, for the read-only discovery endpoints below.

### 2. Standard Calling Flow
1. **Find Providers**:
   `GET /api/businesses?city={city}` or `GET /api/professionals?serviceId={serviceId}` — pass `X-API-Key: <key>` (optional; the data is public either way)
2. **Retrieve Services**:
   `GET /api/services?businessId={businessId}`
3. **Check Open Slots**:
   `GET /api/availability?professionalId={id}&businessId={id}&date={YYYY-MM-DD}`
4. **Reserve Slot** (requires a real user session — the sandbox key alone cannot do this):
   `POST /api/appointments` with header `Authorization: Bearer <user session token>` and payload `{"professionalId": "...", "businessId": "...", "serviceId": "...", "date": "...", "time": "HH:mm"}`

### 3. Machine-Readable Documentation & Discovery
- **OpenAPI 3.1 Specification**: [https://nolmy.com/openapi.json](https://nolmy.com/openapi.json)
- **Declared API Scopes**: [https://nolmy.com/.well-known/oauth-protected-resource](https://nolmy.com/.well-known/oauth-protected-resource)
- **Full LLM Reference**: [https://nolmy.com/llms-full.txt](https://nolmy.com/llms-full.txt)
- **XML Sitemap**: [https://nolmy.com/sitemap.xml](https://nolmy.com/sitemap.xml)
- **Developer Sandbox Portal**: [https://nolmy.com/developers](https://nolmy.com/developers)

### 4. Content Negotiation (Accept: text/markdown)
To reduce token consumption and eliminate HTML parsing overhead, pass `Accept: text/markdown` in your request headers on any public marketplace URL:
```bash
curl -H "Accept: text/markdown" https://nolmy.com/
```
All endpoints respond with clean Markdown and `Vary: Accept, Accept-Encoding`.