# Streamable HTTP

The Streamable HTTP protocol allows you to consume AI app responses in real-time. Instead of waiting for the entire response to generate (which can take seconds for complex Generative AI tasks), this API streams the response chunks as they become available.

### When to use this API

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><i class="fa-brain-circuit">:brain-circuit:</i></td><td><strong>Generative AI experiences</strong></td><td>When your AI app generates long-form content, streaming reduces the "Time to First Byte" perception, making the app feel faster</td></tr><tr><td><i class="fa-timer">:timer:</i></td><td><strong>Real-time UIs</strong></td><td>For typing indicators or "ghost text" effects, similar to ChatGPT</td></tr></tbody></table>

### How it works

This protocol utilizes Server-Sent Events (SSE). You use the exact same endpoint and authentication as the standard REST API, but you enable the `stream` flag in your request.

#### Endpoint configuration

* *URL*: `https://apps.nlx.ai/c/{deploymentKey}/{channelKey}-{languageCode}`
* *Header*: `nlx-api-key: YOUR_KEY`
* *Content-type*: `application/json`

{% hint style="info" %}
Ensure your URL ends with the language code (e.g., `-en-US`).
{% endhint %}

#### Enabling the Stream

Add `"stream": true` to the root of your JSON body.

```bash
curl -N -X POST "https://apps.nlx.ai/c/xxxx/xxxx-en-US" \
  -H "nlx-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stream": true,
    "request": {
      "unstructured": {
        "text": "Write a short poem about coding."
      }
    }
  }'
```

### Consuming the stream

The server will respond with `Content-type: text/event-stream`. Data is sent in chunks prefixed with `data:`.

#### JavaScript client cxample

In a browser or Node.js environment, you handle the stream by reading the response reader.

```javascript
const response = await fetch('https://apps.nlx.ai/c/xxxx/xxxx-en-US', {
  method: 'POST',
  headers: {
    'nlx-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    stream: true,
    request: { unstructured: { text: "Hello" } }
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  console.log("Received chunk:", chunk);
  // Parse 'data: {...}' lines here
}
```