Transport

Overview

CueAPI supports two transport modes for delivering executions to your handler:

Webhook transport

The default. CueAPI POSTs a signed payload to your callback URL when the cue fires.

{
  "name": "daily-sync",
  "schedule": {"cron": "0 9 * * *"},
  "callback": {
    "url": "https://api.yourapp.com/webhook",
    "method": "POST"
  }
}

Requirements:

• Public HTTPS URL (HTTP allowed in development only)
• Returns 2xx for success
• Must respond within 30 seconds

What CueAPI sends:

POST https://api.yourapp.com/webhook
X-CueAPI-Signature: v1=abc123...
X-CueAPI-Timestamp: 1710340800
X-CueAPI-Cue-Id: cue_abc123def456
X-CueAPI-Execution-Id: exec-uuid
Content-Type: application/json

{"task": "daily-sync", "kind": "scheduled_task", ...}

Worker transport

For machines without a public URL. A daemon on your machine polls for executions and runs local handler scripts.

{
  "name": "draft-linkedin",
  "schedule": {"cron": "0 9 * * 1-5"},
  "transport": "worker",
  "payload": {
    "task": "draft-linkedin",
    "kind": "agent_turn"
  }
}

How it works:

1. CueAPI creates executions in pending status
2. Your worker daemon polls GET /v1/executions/claimable
3. Worker claims an execution via POST /v1/executions/{id}/claim
4. Worker runs the matched handler script
5. Worker reports the outcome via POST /v1/executions/{id}/outcome

Requirements:

• cueapi-worker daemon running on your machine
• YAML config mapping payload.task to handler scripts
• API key for authentication

Choosing a transport

Specifying transport

Set transport at cue creation:

{
  "name": "my-cue",
  "schedule": {"cron": "0 9 * * *"},
  "transport": "worker",
  "payload": {"task": "my-handler"}
}

{
  "callback": {"transport": "worker"}
}