Automations

Create automation

curl -X POST http://localhost:6877/automations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Morning briefing",
    "prompt": "Summarize unread emails and today's calendar. Report the briefing in the automation channel.",
    "description": "Weekday morning briefing",
    "trigger_type": "time",
    "at": "09:00",
    "days": "weekdays",
    "idempotency_key": "automation:morning-briefing",
    "idempotency_scope": "global"
  }'

Notifier configuration is separate from automation creation. Use the notification/notifier settings or /notifiers/* endpoints.

Idempotent creation

Every standalone POST /automations request must include a stable semantic idempotency_key and idempotency_scope: "global". Reuse that exact key only to retry an ambiguous create. If an automation with that key already exists, inspect it and use PATCH /automations/{task_id} for changes; do not create a versioned replacement key. Deleting the automation releases its global key, allowing the same job to be recreated without renaming the key.

Trigger options

Scheduled:

{"trigger_type": "time", "at": "09:00", "days": "weekdays"}
{"trigger_type": "time", "at": "22:00", "days": "mon,wed,fri"}
{"trigger_type": "time", "at": "08:00"}

Interval:

{"trigger_type": "time", "every": "2h"}
{"trigger_type": "time", "every": "30m", "start": "09:00", "end": "18:00"}

Event-driven:

{"trigger_type": "event", "event_type": "event_approaching", "lead_minutes": 15}

Idle:

{"trigger_type": "idle", "idle_minutes": 5}

Count:

{"trigger_type": "count", "every_n": 3}

Multiple and message triggers

Pass a triggers array to combine triggers with OR logic. Each item uses type, not the top-level trigger_type field:

curl -X POST http://localhost:6877/automations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Extract facts",
    "prompt": "Extract durable facts from recent conversation.",
    "description": "Conversation fact extraction",
    "triggers": [
      {"type": "count", "every_n": 5},
      {"type": "idle", "idle_minutes": 10}
    ],
    "cooldown_minutes": 10,
    "idempotency_key": "automation:extract-facts",
    "idempotency_scope": "global"
  }'

Slack message triggers also use triggers. Supply channel names; Arden resolves and stores stable Slack IDs when it saves the automation.

{
  "triggers": [{
    "type": "message",
    "source": "slack",
    "channels": ["alerts"],
    "from_user": "incident-bot",
    "contains": ["incident"]
  }]
}

Tool scoping and approval

tool_scope names the contract an automation’s runs execute under. It accepts exactly two values:

Value	Effect
`"read_only"`	Every read-only tool, nothing else. Applied when the field is omitted.
`"all"`	Every tool.

auto_approve=true skips per-run approvals for tools the scope already grants and never expands it.

{
  "name": "Publish the ops page",
  "prompt": "Refresh the ops summary page.",
  "tool_scope": "all",
  "auto_approve": true,
  "idempotency_key": "automation:ops-page",
  "idempotency_scope": "global"
}

A wiki-writing prompt should list the target directory before creating a page, and read the exact path before editing one. The backend protects a fresh read from being overwritten; on a write conflict, list/read again before retrying. Ordinary automation pages belong under automations/. wiki_publish_generated is separate: use it only for a section owned by that automation. Responses also carry tool_scope_label, a rendering of what the scope actually grants (for example read | wiki_create_page | wiki_edit_page). It is informational — the server owns the wording. Arden’s own custodians and workers run under finer contracts assigned in code (area_observe, wiki_producer, daily_notes, and others). Those names appear in tool_scope on read, but the API will not accept them on create or update.

List automations

curl http://localhost:6877/automations \
  -H "Authorization: Bearer $API_KEY"

Get automation

curl http://localhost:6877/automations/1 \
  -H "Authorization: Bearer $API_KEY"

Update automation

curl -X PATCH http://localhost:6877/automations/1 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "New standalone task instructions"}'

Toggle enable/disable

curl -X POST http://localhost:6877/automations/1/toggle \
  -H "Authorization: Bearer $API_KEY"

Toggle auto-approve

Allow a headless automation to skip per-call approval for mutating/external tools its tool_scope already grants. This setting does not widen the scope:

curl -X POST http://localhost:6877/automations/1/auto-approve \
  -H "Authorization: Bearer $API_KEY"

The response includes the updated auto_approve value.

Run immediately

curl -X POST http://localhost:6877/automations/1/run \
  -H "Authorization: Bearer $API_KEY"

Runs and events

curl http://localhost:6877/automations/1/runs \
  -H "Authorization: Bearer $API_KEY"

curl http://localhost:6877/automations/events \
  -H "Authorization: Bearer $API_KEY"

Delete automation

curl -X DELETE http://localhost:6877/automations/1 \
  -H "Authorization: Bearer $API_KEY"

Loops

Loops run repeatedly in an existing chat and stop when their condition is met. They do not create a separate automation channel.

Method	Endpoint	Purpose
`POST`	`/loops`	Create a loop for a `session_id`
`GET`	`/loops?session_id=...`	List one chat’s loops
`PATCH`	`/loops/{task_id}`	Change prompt, cadence, limits, or enabled state
`DELETE`	`/loops/{task_id}`	Stop and remove a loop

Overview

Endpoints

Create automation

Idempotent creation

Trigger options

Multiple and message triggers

Tool scoping and approval

List automations

Get automation

Update automation

Toggle enable/disable

Toggle auto-approve

Run immediately

Runs and events

Delete automation

Loops

​Create automation

​Idempotent creation

​Trigger options

​Multiple and message triggers

​Tool scoping and approval

​List automations

​Get automation

​Update automation

​Toggle enable/disable

​Toggle auto-approve

​Run immediately

​Runs and events

​Delete automation

​Loops

Create automation

Idempotent creation

Trigger options

Multiple and message triggers

Tool scoping and approval

List automations

Get automation

Update automation

Toggle enable/disable

Toggle auto-approve

Run immediately

Runs and events

Delete automation

Loops