> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# Server-sent events and streaming APIs

Fern Definition isn't recommended for new customers and Fern isn't accepting feature requests for this format. It remains supported for existing users.

#### Enterprise feature for SDKs

Using this feature in generated SDKs requires the [Enterprise plan](https://buildwithfern.com/pricing). To get started, reach out to [support@buildwithfern.com](mailto:support@buildwithfern.com).

Specifying `response-stream` on an endpoints allows you to represent endpoint responses that are streaming.

## JSON streaming

If your API returns a series of newline-delimited `JSON` chunks, under `application/json`, `application/x-ndjson`, or any other `*json` content type, as seen below

```json
{ "text": "Hi, I am a" }
{ "text": "chatbot. Do you have any"}
{ "text": "questions for me"}
```

then specify the response under `response-stream` for your endpoint, optionally with an explicit `format: json`. Only server-sent events are auto-detected from the content type, so a JSON stream requires `response-stream`.

**`chat.yml`**

```yaml title="chat.yml" {4}
service:
  base-path: /chat
  endpoints:
    stream:
      method: POST
      path: ""
      response-stream: Chat

types:
  Chat:
    properties:
      text: string
```

## Server-sent events

If your API returns server-sent-events, with the `data` and `event` keys as seen below

```json
data: { "text": "Hi, I am a" }
data: { "text": "chatbot. Do you have any"}
data: { "text": "questions for me"}
```

then include `format: sse`.

**`chat.yml`**

```yaml title="chat.yml" {9}
service:
  base-path: /chat
  endpoints:
    stream:
      method: POST
      path: ""
      response-stream:
        type: Chat
        format: sse

types:
  Chat:
    properties:
      text: string        
```

Generated SDKs expose each event's [metadata — event ID, event type, and retry interval](/learn/sdks/deep-dives/sse-metadata) to your end users.

### Resumable streams

Set `resumable: true` on `response-stream` to opt an SSE endpoint into [automatic reconnection](/learn/sdks/deep-dives/sse-metadata#automatic-reconnection). When the connection drops mid-stream, the generated SDK reconnects and resends the last event ID in the `Last-Event-ID` header, so a server that supports that header resumes where the stream left off.

**`chat.yml`**

```yaml title="chat.yml" {10}
service:
  base-path: /chat
  endpoints:
    stream:
      method: POST
      path: ""
      response-stream:
        type: Chat
        format: sse
        resumable: true

types:
  Chat:
    properties:
      text: string
```

## `Stream` parameter

It has become common practice for endpoints to have a `stream` parameter that
controls whether the response is streamed or not. Fern supports this pattern in a first
class way.

Specify the `stream-condition` alongside the ordinary response and the streaming response:

**`chat.yml`**

```yaml title="chat.yml" {7}
service:
  base-path: /chat
  endpoints:
    stream:
      method: POST
      path: ""
      stream-condition: $request.stream
      request:
        name: StreamChatRequest
        body: 
          properties: 
            stream: boolean
      response: Chat
      response-stream:
        type: ChatChunk
        format: sse

types:
  Chat:
    properties:
      text: string
      tokens: integer
  ChatChunk:
    properties:
      text: string
```

> Use the `response-stream` key to model streaming endpoints