# CueAPI - Complete Reference for AI Agents

> Coordination infrastructure for AI agent systems. Connect any step, task, job, or agent across any environment. Every handoff verified.

CueAPI is an open source coordination API that tracks both delivery and outcome. Declare a cue. Dispatch work across environments via webhook or worker pull. Your agent reports back with proof. CueAPI retries on failure, verifies outcomes against a policy, and alerts you when things break. The core engine is Apache 2.0 licensed and self-hostable.

---

## Install

```bash
pip install cueapi-sdk      # Python SDK
pip install cueapi           # CLI
pip install cueapi-worker    # Worker daemon (no public URL needed)
```

---

## Python SDK

Package: cueapi-sdk (PyPI)
Module: cueapi
Source: https://github.com/cueapi/cueapi-python

### Quick start

```python
from cueapi import CueAPI

client = CueAPI("cue_sk_your_key")

# Schedule an agent to run every morning
cue = client.cues.create(
    name="morning-brief",
    cron="0 9 * * *",
    timezone="America/Los_Angeles",
    callback="https://your-agent.com/run",
    payload={"task": "daily_brief"},
)

print(f"Scheduled. Next run: {cue.next_run}")
```

### CueAPI client

```python
from cueapi import CueAPI

client = CueAPI(
    api_key="cue_sk_...",       # required, starts with cue_sk_
    base_url="https://api.cueapi.ai",  # default
    timeout=30.0,                       # default, seconds
)
```

### Cues resource

```python
# Create recurring cue (webhook transport)
cue = client.cues.create(
    name="my-task",
    cron="0 9 * * *",              # cron expression
    timezone="UTC",                 # IANA timezone
    callback="https://your.app/run",
    callback_method="POST",         # default
    callback_headers={"X-Secret": "..."},
    payload={"task": "generate_report"},
    retry={"max_attempts": 3, "backoff_minutes": [1, 5, 15]},
    on_failure={"email": True, "webhook": None, "pause": False},
)

# Create one-time cue (worker transport)
cue = client.cues.create(
    name="one-off-task",
    at="2026-04-10T09:00:00Z",     # ISO 8601 datetime
    transport="worker",
    payload={"task": "cleanup"},
)

# List cues
cue_list = client.cues.list(limit=20, offset=0, status="active")
for cue in cue_list.cues:
    print(cue.name, cue.next_run)

# Get, update, delete
cue = client.cues.get("cue_abc123")
cue = client.cues.update("cue_abc123", name="new-name", cron="0 10 * * *")
client.cues.delete("cue_abc123")

# Pause and resume
client.cues.pause("cue_abc123")
client.cues.resume("cue_abc123")
```

### Executions resource

```python
# Report outcome
client.executions.report_outcome(
    "exec_01HX...",
    success=True,
    result="Processed 142 records",
    metadata={"duration_ms": 1240},
    external_id="batch:20260324",
    result_type="data_sync",
    summary="Synced 142 records from CRM",
)

# Auto-report via context manager
with client.executions.handle(exec_id) as ctx:
    result = do_work(ctx.payload)
    ctx.result = f"Processed {result.count} records"
# Clean exit -> auto POST success=True
# Exception  -> auto POST success=False with error message

# List and get executions
execs = client.executions.list(cue_id="cue_abc123", status="delivered", limit=20)
exec = client.executions.get("exec_01HX...")

# Heartbeat (extend claim lease for worker transport)
client.executions.heartbeat("exec_01HX...")
```

### Payload builder

```python
from cueapi import CuePayload

payload = CuePayload()
payload.task("morning-brief").kind("content_generation").instruction("Generate daily report")
client.cues.create(name="morning-brief", cron="0 9 * * *", payload=payload.build())
```

### Webhook verification

```python
from cueapi import verify_webhook

is_valid = verify_webhook(
    payload=request.body,           # raw bytes, string, or dict
    signature=request.headers["X-CueAPI-Signature"],
    secret="your_webhook_signing_secret",
    timestamp=request.headers["X-CueAPI-Timestamp"],
    tolerance=300,                  # seconds, default 300
)
```

### Exceptions

```python
from cueapi import (
    CueAPIError,              # base exception
    AuthenticationError,      # 401 - do not retry
    RateLimitError,           # 429 - wait e.retry_after seconds
    CueNotFoundError,         # 404
    CueLimitExceededError,    # 403 - plan limit reached, do not retry
    InvalidScheduleError,     # 400/422
    CueAPIServerError,        # 5xx
)

try:
    client.cues.create(...)
except RateLimitError as e:
    time.sleep(e.retry_after)  # seconds to wait
    # retry
except AuthenticationError:
    # do not retry, fix API key
    pass
except CueLimitExceededError:
    # do not retry, upgrade plan
    pass
```

---

## CLI

Package: cueapi (PyPI)
Source: https://github.com/cueapi/cueapi-cli

```bash
pip install cueapi

# Authenticate
cueapi login

# Create a cue
cueapi cues create \
  --name "my-agent" \
  --cron "0 9 * * *" \
  --url "https://your-agent.com/run"

# List cues
cueapi cues list

# Check execution history
cueapi executions list --cue cue_abc123

# Pause / resume
cueapi cues pause cue_abc123
cueapi cues resume cue_abc123
```

---

## REST API Reference

Base URL: https://api.cueapi.ai
Auth: Authorization: Bearer cue_sk_...
Content-Type: application/json

### Create a cue

POST /v1/cues

```json
{
  "name": "morning-briefing",
  "description": "optional description",
  "schedule": {
    "type": "recurring",
    "cron": "0 9 * * *",
    "at": null,
    "timezone": "America/New_York"
  },
  "transport": "webhook",
  "callback": {
    "url": "https://your.agent/run",
    "method": "POST",
    "headers": {"X-Secret": "..."}
  },
  "payload": {"task": "check_pipeline"},
  "retry": {
    "max_attempts": 3,
    "backoff_minutes": [1, 5, 15]
  },
  "on_failure": {
    "email": true,
    "webhook": null,
    "pause": false
  },
  "delivery": {
    "timeout_seconds": 30,
    "outcome_deadline_seconds": 300
  },
  "catch_up": "run_once_if_missed",
  "verification": {"mode": "none"}
}
```

Response: 201 Created with the cue object.

Key rules:
- schedule is always a nested object with type, cron or at, and timezone
- transport is top-level, not inside callback
- callback.url is required when transport is "webhook"
- For worker transport, omit callback

### List cues

GET /v1/cues?limit=20&offset=0&status=active

### Get a cue

GET /v1/cues/{cue_id}

### Update a cue

PATCH /v1/cues/{cue_id}

Send only the fields you want to change.

### Delete a cue

DELETE /v1/cues/{cue_id}

Returns 204 No Content.

### Pause a cue

PATCH /v1/cues/{cue_id}
{"status": "paused"}

### Resume a cue

PATCH /v1/cues/{cue_id}
{"status": "active"}

### Report outcome

POST /v1/executions/{execution_id}/outcome

```json
{
  "success": true,
  "result": "Processed 142 records",
  "error": null,
  "metadata": {"duration_ms": 1240},
  "external_id": "batch:20260324",
  "result_type": "data_sync",
  "summary": "Synced 142 records from CRM"
}
```

Key rules:
- success is a boolean (true or false), never a string
- result is a human-readable string
- error is a string, only set when success is false
- metadata is a free-form JSON object

### Append evidence

PATCH /v1/executions/{execution_id}/evidence

```json
{
  "external_id": "tweet:1234567890",
  "result_url": "https://twitter.com/user/status/1234567890",
  "result_type": "tweet",
  "summary": "Morning briefing posted"
}
```

### List executions

GET /v1/executions?cue_id={cue_id}&status=delivered&limit=20&offset=0

### Get an execution

GET /v1/executions/{execution_id}

### Worker transport endpoints

For agents without a public URL. The agent polls for work:

GET /v1/executions/claimable?task=my-task
POST /v1/executions/{execution_id}/claim
POST /v1/executions/{execution_id}/heartbeat
POST /v1/executions/{execution_id}/outcome

### Webhook headers

When CueAPI delivers via webhook, it sends these headers:
- X-CueAPI-Signature: v1={hmac_sha256_hex_digest}
- X-CueAPI-Timestamp: unix timestamp
- X-CueAPI-Cue-Id: the cue ID
- X-CueAPI-Execution-Id: the execution ID

Signature is HMAC-SHA256 of "{timestamp}.{json_body}" using your webhook signing secret.

---

## Transport Modes

### Webhook (default)
CueAPI POSTs a signed JSON payload to your URL. Your handler returns 200 to confirm delivery, then reports outcome separately.

### Worker
Your agent runs a local daemon that polls CueAPI for jobs. No public URL or ingress needed. Best for agents on private machines, Mac Minis, OpenClaw, Replit.

Worker flow:
1. Agent polls GET /v1/executions/claimable
2. Agent claims with POST /v1/executions/{id}/claim
3. Agent does the work
4. Agent reports outcome with POST /v1/executions/{id}/outcome

---

## Key Concepts

- Cue: A scheduled agent task with delivery confirmation, retries, and outcome tracking
- Execution: A single run of a cue. Tracks delivery status and outcome separately
- Outcome: Whether the agent confirmed success or failure. Reported by the agent, not assumed
- Delivery vs outcome: Delivery means your agent received the job. Outcome means your agent did the job. Most schedulers only track delivery. CueAPI tracks both
- Verified success: Evidence-backed proof the business action happened. The tweet ID, the email batch ID, the Stripe charge ID
- Silent failure: Your agent ran, reported success, did nothing. The accountability gap
- Catch-up policy: Controls behavior when a cue fires while the agent is offline. Options: run_once_if_missed, skip, run_all_missed

---

## Retry and Failure

- Default: 3 retry attempts with backoff at 1, 5, 15 minutes
- Configurable per cue via retry.max_attempts (1-10) and retry.backoff_minutes array
- on_failure escalation: email alert, webhook notification, auto-pause the cue
- Delivery rate: 99.97%

---

## Pricing

| Plan  | Price     | Cues | Executions/month | Rate limit |
|-------|-----------|------|------------------|------------|
| Free  | $0        | 10   | 300              | 60/min     |
| Pro   | $9.99/mo  | 100  | 5,000            | 200/min    |
| Scale | $49/mo    | 500  | 50,000           | 500/min    |

All plans include: outcome tracking, retries, email alerts, webhook signing, worker transport.
No credit card required for free tier.

Dashboard: https://dashboard.cueapi.ai/signup

---

## Agent Memory Block

Add this to your agent's system prompt or context:

```
You have access to CueAPI for scheduling tasks.
Base URL: https://api.cueapi.ai
Auth: Authorization: Bearer {CUEAPI_API_KEY}
Python SDK: pip install cueapi-sdk, then: from cueapi import CueAPI; client = CueAPI(api_key)
CLI: pip install cueapi
Docs: https://docs.cueapi.ai
Full reference: https://cueapi.ai/llms-full.txt
```

---

## Open Source

Core engine: https://github.com/cueapi/cueapi-core
License: Apache 2.0
Self-hostable with Docker Compose

Python SDK: https://github.com/cueapi/cueapi-python
CLI: https://github.com/cueapi/cueapi-cli

---

## Links

- Website: https://cueapi.ai
- Docs: https://docs.cueapi.ai
- API Docs (OpenAPI): https://api.cueapi.ai/docs
- Dashboard: https://dashboard.cueapi.ai
- Blog: https://blog.cueapi.ai
- Status: https://status.cueapi.ai
- GitHub (core): https://github.com/cueapi/cueapi-core
- GitHub (SDK): https://github.com/cueapi/cueapi-python
- GitHub (CLI): https://github.com/cueapi/cueapi-cli
- PyPI (SDK): https://pypi.org/project/cueapi-sdk/
- PyPI (CLI): https://pypi.org/project/cueapi/
- Support: support@vector.build

---

Vector Apps Inc. - Palo Alto, CA