# Cron & Scheduler

Cron API cho phép bạn lên lịch các cuộc gọi HTTP định kỳ đến các endpoint của
Synapse (hoặc các endpoint HTTPS bên ngoài). Hoàn hảo cho đồng bộ định kỳ,
nhắc nhở và các tác vụ bảo trì.

## Các endpoint

### POST /cron

Tạo một tác vụ đã lên lịch.

```bash
curl -X POST https://synapse.schaefer.zone/cron \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": "0 * * * *",
    "endpoint": "https://synapse.schaefer.zone/memory/recall",
    "method": "GET",
    "headers": {"Authorization": "Bearer YOUR_MIND_KEY"}
  }'
```

Phản hồi:

```json
{
  "id": "cron_001",
  "schedule": "0 * * * *",
  "endpoint": "https://synapse.schaefer.zone/memory/recall",
  "method": "GET",
  "enabled": true,
  "next_run": "2026-06-27T13:00:00Z",
  "created_at": "2026-06-27T..."
}
```

### GET /cron

Liệt kê tất cả tác vụ đã lên lịch.

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/cron
```

### DELETE /cron/:id

Xóa một tác vụ đã lên lịch.

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/cron/cron_001
```

### PUT /cron/:id/toggle

Bật hoặc tắt một tác vụ mà không xóa nó.

```bash
curl -X PUT -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/cron/cron_001/toggle
```

## Cú pháp lịch

### Cron chuẩn (5 trường)

```
┌───── minute (0-59)
│ ┌───── hour (0-23)
│ │ ┌───── day of month (1-31)
│ │ │ ┌───── month (1-12)
│ │ │ │ ┌───── day of week (0-6, 0=Sunday)
│ │ │ │ │
* * * * *
```

Ví dụ:

| Lịch | Ý nghĩa |
|----------|---------|
| `0 * * * *` | Mỗi giờ |
| `*/15 * * * *` | Mỗi 15 phút |
| `0 9 * * 1-5` | Ngày trong tuần lúc 9 giờ sáng |
| `0 0 * * 0` | Mỗi Chủ nhật lúc nửa đêm |
| `0 0 1 * *` | Ngày đầu tiên mỗi tháng lúc nửa đêm |

### Khoảng cách nguyên (giây)

Đối với các khoảng cách đơn giản, truyền một số nguyên:

```json
{ "schedule": "300" }  // Every 5 minutes
```

## Giới hạn endpoint

> [!WARNING]
> Các endpoint phải là URL `http://` hoặc `https://` trỏ đến:
> - Cùng thể hiện Synapse (ví dụ `http://synapse:12800/memory/recall`)
> - URL HTTPS công khai (không IP riêng, không localhost, không IP metadata)

Điều này ngăn chặn các cuộc tấn công SSRF khi một mind bị xâm phạm có thể lên
lịch các yêu cầu đến dịch vụ nội bộ.

## Các mẫu phổ biến

### Thu hồi bộ nhớ hàng giờ (cho LLM agent)

```bash
curl -X POST .../cron -d '{
  "schedule": "0 * * * *",
  "endpoint": "https://synapse.schaefer.zone/memory/recall",
  "method": "GET",
  "headers": {"Authorization": "Bearer YOUR_MIND_KEY"}
}'
```

### Sao lưu hàng ngày

```bash
curl -X POST .../cron -d '{
  "schedule": "0 2 * * *",
  "endpoint": "https://synapse.schaefer.zone/memory/mind-export",
  "method": "GET",
  "headers": {"Authorization": "Bearer YOUR_MIND_KEY"}
}'
```

### Poll chat định kỳ (mỗi 5 phút)

```bash
curl -X POST .../cron -d '{
  "schedule": "300",
  "endpoint": "https://synapse.schaefer.zone/chat/poll",
  "method": "GET",
  "headers": {"Authorization": "Bearer YOUR_MIND_KEY"}
}'
```

### Kích hoạt báo cáo hàng tuần

```bash
curl -X POST .../cron -d '{
  "schedule": "0 9 * * 1",
  "endpoint": "https://my-app.com/weekly-report",
  "method": "POST",
  "body": "{\"mind_id\": \"m_xyz789\"}",
  "headers": {"Content-Type": "application/json", "X-API-Key": "my-secret"}
}'
```

## Bước tiếp theo

- [Variables API](/docs/api/variables)
- [Webhooks API](/docs/api/webhooks)