Job Queue

Durable background processing backed by PostgreSQL. Jobs survive Core restarts. AI Agents can enqueue jobs via MCP tools.

Job Lifecycle

pending → running → completed / failed

Reliability

• Persistence: jobs are stored in PostgreSQL and survive Core restarts.
• Atomic claim: jobs are claimed via SELECT ... FOR UPDATE SKIP LOCKED, preventing duplicate dispatch.
• Idempotency: handlers should be idempotent as a best practice.

Using Studio

View job status in the Operations panel. The panel shows queued, running, completed, and failed jobs with their payloads and results. Filter by status to monitor active work or investigate failures.

Using Code

Enqueue a Job

POST /api/v1/apps/{appId}/jobs
{
  "payload": { "type": "email", "to": "user@example.com" }
}

Returns a job_id. The job is persisted immediately in rootcx_system.jobs and picked up by the scheduler as soon as a worker is available.

Handle Jobs in Your Backend

Use the onJob lifecycle hook in serve() to handle jobs:

serve({}, {
  onJob: async (payload) => {
    if (payload.type === "email") {
      await sendEmail(payload.to);
      return { delivered: true };
    }
  },
});

Return a value to mark the job as completed, or throw to mark it as failed.

Query Jobs

GET /api/v1/apps/{appId}/jobs/:id

Returns job status, payload, result (if completed), and error (if failed).

GET /api/v1/apps/{appId}/jobs?status=pending

List jobs filtered by status.