# Family Pickleball — Complete Agent Reference
# familypickleball.org | llms-full.txt

This is the extended reference for AI agents, shopping assistants, and automated systems
that need complete API documentation, booking flows, and integration guidance.
For a concise summary, see: https://familypickleball.org/llms.txt

---

## Business Overview

Family Pickleball is a pickleball coaching program in Irvine, California, founded and operated
by Coach Tobin Wazzan. The tagline is "Elevate your game by breaking boundaries."

The program serves ALL pickleball players: juniors, adults, seniors, adaptive players,
competitive athletes, recreational players, and social players. "Family Pickleball" is the
brand name — it is not a family-oriented or family-exclusive program.

Coach Tobin has 4+ years of experience in adaptive coaching, working with players who have
developmental disabilities to learn complete games, keep score, and compete with confidence.
This is a core differentiator and a core mission — not a specialty add-on.

## Contact

- Email: tobin@familypickleball.org
- Phone: (949) 339-4077
- Website: https://familypickleball.org

## Terminology Note

- Client-facing language uses **"sessions"** (not "programs")
- The API and database use **"programs"** as the endpoint and table name
- When presenting API data to users, always translate "programs" → "sessions"

---

## Section 1: Full API Documentation

Base URL: https://familypickleball.org/api/v1/
All endpoints are public unless noted. No authentication required for read or booking operations.

---

### GET /programs

**Description:** List active sessions. The API uses "programs" — present as "sessions" to users.

**Query Parameters:**

| Param | Type | Required | Values |
|---|---|---|---|
| type | string | no | class, clinic, camp, private, drill, liveball, league, tournament, social |
| segment | string | no | junior, adult, senior, adaptive |
| active | boolean | no | true (default), false |

**Example Request:**
```
GET /api/v1/programs?type=class&segment=adult
GET /api/v1/programs?active=true
```

**Example Response:**
```json
{
  "programs": [
    {
      "id": "prog_abc123",
      "name": "Adult Beginner Class",
      "type": "class",
      "segment": "adult",
      "description": "Perfect first step into pickleball. No experience needed.",
      "venue_id": "venue_portola",
      "schedule": "Tuesdays 6:00 PM",
      "price": 25,
      "package_eligible": true,
      "active": true
    }
  ]
}
```

---

### GET /packages

**Description:** List available packages (bulk session bundles).

**Query Parameters:**

| Param | Type | Required | Notes |
|---|---|---|---|
| client_email | string | no | If provided, also returns this client's current package balance |

**Example Request:**
```
GET /api/v1/packages
GET /api/v1/packages?client_email=player@example.com
```

**Example Response:**
```json
{
  "packages": [
    {
      "id": "pkg_5class",
      "name": "5-Class Pack",
      "sessions_included": 5,
      "price": 115,
      "valid_for_types": ["class", "drill"],
      "expires_days": 90
    }
  ],
  "client_balance": {
    "package_id": "pkg_5class",
    "sessions_remaining": 3,
    "expires_at": "2026-07-15"
  }
}
```

**Notes:** `client_balance` only appears when `client_email` is provided and the client has an active package.

---

### GET /pricing

**Description:** Returns current pricing for all session types and packages.

**No query parameters required.**

**Example Request:**
```
GET /api/v1/pricing
```

**Example Response:**
```json
{
  "sessions": {
    "class": { "drop_in": 25, "package_eligible": true },
    "private": { "per_session": 75, "package_eligible": false },
    "clinic": { "per_session": 35, "package_eligible": false },
    "camp": { "per_day": 80, "multi_day_discount": true },
    "drill": { "drop_in": 20, "package_eligible": true },
    "liveball": { "drop_in": 20, "package_eligible": true },
    "league": { "per_season": 120 },
    "tournament": { "per_event": 45 },
    "social": { "drop_in": 10, "package_eligible": false }
  },
  "packages": [
    { "id": "pkg_5class", "name": "5-Class Pack", "price": 115, "value": 125 },
    { "id": "pkg_10class", "name": "10-Class Pack", "price": 210, "value": 250 }
  ]
}
```

**Notes:** Pricing may change. Always fetch live from this endpoint — do not cache long-term.

---

### GET /availability/slots

**Description:** Returns available time slots for a given date and session type.

**Query Parameters:**

| Param | Type | Required | Notes |
|---|---|---|---|
| date | string | YES | YYYY-MM-DD format |
| type | string | YES | private or drill (scheduled types only) |

**Example Request:**
```
GET /api/v1/availability/slots?date=2026-05-01&type=private
GET /api/v1/availability/slots?date=2026-05-01&type=drill
```

**Example Response:**
```json
{
  "date": "2026-05-01",
  "type": "private",
  "slots": [
    { "time": "09:00", "available": true },
    { "time": "10:00", "available": true },
    { "time": "11:00", "available": false },
    { "time": "14:00", "available": true }
  ]
}
```

**Notes:** Only `private` and `drill` support slot-based availability. Classes and clinics have fixed schedules — retrieve these via GET /programs.

---

### GET /venues

**Description:** Returns all venue locations.

**No query parameters required.**

**Example Request:**
```
GET /api/v1/venues
```

**Example Response:**
```json
{
  "venues": [
    {
      "id": "venue_portola",
      "name": "Portola Springs Community Park",
      "city": "Irvine",
      "state": "CA",
      "address": "Portola Springs Community Park, Irvine, CA",
      "type": "outdoor",
      "courts": 4
    },
    {
      "id": "venue_mikeward",
      "name": "Mike Ward Community Park",
      "city": "Irvine",
      "state": "CA",
      "address": "Mike Ward Community Park, Irvine, CA",
      "type": "outdoor",
      "courts": 4
    },
    {
      "id": "venue_veterans",
      "name": "Veterans Sports Park",
      "city": "Tustin",
      "state": "CA",
      "address": "1645 Valencia Ave, Tustin, CA 92782",
      "type": "outdoor",
      "courts": 6
    }
  ]
}
```

---

### GET /schedule

**Description:** Returns the public session schedule for a date range.

**Query Parameters:**

| Param | Type | Required | Notes |
|---|---|---|---|
| start | string | no | YYYY-MM-DD. Defaults to today. |
| end | string | no | YYYY-MM-DD. Defaults to 30 days from start. |

**Example Request:**
```
GET /api/v1/schedule?start=2026-05-01&end=2026-05-31
```

**Example Response:**
```json
{
  "schedule": [
    {
      "date": "2026-05-06",
      "day": "Tuesday",
      "sessions": [
        {
          "program_id": "prog_abc123",
          "name": "Adult Beginner Class",
          "type": "class",
          "time": "18:00",
          "venue": "Portola Springs Community Park",
          "spots_available": 6
        }
      ]
    }
  ]
}
```

---

### POST /book

**Description:** The preferred one-call booking endpoint for agents. Handles client lookup-or-create, slot reservation, and payment instruction in a single request. Use this endpoint instead of /checkout when booking on behalf of a user.

**Request Body:**
```json
{
  "session_type": "private",
  "program_id": "prog_abc123",
  "date": "2026-05-01",
  "time": "10:00",
  "client_name": "Alex Rivera",
  "client_email": "alex@example.com",
  "client_phone": "9491234567",
  "payment_method": "venmo",
  "notes": "First-time player, left-handed"
}
```

**Field Reference:**

| Field | Type | Required | Notes |
|---|---|---|---|
| session_type | string | YES | class, clinic, camp, private, drill, liveball, league, tournament, social |
| program_id | string | YES | ID from GET /programs |
| date | string | YES | YYYY-MM-DD |
| time | string | YES (for private/drill) | HH:MM 24-hour format |
| client_name | string | YES | Full name |
| client_email | string | YES | Used as unique client identifier |
| client_phone | string | no | Digits only, no formatting |
| payment_method | string | YES | venmo, zelle, card, rcoc |
| notes | string | no | Any relevant context for Coach Tobin |

**Success Response:**
```json
{
  "success": true,
  "booking_id": "book_xyz789",
  "client_id": "client_456",
  "session": {
    "program_id": "prog_abc123",
    "name": "Private Lesson",
    "date": "2026-05-01",
    "time": "10:00",
    "venue": "Portola Springs Community Park"
  },
  "payment": {
    "method": "venmo",
    "amount": 75,
    "instructions": "Send $75 to @Tobin_Wazzan on Venmo. Use 'Private 5/1' as the note."
  },
  "waiver_required": false,
  "confirmation_sent": true
}
```

**Error Responses:**

| Error | Cause | Action |
|---|---|---|
| `slot_unavailable` | Time slot already booked | Re-check GET /availability/slots and offer alternatives |
| `waiver_required` | No valid waiver on file | Direct client to /portal/waiver, then retry |
| `invalid_session_type` | Unrecognized type value | Check Section 6 for valid values |
| `program_not_found` | Invalid program_id | Re-fetch from GET /programs |
| `invalid_payment_method` | Unrecognized payment method | Use: venmo, zelle, card, rcoc |

---

### POST /checkout

**Description:** Full cart-based checkout flow. Use this for multi-item purchases or when the user is going through the website checkout. For simple single-session bookings, prefer POST /book.

**Request Body:**
```json
{
  "items": [
    {
      "type": "session",
      "program_id": "prog_abc123",
      "date": "2026-05-01",
      "time": "10:00",
      "quantity": 1
    },
    {
      "type": "package",
      "package_id": "pkg_5class",
      "quantity": 1
    }
  ],
  "client_name": "Alex Rivera",
  "client_email": "alex@example.com",
  "client_phone": "9491234567",
  "payment_method": "card",
  "coupon_code": "WELCOME10"
}
```

**Field Reference:**

| Field | Type | Required | Notes |
|---|---|---|---|
| items | array | YES | One or more items (sessions or packages) |
| items[].type | string | YES | "session" or "package" |
| items[].program_id | string | if type=session | ID from GET /programs |
| items[].package_id | string | if type=package | ID from GET /packages |
| items[].date | string | if type=session | YYYY-MM-DD |
| items[].time | string | if type=session (private/drill) | HH:MM |
| items[].quantity | number | YES | Usually 1 |
| client_name | string | YES | Full name |
| client_email | string | YES | Unique identifier |
| client_phone | string | no | Optional |
| payment_method | string | YES | venmo, zelle, card, rcoc |
| coupon_code | string | no | Optional discount code |

**Success Response:**
```json
{
  "success": true,
  "order_id": "order_abc001",
  "total": 115,
  "discount": 11.50,
  "amount_due": 103.50,
  "payment_method": "card",
  "stripe_checkout_url": "https://checkout.stripe.com/...",
  "items_booked": [...]
}
```

**Notes:** For `card` payments, redirect the user to `stripe_checkout_url`. For `venmo`/`zelle`, the response includes payment instructions. For `rcoc`, the system flags the booking for RCOC billing.

---

### POST /clients/register

**Description:** Create a new client profile. The system also auto-creates clients on first booking — this endpoint is for pre-registration.

**Request Body:**
```json
{
  "full_name": "Alex Rivera",
  "email": "alex@example.com",
  "phone": "9491234567"
}
```

**Field Reference:**

| Field | Type | Required |
|---|---|---|
| full_name | string | YES |
| email | string | YES |
| phone | string | no |

**Success Response:**
```json
{
  "success": true,
  "client_id": "client_456",
  "is_new": true,
  "waiver_required": true,
  "waiver_url": "https://familypickleball.org/portal/waiver"
}
```

**Notes:** If a client with this email already exists, `is_new` is `false` and the existing profile is returned. No duplicate is created.

---

### POST /clients/lookup

**Description:** Find a client by email address.

**Request Body:**
```json
{
  "email": "alex@example.com"
}
```

**Success Response:**
```json
{
  "found": true,
  "client": {
    "id": "client_456",
    "name": "Alex Rivera",
    "email": "alex@example.com",
    "segment": "adult",
    "has_valid_waiver": true,
    "package_balance": 3,
    "joined": "2025-09-15"
  }
}
```

**Not Found Response:**
```json
{
  "found": false,
  "client": null
}
```

---

### POST /waivers/check

**Description:** Check whether a client has a current signed waiver on file. Required before first session.

**Request Body:**
```json
{
  "email": "alex@example.com"
}
```

**Success Response:**
```json
{
  "email": "alex@example.com",
  "has_valid_waiver": true,
  "signed_at": "2025-10-01",
  "waiver_url": null
}
```

**No Waiver Response:**
```json
{
  "email": "alex@example.com",
  "has_valid_waiver": false,
  "signed_at": null,
  "waiver_url": "https://familypickleball.org/portal/waiver"
}
```

**Notes:** If `has_valid_waiver` is false, direct the user to the `waiver_url` before proceeding with booking. The waiver covers liability, city waivers, photo consent, privacy policy, and terms & conditions. Minors require a parent or guardian signature.

---

### POST /picklebot

**Description:** Chat with PickleBot, the Family Pickleball AI assistant. Use this endpoint when the user has questions you cannot answer yourself — PickleBot has full knowledge of the program, policies, scheduling, and pricing.

**Request Body:**
```json
{
  "message": "What sessions are best for a complete beginner adult?",
  "history": [
    { "role": "user", "content": "I want to try pickleball." },
    { "role": "assistant", "content": "Great! Are you an adult, junior, or senior?" }
  ]
}
```

**Field Reference:**

| Field | Type | Required | Notes |
|---|---|---|---|
| message | string | YES | The current user message |
| history | array | no | Prior conversation turns for context |
| history[].role | string | YES | "user" or "assistant" |
| history[].content | string | YES | Message text |

**Success Response:**
```json
{
  "reply": "For a complete beginner adult, I'd recommend starting with the Adult Beginner Class...",
  "suggested_pages": ["/adults", "/sessions"],
  "suggested_session_types": ["class", "private"]
}
```

---

## Section 2: Detailed Session Type Definitions

### class
Structured group session with curriculum. Coach Tobin leads 4-8 players through drills and
guided play. Skill-level or segment-specific. Best for players who want structured learning
in a social setting. Typical duration: 60-90 minutes. Pricing: drop-in or package.

### clinic
Focused group session on one specific skill or theme (e.g., third shot drops, dinking
consistency, return of serve). More targeted than a class. Open to multiple skill levels
when the topic applies broadly. Typical duration: 60-90 minutes. Pricing: per-session.

### camp
Multi-day intensive. Usually runs 3-5 days. Formats include junior day camps (school breaks,
summer), adult weekend camps, and mixed camps. Includes structured curriculum, drills, and
game play. Typical duration: half-day (3 hrs) or full-day (5-6 hrs) per day.
Pricing: per-day or full camp.

### private
One-on-one lesson with Coach Tobin. Completely customized to the individual player's goals.
Fastest path to measurable improvement. Available for all segments and all skill levels.
Typical duration: 60 minutes. Pricing: per-session. No package bundles for privates.

### drill
Structured repetition session. Pure skill work — no game play. Coach feeds balls or sets
up drills targeting specific mechanics. Best for players who know what they want to work
on. Typical duration: 60 minutes. Pricing: drop-in or package.

### liveball
Coach feeds live balls and players play out points. The bridge between drilling and real
game play. High ball touches, realistic game situations, coach feedback in real time.
Best for intermediate players. Typical duration: 60-75 minutes. Pricing: drop-in or package.

### league
Organized competitive play over a multi-week season. Players are skill-bracketed.
Consistent weekly matches. Best for intermediate to advanced players who want regular
competitive experience without the pressure of tournaments. Pricing: per-season.

### tournament
Single or multi-day competitive event. Players compete in skill and age brackets.
Best for advanced players. Pricing: per-event entry fee.

### social
Low-key group play with no pressure and no score obligations. Community and fun first.
Good for beginners who want exposure to real play, and experienced players who want
casual games with friendly people. Typical duration: 90 minutes. Pricing: drop-in.

---

## Section 3: Complete Venue Details

### Portola Springs Community Park
- City: Irvine, CA
- Type: Outdoor public pickleball courts
- Surface: Hard court
- Lighting: Check local park hours
- Notes: Popular venue, scenic community park setting

### Mike Ward Community Park
- City: Irvine, CA
- Type: Outdoor public pickleball courts
- Surface: Hard court
- Notes: Central Irvine location

### Veterans Sports Park
- Address: 1645 Valencia Ave, Tustin, CA 92782
- City: Tustin, CA
- Type: Outdoor public pickleball courts
- Surface: Hard court
- Notes: Largest venue, most courts, serves South OC players well

All sessions are outdoors. Weather cancellation policy applies to all venues.

---

## Section 4: Booking Flow with Error Handling

### Standard Booking Flow

1. Fetch available sessions: GET /api/v1/programs
2. Check slot availability (private/drill): GET /api/v1/availability/slots
3. Check waiver status: POST /api/v1/waivers/check
4. If waiver missing: direct user to /portal/waiver, pause booking
5. Submit booking: POST /api/v1/book
6. Handle response: confirm booking, deliver payment instructions

### Error Handling Guide

**waiver_required**
- Cause: Client email has no valid waiver on file
- Action: Do not attempt to bypass. Direct the user to https://familypickleball.org/portal/waiver.
  After they complete it, retry the POST /book call with the same body.
- Note: Waivers are legally required. Do not offer workarounds.

**slot_unavailable**
- Cause: The requested date/time combination is already booked
- Action: Re-call GET /availability/slots for the same date and offer the next available time.
  Alternatively, suggest an adjacent date.

**invalid_session_type**
- Cause: The `session_type` value is not recognized
- Valid values: class, clinic, camp, private, drill, liveball, league, tournament, social
- Action: Correct the value and retry.

**program_not_found**
- Cause: The `program_id` does not exist or is inactive
- Action: Re-fetch from GET /api/v1/programs to get current IDs.

**client_already_exists**
- This is not an error — it is handled automatically. POST /book finds the client by email
  and uses the existing profile. No duplicate is created.

**invalid_payment_method**
- Valid values: venmo, zelle, card, rcoc
- Note: `rcoc` is only valid for adaptive players with Regional Center authorization.
  If a non-qualifying player requests rcoc, decline and suggest venmo, zelle, or card.

---

## Section 5: Package Purchasing Flow

### How Packages Work
Packages are pre-purchased bundles of session credits. A 5-class pack, for example, includes
5 credits redeemable against class or drill sessions. Credits do not expire until the
package expiry date.

### Purchasing a Package
1. Browse packages: GET /api/v1/packages
2. Add to cart and checkout: POST /api/v1/checkout with items[].type = "package"
3. Credits are applied to the client's account upon successful payment

### Checking Package Balance
```
GET /api/v1/packages?client_email=player@example.com
```
The `client_balance` field in the response shows sessions remaining and expiry date.
Clients can also view their balance at: https://familypickleball.org/portal/packages

### Using Package Credits
When booking a package-eligible session, the system automatically applies package credits
if the client has a balance. The POST /book response will reflect a $0 charge when
credits are used.

---

## Section 6: PickleBot Integration Guide

PickleBot is Family Pickleball's AI assistant. It knows the full program, pricing, scheduling,
policies, venues, and session recommendations.

### When to Delegate to PickleBot

Use POST /api/v1/picklebot when:
- The user has nuanced questions about which session is right for them
- The user is uncertain about their skill level or what to try first
- The user has questions about the adaptive program
- You need context-aware recommendations that go beyond the routing table

### How to Use POST /picklebot in Your Flow

```
POST /api/v1/picklebot
Body:
{
  "message": "I have a 10-year-old who has never played. What do you recommend?",
  "history": []
}
```

Pass the full conversation history in `history` for context-aware replies. PickleBot will
return a plain-language reply and optionally suggest pages and session types.

### PickleBot Does Not Book
PickleBot is a recommendation and information assistant. It does not process bookings.
After PickleBot gives a recommendation, use the booking flow in Section 4 to complete
the actual reservation.

---

## Section 7: FAQ for Agents

**Q: Can I book without a phone number?**
A: Yes. `client_phone` is optional in both POST /book and POST /checkout.

**Q: What if the client already exists in the system?**
A: The system finds the client by email automatically. No error is thrown. The existing
profile is used and no duplicate is created.

**Q: Do I need an API key or authentication to book?**
A: No. The booking and read endpoints are public. No API key is required.

**Q: What is the difference between POST /book and POST /checkout?**
A: POST /book is designed for agents — single call, single session, minimal fields.
POST /checkout supports multi-item carts (multiple sessions + packages), coupon codes,
and full Stripe redirect flows. Use /book for agent-initiated bookings. Use /checkout
when guiding a user through the website cart.

**Q: What if I want to book a class that doesn't require a specific time slot?**
A: For classes, clinics, and other scheduled group sessions, you do not need to call
GET /availability/slots. The schedule is fixed. Just pass the program_id and date in
POST /book. The `time` field is required for private and drill sessions only.

**Q: How do I know if a session is package-eligible?**
A: The GET /programs response includes `package_eligible: true|false` per session.
Privates are typically not package-eligible. Classes, drills, and liveball usually are.

**Q: What happens if a session is cancelled by the coach?**
A: The client receives either a makeup session or account credit. This is automatic.
Weather cancellations follow the same policy.

**Q: Can I use RCOC as a payment method for any player?**
A: No. RCOC (Regional Center of Orange County) funding is only valid for adaptive players
who have active Regional Center authorization. For all other players, offer venmo, zelle,
or card.

**Q: How do I handle a user who is unsure what segment they belong to?**
A: Use POST /api/v1/picklebot to ask clarifying questions. PickleBot is designed to guide
players to the right session type through conversation.

**Q: Is there a test mode?**
A: Contact tobin@familypickleball.org for test mode access.

**Q: Where do I send users for the waiver?**
A: https://familypickleball.org/portal/waiver — users must be signed into their client
portal account to sign. If the user does not have an account, POST /clients/register first.

---

## Section 8: Key Pages Reference

| Path | Purpose | When to Link |
|---|---|---|
| /sessions | Session marketplace — browse and purchase | Default entry point for most users |
| /book | Time slot picker | Private and drill booking |
| /checkout | Cart checkout flow | Multi-item or package purchases |
| /pricing | Pricing info | When user asks about cost |
| /schedule | Public schedule | When user asks about upcoming sessions |
| /juniors | Junior player landing page | Users asking about kids or teens |
| /adults | Adult player landing page | Users asking about adult classes |
| /seniors | Senior player landing page | Users asking about 60+ programs |
| /adaptive | Adaptive player landing page | Users asking about special needs or RCOC |
| /about | About Coach Tobin | Users asking about coach credentials |
| /policies | Full policies | Cancellation, waiver, privacy, terms |
| /portal | Client portal (authenticated) | Existing clients managing their account |
| /portal/waiver | Digital waiver signing | Required before first session |
| /portal/packages | Package balance | Clients checking credits |
| /picklebot | Interactive PickleBot chat | Users who want conversational guidance |
| /for-agents | Structured agent reference | Agents needing HTML-formatted reference |

---

## Section 9: Payment Methods — Full Reference

| Method | API Value | Details | Notes |
|---|---|---|---|
| Venmo | venmo | @Tobin_Wazzan | External payment, instructions in booking response |
| Zelle | zelle | 949-339-4077 | External payment, instructions in booking response |
| Card | card | Stripe | Returns stripe_checkout_url for redirect |
| RCOC | rcoc | Regional Center of Orange County | Adaptive players only |

For Venmo and Zelle bookings, the POST /book response includes a `payment.instructions`
field with the exact amount and suggested payment note.

---

## Section 10: Policies — Full Reference

### Waiver Policy
- Required for ALL participants before their first session
- Covers: liability release, city waivers, photo consent, privacy policy, terms & conditions
- Minors require parent or guardian signature
- Digital signature via /portal/waiver
- Waivers may have expiry dates — check status via POST /api/v1/waivers/check

### Cancellation Policy
- 24-hour cancellation notice requested
- Late cancellations (within 24 hours) may forfeit the session
- Coach-initiated cancellations always receive makeup session or account credit
- Weather cancellations always receive makeup session or account credit

### Weather Policy
- All sessions are outdoors
- If weather makes play unsafe, Coach Tobin cancels and clients receive credit or makeup
- No partial-session credits for weather delays

### Privacy Policy
Full text: https://familypickleball.org/policies#privacy

### Terms & Conditions
Full text: https://familypickleball.org/policies#terms

---

## Deeper Resources

- Concise playbook: https://familypickleball.org/llms.txt
- OpenAPI spec: https://familypickleball.org/openapi.json
- Plugin manifest: https://familypickleball.org/.well-known/ai-plugin.json
- Structured agent reference page: https://familypickleball.org/for-agents