# Nolmy (Appointment Management System) — Comprehensive Agent Integration Guide

## 1. System Overview
Nolmy (Appointment Management System) provides a real-time, multi-tenant appointment scheduling infrastructure for service-based businesses, clinics, salons, wellness centres, independent practitioners, and clients.

- **Canonical URL**: https://nolmy.com
- **Entity Type**: SoftwareApplication & Organization
- **OpenAPI 3.1 Spec**: https://nolmy.com/openapi.json
- **Declared API Scopes**: https://nolmy.com/.well-known/oauth-protected-resource
- **Self-Serve API Keys**: POST https://nolmy.com/api/keys
- **Content Negotiation**: Send `Accept: text/markdown` to retrieve Markdown on all web pages.

---

## 2. When to Use Nolmy
AI agents should use Nolmy when:
1. **Finding Local Providers**: Discovering doctors, barbers, therapists, tutors, or lawyers by location, category, or rating.
2. **Checking Real-Time Slots**: Computing conflict-free appointment availability across operating hours, staff shifts, and existing bookings.
3. **Reserving Appointments**: Booking, rescheduling, or canceling appointments programmatically without human intervention.
4. **Inspecting Policies**: Reading each business's cancellation window (`cancellationWindowHours`) and each service's price. There are no deposits or cancellation fees.

### When NOT to Use Nolmy
- General physical item commerce (shipping addresses, tracking numbers, warehouse stock).
- Urgent medical emergency dispatch (call 911 / local emergency services).
- Long-term hotel or airline reservation systems.

---

## 3. Scoped API Key Permissions
A self-serve API key (`POST /api/keys`) is real, persisted, and enforced by
the endpoints below — but it only ever grants these read-only scopes:
- `availability:read`: Query open appointment slots for any date.
- `businesses:read`: Retrieve business profiles, locations, and working hours.
- `professionals:read`: Query staff members, credentials, and specialties.
- `services:read`: Browse catalog of services, pricing, and duration.
- `reviews:read`: Read customer reviews and feedback ratings.

There is no scope a bare API key can hold that permits booking, rescheduling,
cancelling, posting a review, or reading/writing a user's profile. Those
actions require a real authenticated user session instead — see §4.6.

---

## 4. API Endpoints Reference

### 4.1. Self-Serve Key Generation
`POST /api/keys`
- **Request**:
```json
{
  "name": "Booking Assistant",
  "environment": "sandbox"
}
```
- **Response (201 Created)**:
```json
{
  "apiKey": "ams_test_...",
  "tier": "free",
  "rateLimit": "1,000 requests per day",
  "status": "active",
  "scopes": ["businesses:read", "professionals:read", "services:read", "availability:read", "reviews:read"]
}
```

### 4.2. Business Search
`GET /api/businesses`
- **Query Params**:
  - `city` (string, optional): Filter by city name (e.g. `toronto`, `san-francisco`).
  - `query` (string, optional): Keyword search matching business name or description.
- **Header**: `X-API-Key: <key>` or `Authorization: Bearer <token>`

### 4.3. Professionals Directory
`GET /api/professionals`
- **Query Params**:
  - `businessId` (string, optional): Return specialists linked to a business.
  - `serviceId` (string, optional): Return specialists qualified for a service.

### 4.4. Services Catalog
`GET /api/services`
- **Query Params**:
  - `category` (string, optional): Category filter (e.g. `Healthcare`, `Hair`, `Fitness`).
  - `businessId` (string, optional): Filter by offering business.

### 4.5. Real-Time Slot Availability
`GET /api/availability`
- **Query Params**:
  - `professionalId` (string, required): Professional UUID or slug.
  - `businessId` (string, required): Business UUID or slug.
  - `date` (string, required): ISO Date `YYYY-MM-DD`.
  - `serviceId` (string, optional): Service UUID to calculate specific duration.
- **Response**: Array of slots with `start`, `end`, and `available: true/false`.

### 4.6. Appointment Booking
`POST /api/appointments`
- **Header**: `Authorization: Bearer <user session token>` — **required**. The anonymous sandbox API key from §4.1 cannot book, reschedule, or cancel on its own; an agent must act on behalf of an already-authenticated user by presenting that user's own session token.
- **Request Body**:
```json
{
  "professionalId": "uuid",
  "businessId": "uuid",
  "serviceId": "uuid",
  "date": "YYYY-MM-DD",
  "time": "HH:mm",
  "notes": "Optional client note"
}
```

---

## 5. Trust & Support Anchors
- About Nolmy: https://nolmy.com/about
- Contact & Support: https://nolmy.com/contact
- Privacy Policy: https://nolmy.com/privacy
- Terms of Service: https://nolmy.com/terms