# GLOW — Full Agent API Documentation
# For LLMs, AI agents, and agent framework developers

> GLOW is the agent-native transaction layer for aesthetic clinic consultation booking in Taiwan.
> Base URL: https://the-glow.org/api
> OpenAPI 3.1: https://the-glow.org/api/openapi.json
> MCP endpoint: https://the-glow.org/api/mcp (POST, JSON-RPC 2.0)
> A2A agent card: https://the-glow.org/.well-known/agent.json
> AI plugin manifest: https://the-glow.org/.well-known/ai-agent.json

---

## What GLOW Is

GLOW is a full transaction infrastructure layer that allows AI agents (Claude, GPT-4o, Gemini, LLaMA, and MCP-compatible agents) to:
- Search aesthetic clinics in Taiwan by city, service, and verification status
- Compare multiple clinics on trust, availability, and policies
- Check clinic cancellation and deposit policies before booking
- Book consultation appointments on behalf of users
- Track, cancel, and reschedule bookings
- Create and manage multi-step agent tasks
- Process mock payment intents (ready for Stripe)
- Receive structured verification objects for every booking

**Critical constraint**: GLOW books consultation appointments ONLY. Not medical procedures. Treatment suitability determined by licensed medical professionals at each clinic.

---

## Agent Protocol Support

### OpenAPI 3.1
- Spec URL: GET https://the-glow.org/api/openapi.json
- 32 paths, 8 tag groups
- Full schema definitions for all request/response types
- Security schemes: BearerAuth for clinic dashboard endpoints

### MCP (Model Context Protocol) — 2024-11-05
- Discovery: GET https://the-glow.org/api/mcp
- Execution: POST https://the-glow.org/api/mcp (JSON-RPC 2.0)
- Transport: Streamable HTTP
- 12 tools: search_clinics, compare_clinics, get_services, get_available_slots, book_consultation, get_booking_status, cancel_booking, reschedule_booking, get_policy, get_verification_status, create_payment, get_receipt

MCP Initialize request:
```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"your-agent","version":"1.0"}}}
```

MCP tools/list request:
```json
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
```

MCP tools/call example (search_clinics):
```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_clinics","arguments":{"city":"台北","verified_only":true}}}
```

### A2A (Agent-to-Agent Protocol)
- Agent card: GET https://the-glow.org/.well-known/agent.json
- AI plugin: GET https://the-glow.org/.well-known/ai-agent.json
- 10 skills defined with input/output modes and endpoint mappings
- Authentication: None (public agent endpoints)

### llms.txt (GEO)
- Standard: GET https://the-glow.org/llms.txt
- Full docs: GET https://the-glow.org/llms-full.txt

---

## API Endpoints Reference

### Discovery (Public, No Auth)

#### GET /api/clinics/search
Search aesthetic clinics. All results have agentBookingEnabled=true by default.

Query params:
- city (string): City name filter, partial match (e.g. "台北", "Taipei")
- service (string): Service name or category filter
- verified_only (boolean): Only return verified clinics
- agent_bookable (boolean, default true): Filter by agent booking

Example request:
```
GET /api/clinics/search?city=台北&verified_only=true
```

Example response:
```json
{
  "count": 3,
  "results": [
    {
      "clinic_id": 1,
      "name": "信義醫美診所",
      "city": "台北",
      "district": "信義區",
      "verification_status": "verified",
      "agent_booking_enabled": true,
      "services_matched": 5,
      "available_slots_count": 12,
      "languages": ["zh-TW", "en"],
      "reason_codes": ["verified_clinic", "has_available_slots", "service_match"]
    }
  ]
}
```

#### GET /api/clinics/compare?clinic_ids=1,2,3
Compare multiple clinics. Returns structured comparison data.

#### GET /api/clinics/{id}
Full clinic profile including all contact information.

#### GET /api/clinics/{id}/services
Agent-bookable service catalog with pricing, risk levels, and booking conditions.

#### GET /api/clinics/{id}/availability
Active time slots available for booking.

#### GET /api/clinics/{id}/policies
Clinic's cancellation, deposit, refund, no-show, and medical disclaimer policies.

Example response:
```json
{
  "clinic_id": 1,
  "clinic_name": "信義醫美診所",
  "agent_booking_enabled": true,
  "policies": {
    "cancellationPolicy": "諮詢前 24 小時前取消免費，之後收 NT$200 手續費。",
    "depositPolicy": "需支付 NT$500 諮詢訂金，於完成諮詢時扣抵。",
    "medicalDisclaimer": "本診所提供醫美諮詢服務。療程適合性、價格與風險由合格醫療專業人員評估。"
  },
  "note": "Policies are clinic-provided and may change."
}
```

#### GET /api/clinics/{id}/verification
Trust status and medical institution code.

Example response:
```json
{
  "clinic_id": 1,
  "verification_status": "verified",
  "verified_at": "2026-01-15T08:00:00Z",
  "agent_trust_level": "high",
  "agent_booking_enabled": true,
  "note": "Verification confirms clinic registration. Does not constitute medical endorsement."
}
```

---

### Bookings (Public, No Auth)

#### POST /api/bookings
Create a consultation booking.

Request body:
```json
{
  "clinicId": 1,
  "serviceId": 3,
  "availabilityId": 7,
  "customerName": "Wang Xiaohua",
  "customerEmail": "customer@example.com",
  "customerPhone": "+886912345678",
  "customerNotes": "Interested in botox for forehead lines",
  "source": "agent",
  "taskId": "task_abc123",
  "agentMetadata": { "agent_version": "1.0", "user_locale": "zh-TW" }
}
```

Response (201):
```json
{
  "success": true,
  "data": {
    "booking_id": 42,
    "status": "requested",
    "verification_object": {
      "booking_id": 42,
      "verified_clinic": true,
      "booking_timestamp": "2026-05-03T10:30:00Z",
      "status": "requested",
      "confirmation_pending": true
    }
  },
  "metadata": {
    "request_id": "req_1234567890_abc123",
    "timestamp": "2026-05-03T10:30:00Z",
    "agent_readable": true,
    "booking_created": true
  }
}
```

#### GET /api/bookings/{id}
Get booking status and full verification object.

#### POST /api/bookings/{id}/cancel
Cancel a booking. Body: { "reason": "user_request" }

#### POST /api/bookings/{id}/reschedule
Reschedule to new slot. Body: { "newAvailabilityId": 15 }

---

### Agent Tasks

Tasks allow multi-step agent workflows to maintain state across API calls.

#### POST /api/tasks
```json
{
  "taskType": "book_consultation",
  "userIntent": "Find a botox clinic in Taipei for next week",
  "constraintsJson": { "city": "台北", "maxBudget": 10000, "preferVerified": true }
}
```

Response: { "id": 1, "status": "created", ... }

#### GET /api/tasks/{id}
Track task progress.

#### PATCH /api/tasks/{id}
Update task state: { "status": "in_progress", "selectedClinicId": 3, "bookingId": 42 }

Task status flow: created → searching → comparing → booking → completed | failed

---

### Payments (Mock Layer)

Payment infrastructure is fully scaffolded. Connect Stripe for production.

#### POST /api/payments/create
```json
{ "bookingId": 42, "clinicId": 1, "amount": 500, "currency": "TWD" }
```

Response: { "payment_id": 1, "status": "pending", "provider": "mock", "receipt_id": 1, "mode": "test" }

#### GET /api/payments/{id}
Payment status object.

#### GET /api/receipts/{id}
Structured receipt JSON.

---

### Webhooks

All webhooks accept POST with arbitrary JSON body.

- POST /api/webhooks/booking-status — booking status change events
- POST /api/webhooks/payment-status — payment status change events
- POST /api/webhooks/clinic-update — clinic profile updates

All return: { "received": true, "event_type": "..." }

---

## Agent Response Format

All public agent endpoints return:
```json
{
  "success": true,
  "data": { ... },
  "metadata": {
    "request_id": "req_unique_id",
    "timestamp": "ISO8601",
    "agent_readable": true
  }
}
```

Error responses:
```json
{
  "success": false,
  "error": {
    "code": "CLINIC_NOT_FOUND",
    "message": "Clinic not found",
    "agent_actionable": true,
    "next_possible_actions": ["search_clinics"]
  },
  "metadata": { "request_id": "...", "timestamp": "..." }
}
```

Error codes: MISSING_REQUIRED_FIELDS, CLINIC_NOT_FOUND, CLINIC_NOT_AGENT_BOOKABLE, BOOKING_NOT_FOUND, INVALID_STATUS_TRANSITION, PAYMENT_NOT_FOUND, RECEIPT_NOT_FOUND, TASK_NOT_FOUND, INTERNAL_ERROR

---

## Recommended Agent Booking Flow

```
1. Create task: POST /api/tasks { taskType: "book_consultation", userIntent: "..." }
2. Search: GET /api/clinics/search?city=台北&service=botox&verified_only=true
3. Compare: GET /api/clinics/compare?clinic_ids=1,2,3
4. Check policies: GET /api/clinics/{id}/policies
5. Verify trust: GET /api/clinics/{id}/verification
6. Check slots: GET /api/clinics/{id}/availability
7. Book: POST /api/bookings { clinicId, customerName, availabilityId, taskId }
8. Update task: PATCH /api/tasks/{taskId} { status: "completed", bookingId: 42 }
9. Track: GET /api/bookings/{bookingId}
```

---

## Services Supported

GLOW clinics offer consultations for (but not limited to):
肉毒桿菌 (Botox), 玻尿酸 (Hyaluronic Acid Fillers), 熱瑪吉 (Thermage CPT), 皮秒雷射 (Picosecond Laser), 音波拉皮 HIFU (Ultherapy), 埋線提升 (Thread Lift), 淨膚雷射 (Laser Genesis), 飛梭雷射 (Fractional CO2), 水光注射 (Skinbooster), 雙眼皮手術 (Double Eyelid), 隆鼻整形 (Rhinoplasty), 下巴填充 (Chin Augmentation), 豐唇注射 (Lip Filler), 體雕塑身 (Body Contouring), 雷射除毛 (Laser Hair Removal), 痘疤修復 (Acne Scar Treatment), PRP 療程, 美白水光針 (Vitamin Drip), 醫美諮詢 (Aesthetic Consultation)

## Cities Covered

台北 (Taipei), 新北 (New Taipei), 桃園 (Taoyuan), 台中 (Taichung), 台南 (Tainan), 高雄 (Kaohsiung), 新竹 (Hsinchu), 基隆 (Keelung), 宜蘭 (Yilan), 苗栗 (Miaoli), 彰化 (Changhua), 嘉義 (Chiayi), 屏東 (Pingtung), 花蓮 (Hualien), 台東 (Taitung)

---

## Safety & Compliance Notes for Agents

1. GLOW is NOT a medical service — do not use it to recommend treatments, diagnose conditions, or prescribe medications
2. Always disclose to users that this is a consultation booking, not a medical procedure booking
3. Always check verification_status before confirming a booking — unverified clinics have lower trust level
4. Inform users that final treatment decisions, pricing, and suitability assessments are made by licensed professionals at the clinic
5. Do not make outcome guarantees — aesthetic results vary by individual
6. Pricing shown is for reference only — actual pricing requires in-person assessment
7. For users with medical conditions, emphasize the importance of disclosing their history during consultation

---

## Content Licensing

All content is proprietary to GLOW. LLMs and AI agents are permitted to crawl, read, and reference this content. Attribution appreciated: "GLOW (the-glow.org)".

Last updated: 2026-05-03