# agent_trigger_save

Create or Update Agent Trigger

## Beschreibung

Linear-style upsert for cadence rows attached to an
`AgentSchedule`. Pass `id` (prefix `atrg_…`) to update,
omit to create. `agent_schedule_id` is required.

Frequencies and their inputs:
- `hourly` — fires at the top of every hour
- `daily` — needs `run_at` ("HH:MM")
- `weekly` — needs `run_at` + `weekday` (0=Sunday … 6=Saturday)
- `monthly` — needs `run_at` + `day_of_month` (1–31; days
  that don't exist in a given month fall to the last day)
- `cron` — needs `cron_expression` (5-field standard cron,
  parsed by Fugit; uses the trigger's timezone)

`next_run_at` is recomputed on every save — you never set
it directly. DST-aware: timezones like Europe/Berlin keep
the wall-clock hour stable across the March / October
switches.

Authorization delegates to the parent schedule: who can
update the schedule can update its triggers.

## Zugriff

Zugriffsprofil: `gated`. Module: `none`.
Die Freigabe im Profil ersetzt keine Account-, Workspace- oder Rollenberechtigung.

## Parameter

| Name | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `account_id` | string | Ja |  |
| `id` | string | Nein | Trigger prefix id (atrg_…). Omit to create. |
| `agent_schedule_id` | string | Nein | Required on create. |
| `frequency` | string | Nein |  |
| `run_at` | string / null | Nein | Wall-clock time-of-day 'HH:MM' for daily/weekly/monthly. |
| `weekday` | integer / null | Nein | 0=Sunday … 6=Saturday. Weekly only. |
| `day_of_month` | integer / null | Nein | 1–31. Monthly only. |
| `cron_expression` | string / null | Nein | 5-field standard cron. Cron-frequency only. |
| `timezone` | string | Nein | IANA timezone (e.g. 'Europe/Berlin'). Defaults to 'Europe/Berlin' on create. |
| `active` | boolean | Nein | false to retire a cadence row without deleting (scheduler skips inactive triggers). |

## Eingabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "account_id": {
      "type": "string"
    },
    "id": {
      "type": "string",
      "description": "Trigger prefix id (atrg_…). Omit to create."
    },
    "agent_schedule_id": {
      "type": "string",
      "description": "Required on create."
    },
    "frequency": {
      "type": "string",
      "enum": [
        "hourly",
        "daily",
        "weekly",
        "monthly",
        "cron"
      ]
    },
    "run_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "Wall-clock time-of-day 'HH:MM' for daily/weekly/monthly."
    },
    "weekday": {
      "type": [
        "integer",
        "null"
      ],
      "description": "0=Sunday … 6=Saturday. Weekly only."
    },
    "day_of_month": {
      "type": [
        "integer",
        "null"
      ],
      "description": "1–31. Monthly only."
    },
    "cron_expression": {
      "type": [
        "string",
        "null"
      ],
      "description": "5-field standard cron. Cron-frequency only."
    },
    "timezone": {
      "type": "string",
      "description": "IANA timezone (e.g. 'Europe/Berlin'). Defaults to 'Europe/Berlin' on create."
    },
    "active": {
      "type": "boolean",
      "description": "false to retire a cadence row without deleting (scheduler skips inactive triggers)."
    }
  },
  "required": [
    "account_id"
  ],
  "type": "object"
}
```

## Ausgabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "agent_trigger": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "agent_schedule_id": {
          "type": "string"
        },
        "frequency": {
          "type": "string"
        },
        "run_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "weekday": {
          "type": [
            "integer",
            "null"
          ]
        },
        "day_of_month": {
          "type": [
            "integer",
            "null"
          ]
        },
        "cron_expression": {
          "type": [
            "string",
            "null"
          ]
        },
        "timezone": {
          "type": "string"
        },
        "next_run_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "last_run_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "active": {
          "type": "boolean"
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "agent_schedule_id",
        "frequency",
        "timezone",
        "active",
        "created_at"
      ]
    }
  },
  "required": [
    "agent_trigger"
  ],
  "type": "object"
}
```