# Cron & Scheduler

L'API Cron permet de planifier des appels HTTP récurrents vers des endpoints Synapse
(ou des endpoints HTTPS externes). Parfait pour la synchronisation périodique, les
rappels et les tâches de maintenance.

## Endpoints

### POST /cron

Crée une tâche planifiée.

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

Réponse :

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

Liste toutes les tâches planifiées.

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

### DELETE /cron/:id

Supprime une tâche planifiée.

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

### PUT /cron/:id/toggle

Active ou désactive une tâche sans la supprimer.

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

## Syntaxe de planification

### Cron standard (5 champs)

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

Exemples :

| Planification | Signification |
|----------|---------|
| `0 * * * *` | Toutes les heures |
| `*/15 * * * *` | Toutes les 15 minutes |
| `0 9 * * 1-5` | En semaine à 9 h |
| `0 0 * * 0` | Tous les dimanches à minuit |
| `0 0 1 * *` | Le premier de chaque mois à minuit |

### Intervalle entier (secondes)

Pour des intervalles simples, passez un entier :

```json
{ "schedule": "300" }  // Toutes les 5 minutes
```

## Restrictions sur les endpoints

> [!WARNING]
> Les endpoints doivent être des URLs `http://` ou `https://` pointant vers :
> - La même instance Synapse (ex. `http://synapse:12800/memory/recall`)
> - Des URLs HTTPS publiques (pas d'IP privées, pas de localhost, pas d'IP de métadonnées)

Cela empêche les attaques SSRF où un mind compromis pourrait planifier des requêtes
vers des services internes.

## Schémas courants

### Rappel mémoire horaire (pour les agents LLM)

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

### Sauvegarde quotidienne

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

### Polling périodique du chat (toutes les 5 minutes)

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

### Déclencheur de rapport hebdomadaire

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

## Prochaines étapes

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