Triggers

Triggers define how and when agent sessions are created. A trigger is bound to a specific agent and can fire on a cron schedule, after a deployment, or only when manually invoked. Disabled cron triggers are skipped by the scheduler, but manual triggers can always be invoked regardless of the enabled flag.

Service: firetiger.triggers.v1.TriggersService

Resource name pattern: triggers/{trigger_id}

Access: Read-write

Resource type: Trigger

Example flow

Create a manual trigger linked to an agent, then invoke it to kick off a session.

1. Create a manual trigger

curl -X POST "https://api.cloud.firetiger.com/firetiger.triggers.v1.TriggersService/CreateTrigger" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_id": "incident-runbook",
    "trigger": {
      "display_name": "Incident Runbook",
      "description": "Manually invoked to run an incident response playbook",
      "agent": "agents/incident-responder",
      "configuration": {
        "manual": {}
      },
      "enabled": true
    }
  }'

{
  "trigger": {
    "name": "triggers/incident-runbook",
    "displayName": "Incident Runbook",
    "description": "Manually invoked to run an incident response playbook",
    "agent": "agents/incident-responder",
    "configuration": {
      "manual": {}
    },
    "enabled": true,
    "createTime": "2024-08-01T12:00:00Z",
    "updateTime": "2024-08-01T12:00:00Z"
  }
}

2. Invoke the trigger

Pass a message that becomes the initial user activity in the new agent session. The response includes the trigger and the name of the newly created session.

curl -X POST "https://api.cloud.firetiger.com/firetiger.triggers.v1.TriggersService/InvokeTrigger" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "triggers/incident-runbook",
    "message": "There is an ongoing incident affecting checkout. Run the incident response playbook."
  }'

{
  "trigger": {
    "name": "triggers/incident-runbook",
    "displayName": "Incident Runbook",
    "description": "Manually invoked to run an incident response playbook",
    "agent": "agents/incident-responder",
    "configuration": {
      "manual": {}
    },
    "enabled": true,
    "createTime": "2024-08-01T12:00:00Z",
    "updateTime": "2024-08-01T12:00:00Z"
  },
  "session": "agents/incident-responder/sessions/ses-abc123"
}

3. Check the session

Use the session name from the InvokeTrigger response to read messages via the Agent Service.

curl -X POST "https://api.cloud.firetiger.com/firetiger.nxagent.v2.AgentService/Read" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"session": "agents/incident-responder/sessions/ses-abc123", "session_offset": 0}'

Methods

Method	Description
CreateTrigger	Create a new trigger
GetTrigger	Retrieve a trigger by name
UpdateTrigger	Update an existing trigger
DeleteTrigger	Soft-delete a trigger
ListTriggers	List triggers with filtering and pagination
InvokeTrigger	Manually invoke a trigger to create an agent session

CreateTrigger

Create a new trigger.

POST /firetiger.triggers.v1.TriggersService/CreateTrigger

Request body

Field	Type	Required	Description
`trigger_id`	string	No	ID for the new trigger (alphanumeric, hyphens, underscores). Auto-generated if omitted.
`trigger`	Trigger	Yes	The trigger to create

Example – cron trigger

curl -X POST "https://api.cloud.firetiger.com/firetiger.triggers.v1.TriggersService/CreateTrigger" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_id": "daily-health-check",
    "trigger": {
      "display_name": "Daily Health Check",
      "description": "Runs a health check every morning at 9 AM Eastern",
      "agent": "agents/health-checker",
      "configuration": {
        "cron": {
          "schedule": "0 9 * * *",
          "timezone": "America/New_York"
        }
      },
      "enabled": true
    }
  }'

Example – manual trigger

curl -X POST "https://api.cloud.firetiger.com/firetiger.triggers.v1.TriggersService/CreateTrigger" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_id": "incident-runbook",
    "trigger": {
      "display_name": "Incident Runbook",
      "description": "Manually invoked to run an incident response playbook",
      "agent": "agents/incident-responder",
      "configuration": {
        "manual": {}
      },
      "enabled": true
    }
  }'

Example – post-deploy trigger

curl -X POST "https://api.cloud.firetiger.com/firetiger.triggers.v1.TriggersService/CreateTrigger" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_id": "post-deploy-smoke-test",
    "trigger": {
      "display_name": "Post-Deploy Smoke Test",
      "description": "Runs smoke tests 5 minutes after the release SHA lands in production",
      "agent": "agents/smoke-tester",
      "configuration": {
        "post_deploy": {
          "repository": "acme/backend",
          "environment": "production",
          "sha": "abc123def456",
          "delay": "300s"
        }
      },
      "enabled": true
    }
  }'

Response

{
  "trigger": {
    "name": "triggers/daily-health-check",
    "displayName": "Daily Health Check",
    "description": "Runs a health check every morning at 9 AM Eastern",
    "agent": "agents/health-checker",
    "configuration": {
      "cron": {
        "schedule": "0 9 * * *",
        "timezone": "America/New_York"
      }
    },
    "enabled": true,
    "createTime": "2024-08-01T12:00:00Z",
    "updateTime": "2024-08-01T12:00:00Z"
  }
}

GetTrigger

Retrieve a trigger by name.

POST /firetiger.triggers.v1.TriggersService/GetTrigger

Request body

Field	Type	Required	Description
`name`	string	Yes	Resource name of the trigger

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.triggers.v1.TriggersService/GetTrigger" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "triggers/daily-health-check"}'

UpdateTrigger

Update an existing trigger. Use update_mask to specify which fields to modify.

POST /firetiger.triggers.v1.TriggersService/UpdateTrigger

Request body

Field	Type	Required	Description
`trigger`	Trigger	Yes	The trigger with `name` set and updated fields
`update_mask`	string	No	Comma-separated list of fields to update. If omitted, all provided fields are updated.

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.triggers.v1.TriggersService/UpdateTrigger" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger": {
      "name": "triggers/daily-health-check",
      "enabled": false
    },
    "update_mask": "enabled"
  }'

DeleteTrigger

Soft-delete a trigger. The resource will still be accessible via Get but excluded from List results unless show_deleted is set.

POST /firetiger.triggers.v1.TriggersService/DeleteTrigger

Request body

Field	Type	Required	Description
`name`	string	Yes	Resource name of the trigger to delete

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.triggers.v1.TriggersService/DeleteTrigger" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "triggers/daily-health-check"}'

ListTriggers

List triggers with optional filtering and pagination.

POST /firetiger.triggers.v1.TriggersService/ListTriggers

Request body

Field	Type	Required	Description
`filter`	string	No	Filter expression (e.g. `enabled = true`, `agent = "agents/my-agent"`)
`order_by`	string	No	Field to sort by (e.g. `display_name`, `create_time desc`)
`page_size`	integer	No	Maximum results per page
`page_token`	string	No	Token for the next page of results
`show_deleted`	boolean	No	Include soft-deleted triggers

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.triggers.v1.TriggersService/ListTriggers" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"filter": "enabled = true", "page_size": 25}'

Response

{
  "triggers": [
    {
      "name": "triggers/daily-health-check",
      "displayName": "Daily Health Check",
      "agent": "agents/health-checker",
      "configuration": {
        "cron": {
          "schedule": "0 9 * * *",
          "timezone": "America/New_York"
        }
      },
      "enabled": true,
      "createTime": "2024-08-01T12:00:00Z",
      "updateTime": "2024-08-01T12:00:00Z"
    }
  ],
  "nextPageToken": ""
}

InvokeTrigger

Manually invoke a trigger, immediately creating a new agent session. This works for any trigger type – cron, manual, or post-deploy – and works regardless of the enabled flag.

The message field becomes the initial user activity in the new session.

POST /firetiger.triggers.v1.TriggersService/InvokeTrigger

Request body

Field	Type	Required	Description
`name`	string	Yes	Resource name of the trigger to invoke
`message`	string	Yes	Message sent to the agent as the initial user activity in the new session

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.triggers.v1.TriggersService/InvokeTrigger" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "triggers/incident-runbook",
    "message": "There is an ongoing incident affecting checkout. Run the incident response playbook."
  }'

Response

{
  "trigger": {
    "name": "triggers/incident-runbook",
    "displayName": "Incident Runbook",
    "description": "Manually invoked to run an incident response playbook",
    "agent": "agents/incident-responder",
    "configuration": {
      "manual": {}
    },
    "enabled": true,
    "createTime": "2024-08-01T12:00:00Z",
    "updateTime": "2024-08-05T09:15:00Z"
  },
  "session": "agents/incident-responder/sessions/ses-abc123"
}