Payloads
Payload conventions, the task field, and static vs. live context.
Overview
CueAPI accepts any valid JSON as a cue payload. There are no enforced schema requirements. Your handler receives exactly what you send.
That said, these conventions help handlers know what to expect. They make payloads self-describing and routing predictable.
Convention fields
| Field | Required | Description |
|---|---|---|
task | Recommended | Handler name. Maps to worker config key. Used for routing. |
kind | Optional | "scheduled_task" or "agent_turn". Helps handlers differentiate. |
instruction | Optional | Human/agent-readable description of what to do. |
context_ref | Optional | Reference to where live context can be found. |
context_mode | Optional | "static" (use payload as-is) or "live" (handler should fetch fresh context). |
agent | Optional | Which agent should handle this (for agent turns). |
The task field
The task field is the most important convention. It tells the worker which handler to run:
{
"task": "draft-linkedin",
"kind": "agent_turn",
"instruction": "Draft a LinkedIn post"
}The worker matches payload.task to a handler in its YAML config:
handlers:
draft-linkedin:
cmd: "python3 linkedin_agent.py"
timeout: 300Warning
Without a task field, worker transport cues won't match any handler. The task field is required for worker routing.
Key principle
CueAPI carries intent, not data.
The payload tells the handler what to do and where to find context. The handler fetches its own context. CueAPI never resolves URLs, templates, or context references. This keeps CueAPI thin and the handler in control.
Scheduled task payload
Use kind: "scheduled_task" for routine operations:
{
"task": "sync-inventory",
"kind": "scheduled_task",
"instruction": "Sync warehouse inventory to main database",
"context_ref": "warehouse-a",
"context_mode": "live"
}Agent turn payload
Use kind: "agent_turn" when the handler should invoke an AI agent:
{
"task": "draft-linkedin",
"kind": "agent_turn",
"agent": "socrates",
"instruction": "Draft a LinkedIn post about today's top 3 AI developments",
"context_ref": "daily-trends",
"context_mode": "live"
}See the full Agent Turn Scheduling guide.
Static vs. live context
| Mode | Behavior | Use when |
|---|---|---|
static | Handler uses only what's in the payload | Payload contains everything needed |
live | Handler fetches fresh context using context_ref | Context changes between executions |
Live context keeps payloads small and ensures handlers always work with current data. The tradeoff is the handler needs access to the context source (file system, API, database).
Payload size limit
Maximum payload size is 1 MB (JSON body). Requests exceeding 2 MB total body size receive 413 Payload Too Large.
Tip
For large data, use context_mode: "live" and put a reference in context_ref rather than embedding the data in the payload.