Chat Stream

Stream AI responses in real-time using Server-Sent Events (SSE) for responsive chat experiences.

POST /v1/chat/stream

Chat Stream

cURL

curl --request POST \
  --url https://api.example.com/v1/chat/stream

Endpoint

POST https://api.astralform.ai/v1/chat/stream

Request

Headers

X-API-Key: af_live_xxxxxxxxxxxx
Content-Type: application/json

Body

{
  "conversation_id": "conv_abc123",
  "message": "What's the weather like today?",
  "client_tools": [
    {
      "name": "get_location",
      "description": "Get user's current GPS location",
      "input_schema": {
        "type": "object",
        "properties": {}
      }
    }
  ]
}

Field	Type	Required	Description
conversation_id	string	Yes	Conversation to send message to
message	string	Yes	User’s message content
client_tools	array	No	Available client-side tools
agent_name	string	No	Route to a specific agent (bypasses supervisor)

Response

Returns a Server-Sent Events (SSE) stream.

Event Types

content_block_delta

event: content_block_delta
data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"Hello"}}

tool_use

event: tool_use
data: {"type":"tool_use","id":"tool_123","name":"get_location","input":{}}

message_start

event: message_start
data: {"type":"message_start","message_id":"msg_123","conversation_id":"conv_abc","agent_name":"support-agent","agent_display_name":"Customer Support"}

The agent_name and agent_display_name fields are included when an agent handles the response.

agent_start / agent_end

event: agent_start
data: {"type":"agent_start","agent_name":"support-agent","agent_display_name":"Customer Support"}

event: agent_end
data: {"type":"agent_end","agent_name":"support-agent"}

Emitted when a specific agent begins and finishes handling a request. Useful for showing agent attribution in the UI.

message_stop

event: message_stop
data: {"type":"message_stop"}

error

event: error
data: {"type":"error","message":"Rate limit exceeded"}

Example

cURL

curl -N -X POST https://api.astralform.ai/v1/chat/stream \
  -H "X-API-Key: af_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_abc123",
    "message": "Hello, how are you?"
  }'

Swift

for try await event in client.streamChat(
    conversationId: "conv_abc123",
    message: "Hello, how are you?"
) {
    switch event {
    case .contentBlock(let text):
        print(text, terminator: "")
    case .toolUse(let tool):
        // Handle tool call
        break
    case .messageStop:
        print("\n[Done]")
    case .error(let error):
        print("Error: \(error)")
    }
}

Handling Tool Calls

When the AI needs to use a client tool, you’ll receive a tool_use event. Execute the tool locally and submit the result:

case .toolUse(let tool):
    let result = await executeLocalTool(tool)
    try await client.submitToolResult(
        conversationId: conversationId,
        toolCallId: tool.id,
        result: result
    )

See Tool Result for the response format.