# Quanta Clock（小框日记）AI Agent API

> 智能日程管理平台 — 情侣日程 · 共享日记 · 经期推断 · 嘟嘟机硬件配套

## Quick Start

- **Base URL**: `https://www.quantaclock.com/api/v1/agent`
- **Auth**: HTTP Header `X-API-Key: sk-<your-key>`
- **Write ops**: Must include `User-Agent: YourBot/1.0` header
- **Tools**: `GET /api/v1/agent/tools` returns OpenAI function-calling definitions
- **Swagger**: `https://www.quantaclock.com/docs` (interactive)
- **Full docs**: `https://www.quantaclock.com/docs/ai-manual` (downloadable markdown)

## Available Tools (Function Calling)

See `GET /api/v1/agent/tools` for the canonical list. Summary:

| Tool | Method | Description |
|------|--------|-------------|
| get_schedules | GET /schedules | List schedules, optional `?date=YYYY-MM-DD&include_partner=true` |
| get_today_schedules | GET /schedules/today | Today's schedules, optional `?include_partner=true` |
| create_schedule | POST /schedules | Create schedule with title, schedule_time, description, visibility, category, priority, status |
| create_diary | POST /diaries | Create diary (requires couple link), with title, content, mood, weather |
| get_health_prediction | GET /health/prediction | Period cycle prediction |

## Create Schedule Fields

```json
{
  "title": "string (required, 1-256 chars)",
  "schedule_time": "ISO 8601, e.g. 2026-08-01T15:00:00",
  "description": "string (optional)",
  "reminder_minutes": "int, default 15 (1-1440)",
  "repeat_type": "none | daily | weekly | monthly",
  "visibility": "private | couple (default: couple if user has partner)",
  "category": "string (optional, max 64 chars)",
  "priority": "1=high | 2=mid(default) | 3=low",
  "status": "todo | in_progress | done"
}
```

## Response Format

```json
{
  "id": "uuid",
  "title": "string",
  "description": "string",
  "schedule_time": "ISO 8601",
  "reminder_minutes": "int",
  "repeat_type": "string",
  "status": "string",
  "visibility": "string",
  "category": "string",
  "priority": "int",
  "owner_username": "string (when include_partner=true)",
  "owner_user_id": "string (when include_partner=true)"
}
```

## Rate Limits

- Read (GET): 60/min per API Key
- Write (POST/PUT/DELETE): 30/min per API Key
- Exceeded → 429 with `Retry-After` header

## Get API Key

1. Login at `https://www.quantaclock.com`
2. Settings → API Keys → New Key
3. Save the `sk-...` key (shown once)

## Notes

- Couple-linked users: AI-created schedules default to `visibility: "couple"` (shared with partner)
- Write operations require `User-Agent` header (WAF bypass)
- All operations are audit-logged