Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agentbot.raveculture.xyz/llms.txt

Use this file to discover all available pages before exploring further.

​
Scheduled tasks API

Schedule recurring prompts for your agents using cron expressions. You can create, update, list, and delete scheduled tasks through these endpoints.
Scheduled tasks are processed by an inline scheduler that runs inside the API process. The scheduler polls for pending tasks every 30 seconds and executes up to 10 tasks per cycle. Each task is dispatched as an HTTP request to the target agent with a 30-second timeout.
Each tick claims due tasks atomically using SELECT ... FOR UPDATE SKIP LOCKED. Tasks are only marked completed when the agent returns a 2xx response. Failed dispatches are re-queued with backoff or marked failed once attempts reaches maxAttempts. See Execution lifecycle below.
All scheduled task endpoints require session authentication. Tasks are scoped to the authenticated user — you can only manage tasks for agents you own.

​
List scheduled tasks

GET /api/scheduled-tasks
Returns all scheduled tasks for the authenticated user, sorted by creation date (newest first).

​
Query parameters

ParameterTypeRequiredDescription
agentIdstringNoFilter tasks by agent ID

​
Response

{
  "tasks": [
    {
      "id": "task_abc123",
      "name": "Daily check-in",
      "description": "Morning status update",
      "cronSchedule": "0 9 * * *",
      "prompt": "Give me a morning briefing on today's schedule and priorities.",
      "enabled": true,
      "lastRun": "2026-03-22T09:00:00Z",
      "nextRun": "2026-03-23T09:00:00Z",
      "status": "pending",
      "attempts": 0,
      "maxAttempts": 5,
      "lastError": null,
      "agentId": "agent_456",
      "createdAt": "2026-03-15T12:00:00Z",
      "updatedAt": "2026-03-22T09:00:00Z"
    }
  ],
  "count": 1
}

​
Task object

FieldTypeDescription
idstringUnique task identifier
namestringTask name
descriptionstring | nullOptional task description
cronSchedulestringCron expression (5 or 6 fields)
promptstringThe prompt sent to the agent on each run
enabledbooleanWhether the task is active
lastRunstring | nullISO 8601 timestamp of the last execution
nextRunstring | nullISO 8601 timestamp of the next scheduled execution
statusstringCurrent execution state. One of pending, running, completed, failed. See Execution lifecycle.
attemptsnumberNumber of dispatch attempts made for the current run. Reset to 0 on the next scheduled trigger.
maxAttemptsnumberMaximum dispatch attempts before the task is marked failed. Defaults to 5.
lastErrorstring | nullError message from the most recent failed dispatch, or null if the last run succeeded.
agentIdstringID of the agent this task targets
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 last-updated timestamp

​
Errors

CodeDescription
401Unauthorized — no valid session
500Failed to list tasks

​
Create a scheduled task

POST /api/scheduled-tasks
Creates a new scheduled task for one of your agents. The cron schedule is validated to ensure it contains 5 or 6 fields.

​
Request body

FieldTypeRequiredDescription
namestringYesTask name
cronSchedulestringYesCron expression with 5 or 6 fields (for example, "0 9 * * *" for daily at 9 AM)
promptstringYesThe prompt to send to the agent on each run
agentIdstringYesID of the agent to target. Must belong to you.
descriptionstringNoOptional description
enabledbooleanNoWhether the task starts active. Defaults to true.

​
Example request

{
  "name": "Weekly fan report",
  "cronSchedule": "0 10 * * 1",
  "prompt": "Generate a weekly fan engagement report with streaming stats and growth trends.",
  "agentId": "agent_456",
  "description": "Runs every Monday at 10 AM"
}

​
Response (201 Created)

Returns the created task object.

​
Errors

CodeDescription
400Missing required fields (name, cronSchedule, prompt, and agentId are required)
400Invalid cron schedule (expected 5–6 fields)
401Unauthorized — no valid session
404Agent not found or does not belong to you
500Task creation failed

​
Update a scheduled task

PUT /api/scheduled-tasks
Updates an existing scheduled task. Only the fields you include in the request body are changed.

​
Request body

FieldTypeRequiredDescription
taskIdstringYesID of the task to update
namestringNoUpdated task name
descriptionstringNoUpdated description
cronSchedulestringNoUpdated cron expression
promptstringNoUpdated prompt
enabledbooleanNoEnable or disable the task

​
Example request

{
  "taskId": "task_abc123",
  "enabled": false
}

​
Response

Returns the updated task object.

​
Errors

CodeDescription
400taskId is required
401Unauthorized — no valid session
404Task not found or does not belong to you
500Task update failed

​
Delete a scheduled task

DELETE /api/scheduled-tasks
Permanently deletes a scheduled task.

​
Request body

FieldTypeRequiredDescription
taskIdstringYesID of the task to delete

​
Response

{
  "success": true,
  "taskId": "task_abc123"
}

​
Errors

CodeDescription
400taskId is required
401Unauthorized — no valid session
404Task not found or does not belong to you
500Task deletion failed

​
Execution lifecycle

Each scheduled task moves through a small state machine driven by the inline scheduler. The status field on the task object reflects the current state.

​
Status values

StatusMeaning
pendingThe task is waiting for its nextRun time. The scheduler will pick it up on the next tick after nextRun <= NOW().
runningThe scheduler has claimed this task and is currently dispatching it to the target agent.
completedThe most recent dispatch succeeded — the agent returned a 2xx response. The task will return to pending and nextRun will advance to the next cron tick.
failedAll maxAttempts dispatches failed. The task is no longer retried automatically. Inspect lastError and re-enable manually by issuing a PUT with enabled: true after fixing the underlying issue.

​
Atomic claim

Each scheduler tick claims due tasks using SELECT ... FOR UPDATE SKIP LOCKED inside a single atomic statement. This guarantees that overlapping ticks, concurrent replicas, or restarted workers can never claim the same task twice. Up to 10 tasks are claimed per tick.

​
Retry behavior

When a dispatch fails — the agent returns a non-2xx status, the request times out, or the network call raises — the task is settled as follows:
  • If attempts < maxAttempts, the task is re-queued. nextRun is set to NOW() + backoff, status is reset to pending, and lastError is updated. The task is picked up again on a future tick.
  • If attempts >= maxAttempts, the task is marked failed and stops retrying.
Backoff schedule (linear with a hard cap):
AttemptBackoff before next retry
130 s
260 s
390 s
4120 s
5150 s
6+300 s (capped)
The backoff is min(30 × attempts, 300) seconds. The default maxAttempts is 5.

​
Stale-claim recovery

If a worker dies mid-dispatch (process crash, container restart, network partition), the task can be left in running state with no worker driving it forward. On every tick, the scheduler scans for tasks that have been running for more than 10 minutes and returns them to pending with nextRun = NOW(), lastError = "Recovered after stale worker lock". They are then picked up on the next tick. You should never see a task stuck in running for more than 10 minutes during normal operation.