Create Agent API

Create a new scheduled agent via the external API. The agent is immediately ACTIVE upon creation — no separate activation step is needed.

Create Agent

POST /v1/agents

Required fields:

Field	Type	Description
`name`	string	Display name for the agent
`baseUrl`	string	The website URL the agent will operate on (e.g. `https://example.com`)
`mode`	string	Must be `"SCHEDULED"`

Optional fields:

Field	Type	Description
`content`	string	Task instructions / context passed to the agent as its system prompt
`schedule`	object or string	Schedule configuration. Defaults to daily at 09:00 if omitted
`credentials`	object	Not yet supported via the external API. Use the app dashboard to set credentials after creating the agent

Minimal example:


curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Price Monitor",
    "baseUrl": "https://example.com/prices",
    "mode": "SCHEDULED"
  }' \
  "$EXTERNAL_API_ENDPOINT/v1/agents"

Full example with schedule and credentials:


curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Inventory Check",
    "baseUrl": "https://shop.example.com",
    "mode": "SCHEDULED",
    "content": "Navigate to the inventory page and extract the current stock levels for all SKUs. Return the data as a structured list.",
    "schedule": {
      "mode": "SCHEDULED",
      "tasksPerDay": 2,
      "times": ["09:00", "17:00"]
    },
    "credentials": {
      "username": "myuser",
      "password": "secret"
    }
  }' \
  "$EXTERNAL_API_ENDPOINT/v1/agents"

Response — 201 Created:


{
  "data": {
    "id": "agent-123",
    "userId": "user-789",
    "name": "Daily Inventory Check",
    "baseUrl": "https://shop.example.com",
    "content": "Navigate to the inventory page...",
    "schedule": "{\"mode\":\"SCHEDULED\",\"tasksPerDay\":2,\"times\":[\"09:00\",\"17:00\"]}",
    "scheduleId": "agent-agent-123",
    "mode": "SCHEDULED",
    "status": "ACTIVE",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
}

Error responses:

Status	Reason
`400`	Missing `name`, `baseUrl`, or `mode`; or `mode` is not `"SCHEDULED"`
`401`	Missing or invalid API key
`500`	Internal server error

Schedule Object

The schedule field controls when the agent runs. It can be passed as a JSON object or a JSON string. All times are in UTC.

Frequency modes

Manual (run on demand only)

No automatic scheduling. Use POST /v1/agents/:agentId/execute to trigger runs.


{
  "mode": "SCHEDULED",
  "times": []
}

Daily — one or more fixed times per day


{
  "mode": "SCHEDULED",
  "tasksPerDay": 2,
  "times": ["09:00", "17:00"]
}

Field	Type	Notes
`tasksPerDay`	integer 1–24	Number of times to run each day
`times`	string[]	UTC times in `HH:mm` format, one per task. Must have at least 5 minutes between entries

Note: EventBridge Scheduler supports one expression per schedule. If tasksPerDay > 1, only times[0] is used for the first run. Multi-time support requires one schedule per time slot and may be expanded in a future release.

Interval — repeat every N hours


{
  "mode": "SCHEDULED",
  "rateMinutes": 120
}

Field	Type	Notes
`rateMinutes`	integer	Interval in minutes (e.g. `60` = every hour, `120` = every 2 hours). Range: 1–1440

Weekly — specific days at a fixed time


{
  "mode": "SCHEDULED",
  "cronExpression": "cron(0 9 ? * MON,WED,FRI *)"
}

Field	Type	Notes
`cronExpression`	string	Standard EventBridge cron expression . Year field is required

One-time run


{
  "mode": "ONCE",
  "at": "2026-06-15T14:30",
  "cronExpression": "cron(30 14 15 6 ? 2026)"
}

Field	Type	Notes
`mode`	string	Must be `"ONCE"` (not `"SCHEDULED"`)
`at`	string	ISO-8601 datetime without timezone (treated as UTC)
`cronExpression`	string	Matching EventBridge cron expression. The schedule is automatically deleted after the run

Schedule resolution

When the agent is created, the schedule JSON is parsed and translated into an AWS EventBridge Scheduler expression:

Schedule input	EventBridge expression
`times: ["09:00"]`	`cron(0 9 * * ? *)`
`rateMinutes: 60`	`rate(60 minutes)`
Custom `cronExpression`	Used as-is
`mode: "ONCE"`	`cronExpression` field, then auto-deleted
`times: []` (manual)	No schedule created

A flexible time window of ±5 minutes is applied to all scheduled (non-ONCE) runs so AWS can stagger load.

After Creation

Once created, the agent is ACTIVE and its schedule is live. You can:

Trigger an immediate run → POST /v1/agents/:agentId/execute
Update the schedule → PATCH /v1/agents/:agentId
Pause automatic runs → POST /v1/agents/:agentId/pause
Check execution history → GET /v1/agents/:agentId/events