Skip to main content

Triggers Commands

See Triggers module docs for permissions and data model.

soat list-triggers​

List triggers

  • Method: GET
  • Path: /api/v1/triggers

Usage​

soat list-triggers

Options​

--project-id​

—

  • Source: query
  • Required: no
  • Type: string
--type​

—

  • Source: query
  • Required: no
  • Type: enum("manual", "webhook", "schedule", "event")
--target-type​

—

  • Source: query
  • Required: no
  • Type: enum("orchestration", "agent", "tool", "eval")

soat create-trigger​

Create a trigger

  • Method: POST
  • Path: /api/v1/triggers

Usage​

soat create-trigger --name <string> --type <enum("manual", "webhook", "schedule", "event")> --target-type <enum("orchestration", "agent", "tool", "eval")> --target-id <string>

Options​

--project-id​

Public ID of the project. Optional when authenticating with a project-scoped API key, which defaults to the key's project; required otherwise.

  • Source: body
  • Required: no
  • Type: string
--name​

—

  • Source: body
  • Required: yes
  • Type: string
--description​

—

  • Source: body
  • Required: no
  • Type: string
--type​

—

  • Source: body
  • Required: yes
  • Type: enum("manual", "webhook", "schedule", "event")
--target-type​

—

  • Source: body
  • Required: yes
  • Type: enum("orchestration", "agent", "tool", "eval")
--target-id​

—

  • Source: body
  • Required: yes
  • Type: string
--action​

Tool targets only — the action for builtin/mcp tools

  • Source: body
  • Required: no
  • Type: string
--input​

—

  • Source: body
  • Required: no
  • Type: object
--tool-context​

Caller context every firing forwards to the run it starts, so an agent whose tools authorize through \{\{context:<key>\}\} can be put on a schedule — a firing has no request to carry one. Each key is forwarded as one X-Soat-Context-<key> header. Write-only. It is accepted here and never returned on a read, so the record cannot be used to recover a value. A value may be a \{\{secret:sec_...\}\} reference, which keeps the credential in the secret store and leaves only its id on the trigger; it is resolved at fire time, so rotating the secret changes the next firing without touching the trigger. A reference is refused here rather than at fire time when it is not in that id form (a secret's name does not resolve) or names a secret that does not exist in this project.

  • Source: body
  • Required: no
  • Type: object<string, string>
--cron​

5-field cron expression (UTC). Required when type is schedule

  • Source: body
  • Required: no
  • Type: string
--event-pattern​

Internal-event subscription pattern. Required when type is event, rejected otherwise. * matches every event, prefix.* a namespace, or give an exact event name such as documents.ingested

  • Source: body
  • Required: no
  • Type: string
--active​

—

  • Source: body
  • Required: no
  • Type: boolean
  • Default: true
--policy-id​

—

  • Source: body
  • Required: no
  • Type: string

soat get-trigger​

Get a trigger

  • Method: GET
  • Path: /api/v1/triggers/{trigger_id}

Usage​

soat get-trigger --trigger-id <string>

Options​

--trigger-id​

—

  • Source: path
  • Required: yes
  • Type: string

soat update-trigger​

Update a trigger

  • Method: PATCH
  • Path: /api/v1/triggers/{trigger_id}

Usage​

soat update-trigger --trigger-id <string>

Options​

--trigger-id​

—

  • Source: path
  • Required: yes
  • Type: string
--name​

—

  • Source: body
  • Required: no
  • Type: string
--description​

—

  • Source: body
  • Required: no
  • Type: string \| null
--target-type​

—

  • Source: body
  • Required: no
  • Type: enum("orchestration", "agent", "tool", "eval")
--target-id​

—

  • Source: body
  • Required: no
  • Type: string
--action​

—

  • Source: body
  • Required: no
  • Type: string \| null
--input​

—

  • Source: body
  • Required: no
  • Type: object
--tool-context​

Replaces the stored bag; null clears it. Write-only and resolved at fire time — see CreateTriggerRequest.tool_context.

  • Source: body
  • Required: no
  • Type: object<string, string>
--cron​

—

  • Source: body
  • Required: no
  • Type: string \| null
--event-pattern​

—

  • Source: body
  • Required: no
  • Type: string \| null
--active​

—

  • Source: body
  • Required: no
  • Type: boolean
--policy-id​

—

  • Source: body
  • Required: no
  • Type: string \| null

soat delete-trigger​

Delete a trigger

  • Method: DELETE
  • Path: /api/v1/triggers/{trigger_id}

Usage​

soat delete-trigger --trigger-id <string>

Options​

--trigger-id​

—

  • Source: path
  • Required: yes
  • Type: string

soat fire-trigger​

Fire a trigger

  • Method: POST
  • Path: /api/v1/triggers/{trigger_id}/fire

Usage​

soat fire-trigger --trigger-id <string>

Options​

--trigger-id​

—

  • Source: path
  • Required: yes
  • Type: string
--input​

Fire-time input, shallow-merged over the trigger's static input. For eval targets it may carry agent_version and baseline_run_id.

  • Source: body
  • Required: no
  • Type: object
--tool-context​

Fire-time caller context, shallow-merged per key over the trigger's stored tool_context. A manual fire has a caller, so this is the one path that can supply a value without storing it. Forwarded exactly as written: a \{\{secret:...\}\} reference is resolved only in the trigger's stored bag, never in one supplied here.

  • Source: body
  • Required: no
  • Type: object<string, string>

soat get-trigger-secret​

Get trigger secret

  • Method: GET
  • Path: /api/v1/triggers/{trigger_id}/secret

Usage​

soat get-trigger-secret --trigger-id <string>

Options​

--trigger-id​

—

  • Source: path
  • Required: yes
  • Type: string

soat rotate-trigger-secret​

Rotate trigger secret

  • Method: POST
  • Path: /api/v1/triggers/{trigger_id}/rotate-secret

Usage​

soat rotate-trigger-secret --trigger-id <string>

Options​

--trigger-id​

—

  • Source: path
  • Required: yes
  • Type: string

soat list-trigger-firings​

List trigger firings

  • Method: GET
  • Path: /api/v1/trigger-firings

Usage​

soat list-trigger-firings --trigger-id <string>

Options​

--trigger-id​

Trigger to list firings for (trg_...)

  • Source: query
  • Required: yes
  • Type: string

soat get-trigger-firing​

Get a trigger firing

  • Method: GET
  • Path: /api/v1/trigger-firings/{firing_id}

Usage​

soat get-trigger-firing --firing-id <string>

Options​

--firing-id​

—

  • Source: path
  • Required: yes
  • Type: string