Schedules & Triggers API

Automate agent execution with cron-based schedules, webhook triggers, and event-driven invocation. Schedule endpoints use the /api/agents/:name/schedules base path. Schedules are executed by a dedicated scheduler service.

All endpoints require JWT Bearer token unless noted. See Authentication for details. Full interactive API docs at http://localhost:8000/docs.

Schedule CRUD

GET

/api/agents/:name/schedules

List all schedules for an agent.

curl -H "Authorization: Bearer <token>" \
  http://localhost:8000/api/agents/research-agent/schedules

# Response
[
  {
    "id": "sch_abc123",
    "agent_name": "research-agent",
    "name": "Daily Report",
    "cron_expression": "0 9 * * *",
    "message": "Generate the daily research report",
    "enabled": true,
    "timezone": "UTC",
    "timeout_seconds": 900,
    "next_run_at": "2026-03-27T09:00:00Z",
    "last_run_at": "2026-03-26T09:00:00Z"
  }
]

POST

/api/agents/:name/schedules

Create a new schedule for an agent. The cron expression is validated server-side.

Name	Type	Required	Description
name	string	Yes	Display name for the schedule
cron_expression	string	Yes	Standard cron syntax, e.g. "0 9 * * *"
message	string	Yes	The task message sent to the agent
enabled	boolean	No	Whether schedule is active (default: true)
timezone	string	No	IANA timezone (default: "UTC")
description	string	No	Human-readable description
timeout_seconds	integer	No	Execution timeout (default: 900)
allowed_tools	string[]	No	Restrict tools available during execution
model	string	No	Model override (e.g. "opus", "sonnet")

curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Report",
    "cron_expression": "0 9 * * *",
    "message": "Generate the daily research report",
    "timezone": "America/New_York",
    "timeout_seconds": 600
  }' \
  http://localhost:8000/api/agents/research-agent/schedules

# Response (201 Created)
{
  "id": "sch_abc123",
  "agent_name": "research-agent",
  "name": "Daily Report",
  "cron_expression": "0 9 * * *",
  "enabled": true,
  "timezone": "America/New_York",
  "timeout_seconds": 600,
  "created_at": "2026-03-26T12:00:00Z"
}

GET

/api/agents/:name/schedules/:id

Get a specific schedule by ID.

PUT

/api/agents/:name/schedules/:id

Update a schedule. Only include fields you want to change.

Name	Type	Required	Description
name	string	No	Updated display name
cron_expression	string	No	Updated cron expression
message	string	No	Updated task message
enabled	boolean	No	Enable or disable
timezone	string	No	Updated timezone
timeout_seconds	integer	No	Updated timeout

DELETE

/api/agents/:name/schedules/:id

Delete a schedule. Returns 204 No Content on success.

Schedule Control

POST

/api/agents/:name/schedules/:id/enable

Enable a schedule. The dedicated scheduler picks up the change automatically.

POST

/api/agents/:name/schedules/:id/disable

Disable a schedule without deleting it.

POST

/api/agents/:name/schedules/:id/trigger

Manually trigger a schedule execution immediately. Delegates to the dedicated scheduler service which handles distributed locking, execution tracking, and agent execution.

curl -X POST -H "Authorization: Bearer <token>" \
  http://localhost:8000/api/agents/research-agent/schedules/sch_abc123/trigger

# Response
{
  "status": "triggered",
  "schedule_id": "sch_abc123",
  "schedule_name": "Daily Report",
  "agent_name": "research-agent",
  "message": "Execution started"
}

Execution History

GET

/api/agents/:name/schedules/:id/executions

Get execution history for a specific schedule.

Name	Type	Required	Description
limit	integer	No	Max results (default: 50)

GET

/api/agents/:name/executions

Get execution summaries for an agent. Returns lightweight objects optimized for list views (large fields like response and logs excluded).

curl -H "Authorization: Bearer <token>" \
  http://localhost:8000/api/agents/research-agent/executions

# Response
[
  {
    "id": "exec_xyz789",
    "schedule_id": "sch_abc123",
    "agent_name": "research-agent",
    "status": "success",
    "started_at": "2026-03-26T09:00:00Z",
    "completed_at": "2026-03-26T09:05:30Z",
    "duration_ms": 330000,
    "message": "Generate the daily research report",
    "triggered_by": "schedule",
    "cost": 0.045,
    "model_used": "claude-sonnet-4-20250514"
  }
]

GET

/api/agents/:name/executions/:id

Get full details of a specific execution including response text, errors, and tool calls.

GET

/api/agents/:name/executions/:id/log

Get the full execution transcript as a JSON array. Includes all tool calls, thinking steps, and responses from the Claude Code session.

Webhook Triggers

External event triggers and internal execution endpoints for programmatic agent invocation.

Internal Execution (No Auth)

The /api/internal/* endpoints are not authenticated and should only be accessible within the Docker network. They are used by the scheduler service and agent containers.

POST

/api/internal/execute-task

Execute a task internally. Used by the scheduler service, supports async_mode for background execution.

POST

/api/internal/decrypt-and-inject

Auto-import credentials on agent startup. Called internally during the container boot process.

Process Triggers

POST

/api/processes/:id/execute

Start a process execution by ID.

Slack Events

POST

/api/public/slack/events

Slack event receiver endpoint. Handles incoming Slack events and routes them to the appropriate agent.

Event Emission

POST

/api/events

Emit an event that triggers agent subscriptions. Any agent subscribed to the event type will be invoked.

POST

/api/agents/:name/emit-event

Emit an event for a specific agent. The event is scoped to that agent's subscriptions.

Cron Expression Format

Trinity uses standard 5-field cron expressions. The dedicated scheduler evaluates them with timezone support.

# Format: minute hour day-of-month month day-of-week
#
# Examples:
# Every day at 9 AM:          0 9 * * *
# Every hour:                  0 * * * *
# Every 15 minutes:            */15 * * * *
# Weekdays at 8:30 AM:        30 8 * * 1-5
# First day of month at noon: 0 12 1 * *

Schedule Model

Field	Type	Description
id	string	Unique schedule ID
agent_name	string	Owning agent name
name	string	Display name
cron_expression	string	5-field cron expression
message	string	Task message sent to agent
enabled	boolean	Whether schedule is active
timezone	string	IANA timezone
timeout_seconds	integer	Execution timeout (default: 900)
model	string?	Model override for this schedule
next_run_at	datetime?	Next scheduled execution time
last_run_at	datetime?	Last execution time

Error Responses

Status	Meaning
400	Invalid cron expression
401	Invalid or missing JWT token
403	Access denied to agent or schedule
404	Schedule or agent not found
503	Scheduler service unavailable
504	Scheduler service timeout

Skills API Guides