# createScheduledTask

Schedule Ask Goliath to run `instruction` as the key owner: give exactly one of `cronExpression` (recurring, 5 fields) or `fireAt` (once), read in `timezone` (IANA). Optional `expiresAt` (it stops after). Each run asks the owner before any action (no abilities). Refused while scheduled tasks are off for the workspace.

- Call: `POST https://server.goliathdata.com/api/v1/call` with `{ "operationId": "createScheduledTask", "variables": {...} }`
- Scope: `WRITE`
- Type: mutation
- Idempotency: honors `Idempotency-Key` (24 h)
- Rate-limited: no

## Variables

- `title`: `String!` (required)
- `instruction`: `String!` (required)
- `timezone`: `String!` (required)
- `cronExpression`: `String`
- `fireAt`: `DateTime`
- `expiresAt`: `DateTime`

## Response (data, an example)

```json
{
  "scheduledTaskMutation": {
    "createScheduledTask": {
      "id": "<ID>",
      "title": "…",
      "instruction": "…",
      "status": "ACTIVE",
      "schedule": "…",
      "nextRunAt": "2026-01-01T00:00:00.000Z",
      "sessionId": "<ID>"
    }
  }
}
```

## Example

```bash
curl https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer $GOLIATH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "operationId": "createScheduledTask",
    "variables": {
      "title": "<String>",
      "instruction": "<String>",
      "timezone": "<String>"
    }
  }'
```