API Reference

CueAPI for Agents

Complete API reference for integrating CueAPI into your AI agent. Schedule tasks, confirm outcomes, get alerts when things break.

Get API KeyFull Docs

Base URL

https://api.cueapi.ai/v1

All endpoints require an Authorization: Bearer YOUR_API_KEY header unless noted otherwise.

Authentication

Bearer token on every request

curl https://api.cueapi.ai/v1/cues \
  -H "Authorization: Bearer cue_live_abc123..."

API keys start with cue_live_ (production) or cue_test_ (sandbox). Keys are SHA-256 hashed at rest — the plaintext is shown exactly once at creation.

All Endpoints

36 endpoints across 8 resource groups

MethodPathDescription
Cues
POST/v1/cuesCreate a new cue
GET/v1/cuesList all cues
GET/v1/cues/:idGet a single cue
PATCH/v1/cues/:idUpdate a cue
DELETE/v1/cues/:idDelete a cue
POST/v1/cues/:id/fireManually trigger a cue
Executions
GET/v1/executionsList executions
GET/v1/executions/:idGet a single execution
POST/v1/executions/:id/outcomeReport execution outcome
PATCH/v1/executions/:id/evidenceAttach evidence to execution
POST/v1/executions/:id/replayReplay a failed execution
POST/v1/executions/:id/heartbeatSend heartbeat for long-running task
POST/v1/executions/:id/verifyMark execution as verified
POST/v1/executions/:id/verification-pendingMark verification as pending
GET/v1/executions/claimableList claimable executions (workers)
POST/v1/executions/:id/claimClaim an execution (workers)
Auth
POST/v1/auth/registerRegister a new account
GET/v1/auth/meGet current user info
POST/v1/auth/key/regenerateRegenerate API key
POST/v1/auth/webhook-secretRotate webhook signing secret
POST/v1/auth/device-codeStart device auth flow
Billing
POST/v1/billing/checkoutCreate Stripe checkout session
POST/v1/billing/portalOpen Stripe billing portal
Workers
POST/v1/workers/heartbeatWorker heartbeat
GET/v1/workersList registered workers
Alerts
GET/v1/alertsList alerts
POST/v1/alerts/:id/acknowledgeAcknowledge alert
Support
POST/v1/supportCreate support ticket
GET/v1/support/:idGet support ticket
GET/v1/supportList support tickets
Health
GET/v1/healthHealth check
GET/v1/statusDetailed status

Create a Cue

POST /v1/cues

A cue is a scheduled task. It defines when to fire and where to deliver. CueAPI supports one-time, recurring (cron), and interval-based schedules.

Request body

POST /v1/cues
Content-Type: application/json
Authorization: Bearer cue_live_abc123...

{
  "name": "morning-analytics",
  "schedule": {
    "type": "recurring",
    "cron": "0 9 * * *",
    "timezone": "America/Los_Angeles"
  },
  "callback": {
    "url": "https://my-agent.com/webhook"
  },
  "payload": {
    "task": "pull-dashboard"
  }
}

Schedule types

TypeFieldsExample
recurringcron, timezone"0 9 * * 1-5"
one_timerun_at (ISO 8601)"2025-06-01T14:00:00Z"
intervalevery_seconds300

Response (201 Created)

{
  "id": "cue_8xk2m4n9",
  "name": "morning-analytics",
  "status": "active",
  "schedule": {
    "type": "recurring",
    "cron": "0 9 * * *",
    "timezone": "America/Los_Angeles",
    "next_fire_at": "2025-06-02T16:00:00Z"
  },
  "callback": {
    "url": "https://my-agent.com/webhook"
  },
  "payload": {
    "task": "pull-dashboard"
  },
  "retry_policy": {
    "max_attempts": 5,
    "backoff": "exponential"
  },
  "created_at": "2025-06-01T12:00:00Z"
}

Webhook Delivery Payload

What your callback URL receives

When a cue fires, CueAPI sends an HTTP POST to your callback URL with the following payload. The request includes an HMAC-SHA256 signature header for verification.

POST https://my-agent.com/webhook
Content-Type: application/json
X-Cue-Signature: sha256=9f3a...
X-Cue-Timestamp: 1717329600
X-Cue-Execution-Id: exec_abc123

{
  "event": "cue.fired",
  "cue_id": "cue_8xk2m4n9",
  "execution_id": "exec_abc123",
  "cue_name": "morning-analytics",
  "fired_at": "2025-06-02T16:00:00Z",
  "attempt": 1,
  "payload": {
    "task": "pull-dashboard"
  }
}

Verifying the signature

import hmac, hashlib

def verify(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Report Execution Outcome

POST /v1/executions/:id/outcome

After your agent processes a cue, report the outcome back to CueAPI. This closes the accountability loop — CueAPI now knows not just that a cue was delivered, but whether the task succeeded.

POST /v1/executions/exec_abc123/outcome
Content-Type: application/json
Authorization: Bearer cue_live_abc123...

{
  "status": "success",
  "summary": "Dashboard pulled. 3 anomalies flagged.",
  "metadata": {
    "rows_processed": 12400,
    "anomalies": 3,
    "duration_ms": 4200
  }
}

Outcome statuses

StatusMeaning
successTask completed successfully
failureTask failed — triggers alert
partialPartially completed — no alert
skippedIntentionally skipped this run

Worker Pull Mode

Pull instead of push — your agent polls for work

Not every agent can expose a public webhook. Worker mode lets your agent pull executions on its own schedule. Set your cue transport to worker and poll the claimable executions endpoint.

1. Create a cue with worker transport

POST /v1/cues
{
  "name": "nightly-report",
  "schedule": { "type": "recurring", "cron": "0 2 * * *" },
  "transport": "worker"
}

2. Poll for claimable executions

GET /v1/executions/claimable
Authorization: Bearer cue_live_abc123...

# Response
{
  "executions": [
    {
      "id": "exec_xyz789",
      "cue_id": "cue_8xk2m4n9",
      "cue_name": "nightly-report",
      "fired_at": "2025-06-02T09:00:00Z",
      "payload": { "task": "generate-report" }
    }
  ]
}

3. Claim and execute

POST /v1/executions/exec_xyz789/claim
Authorization: Bearer cue_live_abc123...

# Then report outcome when done
POST /v1/executions/exec_xyz789/outcome
{ "status": "success", "summary": "Report generated." }

4. Send heartbeats for long tasks

POST /v1/executions/exec_xyz789/heartbeat
Authorization: Bearer cue_live_abc123...

# Send every 30s to prevent timeout. Default timeout: 5 min.

Retry Policy

Automatic exponential backoff

If a webhook delivery fails (non-2xx response or timeout), CueAPI retries automatically using exponential backoff. You can configure retries per cue (1 to 10 attempts).

AttemptDelayCumulative
1Immediate0 s
210 s10 s
330 s40 s
42 min2 min 40 s
510 min12 min 40 s

After the final attempt, the execution is marked delivery_failed and an alert is created.

Error Codes

Standard HTTP status codes with machine-readable error types

StatusError TypeDescription
400invalid_scheduleCron expression or schedule is malformed
401invalid_api_keyMissing, expired, or invalid API key
403cue_limit_exceededPlan cue limit reached — upgrade to create more
404cue_not_foundCue ID does not exist or is not owned by you
409outcome_already_recordedOutcome was already submitted for this execution
422invalid_timezoneTimezone string is not a valid IANA timezone
429rate_limitedToo many requests — check Retry-After header

Error response format

{
  "error": {
    "type": "invalid_schedule",
    "message": "Cron expression '* * * *' is missing the day-of-week field.",
    "status": 400
  }
}

Rate Limits

Per plan, per API key

PlanRequests/minBurst
Free6010
Pro20030
Scale50050

Rate-limited responses include Retry-After and X-RateLimit-Reset headers.

Pricing

Every plan includes every feature

Free

$0

  • 10 cues
  • 300 executions/mo
  • 60 req/min

Pro

$9.99/mo

  • 100 cues
  • 5,000 executions/mo
  • 200 req/min

Scale

$49/mo

  • 500 cues
  • 50,000 executions/mo
  • 500 req/min

All plans include: webhook + worker transport, automatic retries, HMAC-signed webhooks, outcome tracking, failure alerting, execution history, and SSRF protection.

Security

Built in, not bolted on

HMAC-SHA256 Signed Webhooks

Every webhook delivery includes an X-Cue-Signature header. Verify it against your webhook secret to ensure the request is authentic and has not been tampered with.

Hashed API Keys

API keys are SHA-256 hashed at rest. The plaintext key is shown exactly once at creation. If lost, regenerate via POST /v1/auth/key/regenerate.

SSRF Protection

Callback URLs are validated before every delivery. Private IPs (127.0.0.1, 10.x, 192.168.x, etc.), link-local addresses, and non-HTTPS URLs (in production) are blocked.

Replay Protection

Webhook signatures are bound to a timestamp (X-Cue-Timestamp). Reject any delivery older than 5 minutes to prevent replay attacks.

HTTPS Only

In production, all callback URLs must use HTTPS. HTTP is allowed only in test mode for local development.

Audit Trail

Every execution is logged with delivery status, HTTP response code, outcome, and timing. Access the full history via the API or dashboard.

Quick Start

Three API calls to a running cue

1. Get your API key

Sign up at dashboard.cueapi.ai to receive your key.

2. Create a cue

curl -X POST https://api.cueapi.ai/v1/cues \
  -H "Authorization: Bearer cue_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "health-check",
    "schedule": { "type": "interval", "every_seconds": 300 },
    "callback": { "url": "https://my-agent.com/webhook" }
  }'

3. Handle the webhook and report outcome

# In your webhook handler:
POST /v1/executions/{execution_id}/outcome
{
  "status": "success",
  "summary": "All systems operational."
}

SDKs and Resources

Full Documentation

Guides, tutorials, and complete API docs

Open Source Core

Self-host the scheduling engine

Dashboard

Manage cues, view executions, and configure alerts

System Status

Real-time uptime and incident history