Rules API

The Rules API lets you manage automation rules programmatically. You can create rules from YAML definitions, toggle their execution mode between disabled, shadow, and live, and manage webhook delivery and HMAC signing.

All endpoints are under /api/rules and require authentication.

Rules are defined using YAML. See the Rules YAML reference for the full schema.

CRUD Operations

POST/api/rulesAuth required

Create a new rule from a YAML definition.


// Request body
{ "yaml": "name: My Rule\ntrigger: push\n..." }

GET/api/rulesAuth required

List all rules. Supports pagination.


GET /api/rules?page=1&pageSize=20

GET/api/rules/:idAuth required

Get a single rule by ID.

PUT/api/rules/:idAuth required

Update an existing rule with new YAML.


// Request body
{ "yaml": "name: Updated Rule\ntrigger: pull_request\n..." }

DELETE/api/rules/:idAuth required

Delete a rule. Requires owner or admin role.

Only workspace owners and admins can delete rules. Members will receive a 403 response.

Rule State Management

POST/api/rules/:id/toggleAuth required

Toggle a rule between enabled and disabled.

POST/api/rules/:id/stateAuth required

Change the rule execution mode.


// Request body
{ "mode": "disabled" | "shadow" | "live" }

Testing

POST/api/rules/:id/testAuth required

Execute the rule in test mode without side effects.

POST/api/rules/:id/test-webhookAuth required

Send a test webhook delivery to verify your endpoint.

Shadow Mode

Shadow mode lets you observe how a rule would behave without actually executing actions. Use confidence stats and shadow logs to validate before promoting to live.

GET/api/rules/:id/confidenceAuth required

Get confidence statistics from shadow mode executions.

GET/api/rules/:id/shadow-logAuth required

Get shadow execution logs. Supports pagination.


GET /api/rules/:id/shadow-log?page=1&pageSize=50

Webhook Deliveries

GET/api/rules/:id/deliveriesAuth required

List webhook deliveries for this rule.


GET /api/rules/:id/deliveries?limit=25&offset=0

GET/api/rules/:id/deliveries/lastAuth required

Get the timestamp of the last successful delivery.

Webhook Security

POST/api/rules/:id/rotate-secretAuth required

Rotate the webhook signing secret. Requires owner or admin role.

POST/api/rules/:id/hmacAuth required

Enable or disable HMAC signature verification. Requires owner or admin role.


// Request body
{ "enabled": true }

Rotating a webhook secret invalidates the previous secret immediately. Update your receiving endpoint before rotating.