curl --request POST \
  --url https://asteragents.com/api/chat \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentId": 123,
  "message": {
    "role": "user",
    "parts": [
      {
        "type": "text",
        "text": "Summarize the latest quarterly report."
      }
    ]
  }
}
'

"<string>"

Conversations API

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. Returns 202 Accepted immediately with { threadId, status: "in_progress" } and an X-Thread-ID header, then runs the agent in the background. Poll GET /getConversation?threadId={threadId} until streamStatus is terminal (completed / stopped / error / timeout), then read the assistant message(s) from messages. This avoids platform request timeouts on long-running, multi-tool agents.
Streaming — omit the header (or send anything other than false). Returns 200 with a text/event-stream (AI SDK UI-message stream) and an X-Thread-ID header. 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.

POST

chat

curl --request POST \
  --url https://asteragents.com/api/chat \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentId": 123,
  "message": {
    "role": "user",
    "parts": [
      {
        "type": "text",
        "text": "Summarize the latest quarterly report."
      }
    ]
  }
}
'

"<string>"

Authorizations

Authorization

string

header

required

JWT token from Clerk authentication.

Must be from a user with org:admin role.

Headers

X-Stream-Response

enum<string>

Set to false for the non-streaming 202 + poll pattern. Any other value (or omitted) streams an SSE response.

Available options:

false

Example:

"false"

Body

application/json

agentId

integer

required

ID of the agent to invoke (must belong to your organization).

Example:

123

message

object

required

The user message in v5 format.

Show child attributes

threadId

string<uuid> | null

Existing conversation thread to continue. Omit to start a new conversation.

Example:

"550e8400-e29b-41d4-a716-446655440000"

timezone

string | null

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.

Delete a bundled file Get a conversation with messages