SFTPGo Octri Preview
POST/eventrules

Create an event rule

Creates an event rule that connects a trigger and its conditions to an ordered list of actions. Supply name and trigger, configure exactly one applicable condition in conditions, and use actions to specify the actions and their execution order.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 9 body fields
confidential_dataintegeroptional
Set to 1 to include confidential data, including secret keys and additional secret data, in the response. This setting is ignored if you do not have the required permission.

Event rule definition, with an optional ordered list of actions. Provide the required name and trigger, and configure exactly one applicable condition.

conditionsobjectoptional
Defines when a rule triggers. Exactly one of fs_events, provider_events, schedules, or idp_login_event must be configured
created_atintegeroptional
Creation time as Unix timestamp in milliseconds.
descriptionstringoptional
Optional free-form description.
idintegeroptional
Read-only rule identifier populated by the server.
namestringrequired
Unique rule name.
statusintegeroptional
Rule status: * `0` disabled — rule is stored but never fires * `1` enabled
Allowed:01
triggerintegerrequired
Supported event trigger types. Selects which `conditions.*` sub-filter is meaningful on the parent `EventRule`, and which keys of the template context are populated for actions of this rule. * `1` - Filesystem event → filter by `conditions.fs_events[]` (upload, pre-upload, first-upload, download, pre-download, first-download, delete, pre-delete, rename, mkdir, rmdir, copy, ssh_cmd). Populates path/size/elapsed fields in the template context. * `2` - Provider event → filter by `conditions.provider_events[]` (add, update, delete) plus `conditions.options.provider_objects[]` (user, folder, group, admin, api_key, share, event_rule, event_action). Populates `{{.Object}}`. * `3` - Schedule (cron) → filter by `conditions.schedules[]`. Populates only `{{.Timestamp}}` and chained data from earlier actions; no filesystem context. * `4` - IP blocked → no filter. Populates `{{.IP}}`, `{{.Protocol}}`, `{{.Errors}}`. * `5` - Certificate renewal → no filter. Populates `{{.Event}}` (`acme_ok` / `acme_error`), `{{.Errors}}`. * `6` - On demand → no trigger-time filter. Run via `POST /events/rules/{name}/run`; caller may inject a user list which populates `{{.Name}}` per user. * `7` - Identity provider login → filter by `conditions.idp_login_event` (0 any, 1 user only, 2 admin only). Populates `{{.Name}}`, `{{.ExtName}}`, `{{.Role}}`, `{{.Email}}`, `{{.IDPFields}}`, `{{.IP}}`, `{{.Protocol}}` = `OIDC`. Intended for JIT provisioning paired with action `type: 13`.
Allowed:1234567
updated_atintegeroptional
Last update time as Unix timestamp in milliseconds.
actionsarray<object>optional
Ordered list of actions for the rule. Each entry specifies an action `name`, its execution `order`, and optional `relation_options`.

6 status codes
201Returns the created event rule, including its identifier, name, trigger, conditions, and configured actions.
conditionsobjectoptional
Defines when a rule triggers. Exactly one of fs_events, provider_events, schedules, or idp_login_event must be configured
created_atintegeroptional
Creation time as Unix timestamp in milliseconds.
descriptionstringoptional
Optional free-form description.
idintegeroptional
namestringrequired
Unique rule name.
statusintegeroptional
Rule status: * `0` disabled — rule is stored but never fires * `1` enabled
Allowed:01
triggerintegerrequired
Supported event trigger types. Selects which `conditions.*` sub-filter is meaningful on the parent `EventRule`, and which keys of the template context are populated for actions of this rule. * `1` - Filesystem event → filter by `conditions.fs_events[]` (upload, pre-upload, first-upload, download, pre-download, first-download, delete, pre-delete, rename, mkdir, rmdir, copy, ssh_cmd). Populates path/size/elapsed fields in the template context. * `2` - Provider event → filter by `conditions.provider_events[]` (add, update, delete) plus `conditions.options.provider_objects[]` (user, folder, group, admin, api_key, share, event_rule, event_action). Populates `{{.Object}}`. * `3` - Schedule (cron) → filter by `conditions.schedules[]`. Populates only `{{.Timestamp}}` and chained data from earlier actions; no filesystem context. * `4` - IP blocked → no filter. Populates `{{.IP}}`, `{{.Protocol}}`, `{{.Errors}}`. * `5` - Certificate renewal → no filter. Populates `{{.Event}}` (`acme_ok` / `acme_error`), `{{.Errors}}`. * `6` - On demand → no trigger-time filter. Run via `POST /events/rules/{name}/run`; caller may inject a user list which populates `{{.Name}}` per user. * `7` - Identity provider login → filter by `conditions.idp_login_event` (0 any, 1 user only, 2 admin only). Populates `{{.Name}}`, `{{.ExtName}}`, `{{.Role}}`, `{{.Email}}`, `{{.IDPFields}}`, `{{.IP}}`, `{{.Protocol}}` = `OIDC`. Intended for JIT provisioning paired with action `type: 13`.
Allowed:1234567
updated_atintegeroptional
Last update time as Unix timestamp in milliseconds.
actionsarray<object>optional
400Returned when the request is invalid, including when required fields are missing or values fail validation.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
401Returned when the request is unauthenticated.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
403Returned when the caller does not have permission to create the event rule.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
500Returned when an internal server error occurs.
errorstringoptional
error description if any
messagestringoptional
message, can be empty
defaultUnexpected Error
errorstringoptional
error description if any
messagestringoptional
message, can be empty

Error handling

A 400 indicates an invalid request, a 401 indicates missing or invalid authentication, a 403 indicates insufficient permission, and a 500 indicates an internal server error. name and trigger are required; trigger must be one of 1, 2, 3, 4, 5, 6, or 7, and status, if supplied, must be 0 or 1. Configure exactly one of conditions.fs_events, conditions.provider_events, conditions.schedules, or conditions.idp_login_event.