Your API key:

All requests below will use this key. Your API key is sent directly to api.cueapi.ai and never stored by the docs site.

POST/v1/cues

Create a Cue

namestringrequiredbody

Human-readable name for the cue. Max 255 characters.

scheduleobjectrequiredbody

callbackobjectbody

transportstringdefault: webhookbody

"webhook" or "worker". Worker transport does not require a callback URL.

payloadobjectbody

JSON payload delivered with each execution. Any valid JSON.

descriptionstringbody

Optional description of what this cue does.

retryobjectbody

on_failureobjectbody

Controls what happens after all retry attempts are exhausted. See the On-Failure Escalation guide for details.

deliveryobjectbody

Two-phase delivery configuration.

timeout_seconds (integer, default: 30) - How long to wait for HTTP 200 ACK (1-3600)
outcome_deadline_seconds (integer, default: 300) - How long to wait for outcome report after ACK (1-3600)

alertsobjectbody

Proactive alerting configuration.

consecutive_failures (integer, default: 3) - Alert after N consecutive failures (1-100)
missed_window_multiplier (integer, default: 2) - Alert when no success in schedule interval x N (1-10)

catch_upstringdefault: run_once_if_missedbody

Behavior when executions are missed during downtime. One of:

skip_missed - Fast-forward to next future window, create no backfill executions
run_once_if_missed - Run once to catch up, then resume normal schedule (default)
replay_all_missed - Create executions for every missed window (capped at 100)

verificationobjectbody

Outcome verification policy. Controls what evidence is required for an outcome to be marked verified_success.

mode (string, default: "none") - One of: none, require_external_id, require_result_url, require_artifacts, manual

Transport compatibility. All verification modes are supported on both webhook and worker transports. Webhook handlers attach evidence in the body of POST /v1/executions/{id}/outcome; worker handlers write evidence to $CUEAPI_OUTCOME_FILE before exit (cueapi-worker ≥ 0.3.0). See outcome states for the full compatibility matrix and the cueapi-worker README for the file schema and conflict rules.

Request

bash

curl -X POST https://api.cueapi.ai/v1/cues \
  -H "Authorization: Bearer cue_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-sync",
    "schedule": {"type": "recurring", "cron": "0 9 * * *"},
    "callback": {"url": "https://api.yourapp.com/sync"}
  }'

javascript

const response = await fetch("https://api.cueapi.ai/v1/cues", {
  method: "POST",
  headers: {
    "Authorization": "Bearer cue_sk_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "daily-sync",
    schedule: { type: "recurring", cron: "0 9 * * *" },
    callback: { url: "https://api.yourapp.com/sync" },
  }),
});
const cue = await response.json();

bash

curl -X POST https://api.cueapi.ai/v1/cues \
  -H "Authorization: Bearer cue_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "reminder",
    "schedule": {"type": "once", "at": "2026-03-15T14:00:00Z"},
    "callback": {"url": "https://api.yourapp.com/notify"}
  }'

javascript

const response = await fetch("https://api.cueapi.ai/v1/cues", {
  method: "POST",
  headers: {
    "Authorization": "Bearer cue_sk_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "reminder",
    schedule: { type: "once", at: "2026-03-15T14:00:00Z" },
    callback: { url: "https://api.yourapp.com/notify" },
  }),
});
const cue = await response.json();

bash

curl -X POST https://api.cueapi.ai/v1/cues \
  -H "Authorization: Bearer cue_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "agent-task",
    "schedule": {"type": "recurring", "cron": "0 9 * * 1-5"},
    "transport": "worker",
    "payload": {"task": "draft-linkedin", "kind": "agent_turn"}
  }'

javascript

const response = await fetch("https://api.cueapi.ai/v1/cues", {
  method: "POST",
  headers: {
    "Authorization": "Bearer cue_sk_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "agent-task",
    schedule: { type: "recurring", cron: "0 9 * * 1-5" },
    transport: "worker",
    payload: { task: "draft-linkedin", kind: "agent_turn" },
  }),
});
const cue = await response.json();

bash

curl -X POST https://api.cueapi.ai/v1/cues \
  -H "Authorization: Bearer cue_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "critical-sync",
    "schedule": {"type": "recurring", "cron": "0 */6 * * *"},
    "callback": {"url": "https://api.yourapp.com/sync"},
    "delivery": {
      "timeout_seconds": 60,
      "outcome_deadline_seconds": 600
    },
    "alerts": {
      "consecutive_failures": 2,
      "missed_window_multiplier": 3
    },
    "catch_up": "replay_all_missed",
    "verification": {
      "mode": "require_external_id"
    }
  }'

Response

json

{
  "id": "cue_a1b2c3d4e5f6",
  "name": "daily-sync",
  "status": "active",
  "next_run": "2026-03-14T09:00:00+00:00",
  "schedule": {
    "type": "recurring",
    "cron": "0 9 * * *",
    "timezone": "UTC"
  },
  "callback": {
    "url": "https://api.yourapp.com/sync",
    "method": "POST"
  },
  "transport": "webhook",
  "payload": null,
  "run_count": 0,
  "created_at": "2026-03-13T15:00:00Z"
}

json

{
  "error": {
    "code": "cue_limit_exceeded",
    "message": "You have reached your plan's cue limit (10)",
    "status": 403
  }
}

POST/v1/cues

Try it

Request Body

Enter your API key above to send requests

Previous← Test Your Key NextList Cues →