# Cron 및 Scheduler

Cron API를 사용하면 Synapse 엔드포인트 (또는 외부 HTTPS 엔드포인트)에 대한
반복적인 HTTP 호출을 예약할 수 있습니다. 주기적 동기화, 알림 및 유지 관리
작업에 적합합니다.

## 엔드포인트

### POST /cron

예약된 작업을 생성합니다.

```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"}
  }'
```

응답:

```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

모든 예약된 작업을 나열합니다.

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

### DELETE /cron/:id

예약된 작업을 삭제합니다.

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

### PUT /cron/:id/toggle

삭제하지 않고 작업을 활성화 또는 비활성화합니다.

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

## 스케줄 구문

### 표준 cron (5개 필드)

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

예시:

| 스케줄 | 의미 |
|----------|---------|
| `0 * * * *` | 매시 정각 |
| `*/15 * * * *` | 15분마다 |
| `0 9 * * 1-5` | 평일 오전 9시 |
| `0 0 * * 0` | 매주 일요일 자정 |
| `0 0 1 * *` | 매월 1일 자정 |

### 정수 간격 (초)

단순한 간격의 경우 정수를 전달합니다:

```json
{ "schedule": "300" }  // 5분마다
```

## 엔드포인트 제한 사항

> [!WARNING]
> 엔드포인트는 다음을 가리키는 `http://` 또는 `https://` URL이어야 합니다:
> - 동일한 Synapse 인스턴스 (예: `http://synapse:12800/memory/recall`)
> - 공용 HTTPS URL (사설 IP, localhost, 메타데이터 IP 불가)

이는 손상된 마인드가 내부 서비스로 요청을 예약하는 SSRF 공격을
방지합니다.

## 일반적인 패턴

### 시간별 memory recall (LLM 에이전트용)

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

### 일일 백업

```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"}
}'
```

### 주기적 채팅 폴링 (5분마다)

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

### 주간 보고서 트리거

```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"}
}'
```

## 다음 단계

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