> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flextell.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Stream a chat response

> The response is `text/event-stream`. Each frame contains an `event` field (event type)
and a `data` field (JSON payload). Consume `text_delta` events to progressively render
the assistant's reply.

**Event types in order:**
- `stream_start` — stream opened, includes model and provider info
- `step_start` — reasoning step started
- `text_start` — text block started
- `text_delta` — incremental text chunk; read `data.delta` for the token
- `text_complete` — text block finished
- `step_finish` — reasoning step finished
- `stream_end` — stream closed, includes `finish_reason` and token `usage`

**Example stream:**
```
event: stream_start
data: {"id":"evt_01KPTDR1BWRTJRY7W56MBCGF0R","timestamp":1776855811,"model":"grok-4-1-fast-non-reasoning","provider":"xai","metadata":null}

event: step_start
data: {"id":"evt_01KPTDR1BWRTJRY7W56MBCGF0S","timestamp":1776855811}

event: text_start
data: {"id":"evt_01KPTDR1BWRTJRY7W56MBCGF0T","timestamp":1776855811,"message_id":"evt_abc"}

event: text_delta
data: {"id":"evt_01KPTDR1BXRXHBK6DFSZ3W32H6","timestamp":1776855811,"delta":"Hello","message_id":"evt_def"}

event: text_delta
data: {"id":"evt_01KPTDR1CXK80DJ647VEF68ATW","timestamp":1776855811,"delta":"!","message_id":"evt_klm"}

event: text_complete
data: {"id":"evt_01KPTDR1Q0Z330AKTGKFXYRQ7G","timestamp":1776855811,"message_id":"evt_xyz"}

event: step_finish
data: {"id":"evt_01KPTDR1Q1PD7FG8F9DS2GCAVJ","timestamp":1776855811}

event: stream_end
data: {"id":"evt_01KPTDR1Q1PD7FG8F9DS2GCAVK","timestamp":1776855811,"finish_reason":"Stop","usage":{"prompt_tokens":12,"completion_tokens":8,"cache_write_input_tokens":null,"cache_read_input_tokens":null,"thought_tokens":null},"citations":null}
```

> **Note:** Use `curl -N` (no-buffer) or an EventSource client to see tokens arrive in real time.
> Postman buffers SSE until the connection closes.



## OpenAPI

````yaml https://dev.flextell.ai/docs/api.json post /v1/flexy-chat/stream
openapi: 3.1.0
info:
  title: Flextell API
  version: 0.0.1
  description: '## Flextell API'
servers:
  - url: https://dev.flextell.ai/api
security:
  - oauth2: []
  - bearer: []
paths:
  /v1/flexy-chat/stream:
    post:
      tags:
        - FlexyChat
        - FlexyChatApi
      summary: Stream a chat response
      description: >-
        The response is `text/event-stream`. Each frame contains an `event`
        field (event type)

        and a `data` field (JSON payload). Consume `text_delta` events to
        progressively render

        the assistant's reply.


        **Event types in order:**

        - `stream_start` — stream opened, includes model and provider info

        - `step_start` — reasoning step started

        - `text_start` — text block started

        - `text_delta` — incremental text chunk; read `data.delta` for the token

        - `text_complete` — text block finished

        - `step_finish` — reasoning step finished

        - `stream_end` — stream closed, includes `finish_reason` and token
        `usage`


        **Example stream:**

        ```

        event: stream_start

        data:
        {"id":"evt_01KPTDR1BWRTJRY7W56MBCGF0R","timestamp":1776855811,"model":"grok-4-1-fast-non-reasoning","provider":"xai","metadata":null}


        event: step_start

        data: {"id":"evt_01KPTDR1BWRTJRY7W56MBCGF0S","timestamp":1776855811}


        event: text_start

        data:
        {"id":"evt_01KPTDR1BWRTJRY7W56MBCGF0T","timestamp":1776855811,"message_id":"evt_abc"}


        event: text_delta

        data:
        {"id":"evt_01KPTDR1BXRXHBK6DFSZ3W32H6","timestamp":1776855811,"delta":"Hello","message_id":"evt_def"}


        event: text_delta

        data:
        {"id":"evt_01KPTDR1CXK80DJ647VEF68ATW","timestamp":1776855811,"delta":"!","message_id":"evt_klm"}


        event: text_complete

        data:
        {"id":"evt_01KPTDR1Q0Z330AKTGKFXYRQ7G","timestamp":1776855811,"message_id":"evt_xyz"}


        event: step_finish

        data: {"id":"evt_01KPTDR1Q1PD7FG8F9DS2GCAVJ","timestamp":1776855811}


        event: stream_end

        data:
        {"id":"evt_01KPTDR1Q1PD7FG8F9DS2GCAVK","timestamp":1776855811,"finish_reason":"Stop","usage":{"prompt_tokens":12,"completion_tokens":8,"cache_write_input_tokens":null,"cache_read_input_tokens":null,"thought_tokens":null},"citations":null}

        ```


        > **Note:** Use `curl -N` (no-buffer) or an EventSource client to see
        tokens arrive in real time.

        > Postman buffers SSE until the connection closes.
      operationId: flexy-chat.stream
      parameters:
        - name: X-Tenant
          in: header
          required: true
          description: >-
            Tenant identifier. Send the Tenant ID in the `X-Tenant` header to
            scope API requests to a specific tenant.
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                  description: The user prompt to send to the assistant.
                  minLength: 1
                  maxLength: 2000
                history:
                  type:
                    - array
                    - 'null'
                  description: Prior conversation messages (max 20 turns).
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                        description: The role of the message author (user or assistant).
                        enum:
                          - user
                          - assistant
                      content:
                        type: string
                        description: The text content of the message.
                    required:
                      - role
                      - content
                  maxItems: 20
              required:
                - prompt
      responses:
        '200':
          description: >-
            SSE stream. Listen for `text_delta` events and read `data.delta` to
            render the response progressively.
          content:
            text/event-stream:
              schema:
                type: object
                properties:
                  event:
                    type: string
                    enum:
                      - stream_start
                      - step_start
                      - text_start
                      - text_delta
                      - text_complete
                      - step_finish
                      - stream_end
                    example: text_delta
                  data:
                    type: object
                required:
                  - event
                  - data
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://dev.flextell.ai/oauth/authorize
          tokenUrl: https://dev.flextell.ai/oauth/token
          scopes:
            '*': all
    bearer:
      type: http
      scheme: bearer

````