Events API

Create, update, and manage scheduled events and workflows

Overview

Events define jobs to run including what, when, and how. Use these endpoints to list, fetch, create, update, delete events, and trigger runs immediately.

List Events

GET /api/app/get_events/v1

Fetch all event definitions. No specific privilege is required beyond a valid user session or API Key.

Response

code · number · required

Response code (0 = success)

rows · array · required

Array of event objects

list · object · required

Metadata including total length

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  https://your-server.com/api/app/get_events/v1

Response

{
  "code": 0,
  "rows": [
    {
      "id": "event100",
      "title": "Daily Backup",
      "enabled": true,
      "category": "maintenance",
      "targets": ["main"],
      "plugin": "shellplug",
      "triggers": [
        {
          "type": "schedule",
          "enabled": true,
          "hours": [2],
          "minutes": [0]
        }
      ]
    }
  ],
  "list": { "length": 1 }
}

Get Event

GET /api/app/get_event/v1

Fetch a single event definition by ID including currently active jobs.

Parameters

id · string · required

Event ID to fetch

Response

event · object

Complete event definition

jobs · array

Array of currently active jobs for this event

queued · number

Count of queued jobs

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://your-server.com/api/app/get_event/v1?id=event100"

Create Event

POST /api/app/create_event/v1

Create a new event definition. Requires the create_events privilege.

Parameters

title · string · required

Display name for the event

enabled · boolean · required

Whether the event is active

category · string · required

Category ID for organization

targets · array · required

Array of server group IDs or hostnames to run on

plugin · string · required

Plugin ID to execute

algo · string · required

Target selection algorithm: random, round_robin, least_cpu, least_mem, prefer_first, or multiplex

params · object

Plugin-specific parameters

triggers · array

Array of trigger definitions (schedule, manual, etc.)

limits · array

Resource limits (memory, CPU, time, etc.)

actions · array

Actions to perform on job completion

id · string

Custom event ID (auto-generated if omitted)

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "title": "Daily Backup",
    "enabled": true,
    "category": "maintenance",
    "targets": ["main"],
    "plugin": "shellplug",
    "algo": "random",
    "params": {
      "script": "#!/bin/bash\n\nbackup.sh\n"
    },
    "triggers": [
      {
        "type": "schedule",
        "enabled": true,
        "hours": [2],
        "minutes": [0]
      }
    ]
  }' \
  https://your-server.com/api/app/create_event/v1

Update Event

POST /api/app/update_event/v1

Update an existing event. Requires the edit_events privilege. The request is shallow-merged into the existing event.

Parameters

id · string · required

Event ID to update

... · any

Any event properties to update (title, enabled, params, etc.)

update_state · object

Optional state updates (e.g., cursor for catch-up mode)

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "id": "event100",
    "enabled": false
  }' \
  https://your-server.com/api/app/update_event/v1

Delete Event

POST /api/app/delete_event/v1

Delete an event definition. Requires the delete_events privilege. Deletion is blocked if any jobs are currently active.

Parameters

id · string · required

Event ID to delete

delete_jobs · boolean

If true, also delete all historical jobs for this event (performed in background)

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "id": "event100",
    "delete_jobs": true
  }' \
  https://your-server.com/api/app/delete_event/v1

Run Event

POST /api/app/run_event/v1

Run an event on demand with optional parameter overrides. Requires the run_jobs privilege.

Parameters

id · string

Event ID to run (either id or title required)

title · string

Event title to run (alternative to id)

params · object

Override event parameters

input · object

Optional input data or files for the job

test · boolean

If true, bypasses manual trigger and enabled checks

Response

id · string

The newly created job ID

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "id": "event100",
    "params": {
      "custom_param": "value"
    }
  }' \
  https://your-server.com/api/app/run_event/v1

Get Event History

GET /api/app/get_event_history/v1

Fetch revision history for a specific event from the activity log.

Parameters

id · string · required

Event ID

offset · number

Row offset for pagination (default: 0)

limit · number

Row limit for pagination (default: 1)

Response

{
  "code": 0,
  "rows": [
    {
      "action": "event_update",
      "username": "admin",
      "description": "Updated title",
      "date": 1234567890
    }
  ],
  "list": { "length": 1 }
}

Events must have an enabled manual trigger to be run via the API, unless you pass test: true.