Automations

Schedule, manage, and inspect subject-scoped background agent runs.

Automations run an agent prompt on a schedule. Each automation belongs to one agent and one stable subjectId, and every occurrence runs in a fresh session with that subject’s persistent workspace and memory. Use the Files API to inspect or seed that workspace from your application.

All schedules use UTC. Herm accepts an ISO timestamp, a one-time duration such as 30m, a recurring interval such as every 2h, or a five-field cron expression.

Create an automation

curl -X POST \
  "https://api.herm.run/v1/agents/agent_123/users/customer_123/automations" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $HERM_API_KEY" \
  -d '{
    "name": "Weekly account summary",
    "prompt": "Review this account and write the weekly summary.",
    "schedule": "0 9 * * 1",
    "skills": ["account-review"],
    "enabled": true
  }'

Field	Type	Required	Description
name	string	No	Display name, up to 200 characters.
prompt	string	Yes	Prompt for each run, up to 5,000 characters.
schedule	string	Yes	ISO timestamp, duration, recurring interval, or five-field UTC cron expression.
skills	string[]	No	Configured skill names to make available, up to 64 entries.
repeat	integer	No	Stop after this many completed occurrences.
enabled	boolean	No	Whether scheduled occurrences can run. Defaults to true.

The response includes the normalized schedule, human-readable scheduleDisplay, nextRunAt, current state, and run counters.

List automations

List automations for one subject:

curl \
  "https://api.herm.run/v1/agents/agent_123/users/customer_123/automations" \
  -H "x-api-key: $HERM_API_KEY"

List automations across all subjects for an agent:

curl "https://api.herm.run/v1/agents/agent_123/automations" \
  -H "x-api-key: $HERM_API_KEY"

Read and update

GET   /v1/agents/{agentId}/users/{subjectId}/automations/{automationId}
PATCH /v1/agents/{agentId}/users/{subjectId}/automations/{automationId}

PATCH accepts any subset of the create fields. Set repeat to null to remove a repeat limit.

Pause, resume, and trigger

POST /v1/agents/{agentId}/users/{subjectId}/automations/{automationId}/pause
POST /v1/agents/{agentId}/users/{subjectId}/automations/{automationId}/resume
POST /v1/agents/{agentId}/users/{subjectId}/automations/{automationId}/trigger

Manual trigger returns the new sessionId and does not change nextRunAt. Pause prevents scheduled occurrences without deleting history; resume computes the next eligible occurrence.

Run history

curl \
  "https://api.herm.run/v1/agents/agent_123/users/customer_123/automations/automation_123/sessions?limit=20" \
  -H "x-api-key: $HERM_API_KEY"

The response lists the fresh sessions created by scheduled and manual runs. Follow each session through the normal event stream.

Delete

DELETE /v1/agents/{agentId}/users/{subjectId}/automations/{automationId}

Deletion stops future runs while preserving historical sessions. Scheduled work is recovered after transient gateway failures, so external side effects should be idempotent.