Streaming

Overview

ChatBotKit API endpoints support both streaming and non-streaming responses, allowing you to receive data incrementally as it becomes available or wait for a complete response. Streaming is particularly useful for large datasets, long-running operations, and real-time updates.

How Streaming Works

The API determines whether to stream responses based on the Accept header you send with your request:

• Non-streaming (default): Set Accept: application/json to receive a complete JSON response once the operation finishes
• Streaming: Set Accept to a streaming format (application/jsonl, text/event-stream, or text/csv) to receive data incrementally

For non-streaming requests that take longer than expected, the API automatically falls back to streaming mode to ensure you receive data before any timeout limits.

Supported Response Formats

JSON (Non-Streaming)

Accept Header: application/json

Returns a complete JSON response when the operation finishes. This is the default format and is ideal for most API calls that return small amounts of data quickly.

Example Request:

Example Response:

JSON Lines (Streaming)

Accept Header: application/jsonl

Returns newline-delimited JSON objects, with each line representing a separate event. This format is ideal for processing large datasets or receiving real-time updates as they occur.

Example Request:

Example Response:

Server-Sent Events (Streaming)

Accept Header: text/event-stream

Returns data using the Server-Sent Events (SSE) protocol, which is designed for real-time server-to-client communication. This format works seamlessly with the browser's built-in EventSource API.

Example Request:

Example Response:

CSV (Streaming)

Accept Header: text/csv

Returns data in CSV (Comma-Separated Values) format with headers automatically generated from the first data item. This format is ideal for data exports and spreadsheet applications.

Example Request:

Example Response:

Stream Event Types

When using streaming formats (JSON Lines or Server-Sent Events), the API sends different types of events:

• item: Individual data records (e.g., each bot, conversation, or file)
• result: Final result indicating the operation is complete
• error: Error information if something goes wrong
• nop: Keep-alive signal sent during long operations to maintain the connection
• ping: Periodic heartbeat to ensure the connection stays active

When to Use Streaming

Choose streaming when you need:

• Large datasets: Listing hundreds or thousands of items
• Long-running operations: Tasks that may take more than a few seconds
• Real-time updates: Progress notifications or live event feeds
• Data exports: Downloading data for backup or analysis
• Better user experience: Show data as it arrives instead of waiting

Choose non-streaming (JSON) when you need:

• Small responses: Single records or small lists
• Fast operations: Quick lookups or updates
• Simpler code: Standard REST API patterns without streaming complexity

Best Practices

1. Handle connection interruptions: Implement retry logic for streaming connections that may be interrupted
2. Process events incrementally: Don't wait for the entire stream to complete before processing data
3. Use appropriate timeouts: Set reasonable timeout values for both streaming and non-streaming requests
4. Monitor keep-alive events: Watch for nop and ping events to detect connection health
5. Close connections properly: Always close streaming connections when done to free up resources