# Cron & Scheduler

The Cron API lets you schedule recurring HTTP calls to Synapse endpoints (or
external HTTPS endpoints). Perfect for periodic sync, reminders, and
maintenance tasks.

## Endpoints

### POST /cron

Create a scheduled task.

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

Response:

```json
{
  "id": "uuid-here",
  "schedule": "*/15 * * * *",
  "endpoint": "https://synapse.schaefer.zone/memory/recall",
  "method": "GET",
  "enabled": true,
  "next_run": 1751023200,
  "created_at": 1751019600
}
```

### GET /cron

List all scheduled tasks for the authenticated mind.

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

### DELETE /cron/:id

Delete a scheduled task.

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

### PUT /cron/:id/toggle

Enable or disable a task without deleting it.

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

## Schedule Syntax

> [!IMPORTANT]
> Synapse uses a **simplified scheduler** — NOT full 5-field cron. Only the three formats below are supported. Standard cron expressions like `0 9 * * 1-5` or `30 4 * * *` will be **rejected** with `invalid_schedule`.

### Supported formats

| Format | Example | Meaning |
|--------|---------|----------|
| Integer (seconds) | `"300"` | Every 300 seconds (5 minutes) |
| `*/N * * * *` | `"*/15 * * * *"` | Every 15 minutes |
| `* */N * * *` | `"* */2 * * *"` | Every 2 hours |

### NOT supported (will be rejected)

| Schedule | Why it fails |
|----------|-------------|
| `0 * * * *` | Fixed minute without `*/N` — use `"3600"` (seconds) instead |
| `0 9 * * 1-5` | Day-of-week ranges not supported |
| `0 0 1 * *` | Day-of-month fields not supported |
| `30 4 * * *` | Fixed hour:minute not supported |

## Endpoint Restrictions

> [!WARNING]
> Endpoints must be `http://` or `https://` URLs pointing to:
> - The same Synapse instance (e.g. `http://synapse:12800/memory/recall`)
> - Public HTTPS URLs (no private IPs, no localhost, no metadata IPs)

This prevents SSRF attacks where a compromised mind could schedule requests to
internal services.

## Common Patterns

### Periodic memory recall (every 15 minutes)

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

### Hourly chat poll (integer seconds)

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

### Bi-daily sync

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

## Next Steps

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