Actions

The Actions API lets you create, manage, and trigger automated response actions. Actions can send notifications, apply remediation steps, call webhooks, or run scripts.

List Actions

GET /api/actions

Query Parameters

Parameter Type Default Description
type string all Filter by type: notification, remediation, webhook, script, approval.
search string Search in action name and description.
page integer 1 Page number.
per_page integer 20 Results per page (max 100).

Example

curl -X GET "https://api.s4e.io/api/actions?type=remediation" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "act-block-ip",
      "name": "Block IP Address",
      "type": "remediation",
      "description": "Block a malicious IP address on the firewall.",
      "version": "1.2.0",
      "executor": "opservant",
      "parameters": [
        {"name": "ip_address", "type": "string", "required": true},
        {"name": "duration_hours", "type": "integer", "required": false, "default": 24}
      ],
      "created_at": "2026-02-10T09:00:00Z"
    }
  ],
  "meta": {
    "total": 15,
    "page": 1,
    "per_page": 20
  }
}

Create Action

POST /api/actions

Request Body

Field Type Required Description
name string Yes Action name.
type string Yes Action type.
description string No Purpose of the action.
executor string Yes Execution target: local, remote, opservant, webhook.
parameters array No Parameter definitions.
config object No Executor-specific configuration.

Example

curl -X POST "https://api.s4e.io/api/actions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Send Slack Alert",
    "type": "notification",
    "description": "Send a notification to a Slack channel.",
    "executor": "webhook",
    "parameters": [
      {"name": "channel", "type": "string", "required": true},
      {"name": "message", "type": "string", "required": true}
    ],
    "config": {
      "url": "https://hooks.slack.com/services/T00/B00/xxx",
      "method": "POST",
      "headers": {"Content-Type": "application/json"},
      "body_template": "{\"channel\": \"{{ channel }}\", \"text\": \"{{ message }}\"}"
    }
  }'

Response (201 Created)

{
  "data": {
    "id": "act-slack-alert",
    "name": "Send Slack Alert",
    "type": "notification",
    "executor": "webhook",
    "version": "1.0.0",
    "created_at": "2026-04-28T12:00:00Z"
  }
}

Get Action Details

GET /api/actions/{id}

curl -X GET "https://api.s4e.io/api/actions/act-block-ip" \
  -H "Authorization: Bearer YOUR_API_KEY"

Trigger Action

POST /api/actions/{id}/trigger

Request Body

Field Type Required Description
target string No Target asset ID.
parameters object Yes Parameter values for execution.
sandbox boolean No Run in sandbox mode (default: false).
dry_run boolean No Validate without executing (default: false).

Example

curl -X POST "https://api.s4e.io/api/actions/act-block-ip/trigger" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "a-1001",
    "parameters": {
      "ip_address": "203.0.113.50",
      "duration_hours": 48
    }
  }'

Response

{
  "data": {
    "execution_id": "exec-9912",
    "action_id": "act-block-ip",
    "status": "running",
    "started_at": "2026-04-28T12:00:00Z"
  }
}

List Action Executions

GET /api/actions/{id}/executions

curl -X GET "https://api.s4e.io/api/actions/act-block-ip/executions?page=1&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "execution_id": "exec-9912",
      "status": "completed",
      "parameters": {"ip_address": "203.0.113.50", "duration_hours": 48},
      "output": {"rule_id": "fw-789", "blocked": true},
      "started_at": "2026-04-28T12:00:00Z",
      "completed_at": "2026-04-28T12:00:05Z",
      "duration_seconds": 5
    }
  ],
  "meta": {"total": 23, "page": 1, "per_page": 10}
}

Get Execution Details

GET /api/actions/executions/{exec_id}

Returns full execution details including output, logs, and error information.

curl -X GET "https://api.s4e.io/api/actions/executions/exec-9912" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "execution_id": "exec-9912",
    "action_id": "act-block-ip",
    "action_name": "Block IP Address",
    "status": "completed",
    "target": "a-1001",
    "parameters": {
      "ip_address": "203.0.113.50",
      "duration_hours": 48
    },
    "output": {
      "rule_id": "fw-789",
      "blocked": true,
      "expires_at": "2026-04-30T12:00:00Z"
    },
    "logs": [
      {"timestamp": "2026-04-28T12:00:01Z", "level": "INFO", "message": "Connecting to firewall API."},
      {"timestamp": "2026-04-28T12:00:03Z", "level": "INFO", "message": "Block rule created: fw-789."},
      {"timestamp": "2026-04-28T12:00:05Z", "level": "INFO", "message": "Action completed successfully."}
    ],
    "started_at": "2026-04-28T12:00:00Z",
    "completed_at": "2026-04-28T12:00:05Z"
  }
}

Action Types

Type Description
notification Send alerts (Slack, email, PagerDuty, webhook).
remediation Apply fixes (block IP, patch, config change).
webhook Call an external HTTP endpoint.
script Execute a script on the agent or platform.
approval Request human approval before proceeding.

Execution States

State Description
pending Execution is queued.
running Execution is in progress.
completed Execution finished successfully.
failed Execution encountered an error.
timeout Execution exceeded the time limit.
cancelled Execution was manually cancelled.

Next Steps