Invoke an agent (start or continue a conversation)
Send a message to an agent and run it. This is how you invoke an agent
programmatically — POST /agents only builds agents; this runs them.
The agent must belong to the authenticated user’s organization, and the
org must have an API key configured for the agent’s model provider
(Control Hub → Providers) or the run will end with streamStatus: "error".
Two response modes, selected by the X-Stream-Response header:
- Non-streaming (recommended for API/automation) — set
X-Stream-Response: false. Returns202 Acceptedimmediately with{ threadId, status: "in_progress" }and anX-Thread-IDheader, then runs the agent in the background. PollGET /getConversation?threadId={threadId}untilstreamStatusis terminal (completed/stopped/error/timeout), then read the assistant message(s) frommessages. This avoids platform request timeouts on long-running, multi-tool agents. - Streaming — omit the header (or send anything other than
false). Returns200with atext/event-stream(AI SDK UI-message stream) and anX-Thread-IDheader. Consume the SSE stream for incremental output. Most non-browser clients should prefer the non-streaming mode.
Conversation continuity: omit threadId to start a new conversation
(one is generated and returned in the X-Thread-ID header); pass an
existing threadId to continue that thread. The message body uses the
v5 parts format.
Authorizations
JWT token from Clerk authentication.
Must be from a user with org:admin role.
Headers
Set to false for the non-streaming 202 + poll pattern. Any other value (or omitted) streams an SSE response.
false "false"
Body
ID of the agent to invoke (must belong to your organization).
123
The user message in v5 format.
Show child attributes
Show child attributes
Existing conversation thread to continue. Omit to start a new conversation.
"550e8400-e29b-41d4-a716-446655440000"
Optional conversation title, trimmed and saved immediately. Creation only (omit threadId); rejected on existing threads. Must be a nonblank single line without control characters. Skips automatic title generation. If omitted, Aster generates a short title in the background using your preferred provider's Economy-tier model; failures retain the first-message fallback. Manual renames always take precedence.
1 - 120"Daily pipeline review · 2026-09-26"
IANA timezone used when rendering date/time prompt variables (e.g. "America/New_York").
Response
Streaming mode (header omitted). A Server-Sent Events stream of the
AI SDK UI-message protocol. The X-Thread-ID header carries the
thread ID.
The response is of type string.