What is CueAPI

CueAPI is a scheduling API for AI agents. Register a cue (cron or one-time), and CueAPI fires a webhook or queues an execution for your local worker at the right time. Every delivery includes HMAC-SHA256 signatures, automatic retries, and execution history.

Base URL:   https://api.cueapi.ai
Auth:       Bearer cue_sk_... (SHA-256 hashed, cached in Redis, DB fallback)
Docs:       https://docs.cueapi.ai
Dashboard:  https://cueapi.ai

Reliability

Security

Mental model

Webhook transport:
  REGISTER --> FIRE --> DELIVER --> REPORT
  POST /v1/cues    poller    webhook POST    POST /v1/executions/{id}/outcome

Worker transport:
  REGISTER --> QUEUE --> PULL+RUN --> REPORT
  POST /v1/cues    poller    GET /v1/executions/claimable    POST /v1/executions/{id}/outcome
                             POST /v1/executions/{id}/claim

Key concepts

• Cue: A registered schedule. Has status (active/paused/completed/failed), schedule (cron or once), transport (webhook or worker), payload (JSON).
• Execution: A single fire of a cue. Status: pending → delivering → success/failed. Retries go through: retrying → retry_ready → delivering.
• Outcome: What the handler reports back. Write-once. Contains success (bool), result, error, metadata.
• Transport: webhook (push to URL) or worker (pull from API).
• Delivery guarantee: at-least-once. Use execution_id as idempotency/dedup key.
• Two status layers: delivery_status (did the HTTP call succeed?) and outcome_status (did the handler logic succeed?).

Idempotency warning

CueAPI guarantees at-least-once delivery. Your handler may receive the same
execution more than once. Use the X-CueAPI-Execution-Id header as a
deduplication key. Store processed execution IDs and skip duplicates.

All endpoints (22)

Rate limits per plan

Execution payload schema (webhook delivery)

Headers:
  X-CueAPI-Signature:     v1={hmac_sha256_hex}
  X-CueAPI-Timestamp:     {unix_epoch}
  X-CueAPI-Cue-Id:        {cue_id}
  X-CueAPI-Execution-Id:  {execution_id}
  X-CueAPI-Scheduled-For: {iso8601}
  X-CueAPI-Attempt:       {int}
  Content-Type:            application/json
  Authorization:           Bearer {cue_api_key}

Body:
  The cue's payload JSON (whatever you set when creating the cue).

Webhook secret

Retrieve:  GET /v1/auth/webhook-secret
Rotate:    POST /v1/auth/webhook-secret/regenerate

Format:    whsec_ + 64 hex chars
Rotation:  Old secret instantly revoked on rotation.

Error codes

Error format:
{ "error": { "code": "string", "message": "string", "status": int } }

Retry policy

Webhook verification code

Python

import hmac, hashlib, time

def verify_webhook(payload_bytes, signature_header, timestamp_header, secret):
    # Check timestamp freshness (5 min tolerance)
    if abs(time.time() - int(timestamp_header)) > 300:
        raise ValueError("Timestamp too old")
    # Reconstruct signed content
    signed_content = f"{timestamp_header}.{payload_bytes.decode()}"
    expected = "v1=" + hmac.new(
        secret.encode(), signed_content.encode(), hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(signature_header, expected):
        raise ValueError("Invalid signature")

Node.js

const crypto = require('crypto');

function verifyWebhook(payloadBuffer, signatureHeader, timestampHeader, secret) {
  if (Math.abs(Date.now() / 1000 - parseInt(timestampHeader)) > 300) {
    throw new Error('Timestamp too old');
  }
  const signedContent = `${timestampHeader}.${payloadBuffer.toString()}`;
  const expected = 'v1=' + crypto
    .createHmac('sha256', secret)
    .update(signedContent)
    .digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected))) {
    throw new Error('Invalid signature');
  }
}

Quick start

1. Register:  POST /v1/auth/register  {"email": "you@example.com"}  → get api_key
2. Get secret: GET /v1/auth/webhook-secret  → whsec_...
3. Create cue: POST /v1/cues  with schedule + callback
4. Verify:     Check your webhook endpoint receives the signed payload

Worker pull flow

1. Heartbeat: POST /v1/worker/heartbeat  with worker_id + handlers list
2. Poll:      GET /v1/executions/claimable?task=your_task
3. Claim:     POST /v1/executions/{id}/claim  with worker_id
4. Run:       Execute handler logic
5. Report:    POST /v1/executions/{id}/outcome  with {success, result/error, metadata}

Install

pip install cueapi          # CLI
pip install cueapi-worker   # Local daemon

No SDK needed — direct HTTP API.