Server-sent events and streaming APIs

Use the response-stream key to model streaming endpoints

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. To get started, reach out to 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

{ "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

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

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

then include format: sse.

chat.yml

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 to your end users.

Resumable streams

Set resumable: true on response-stream to opt an SSE endpoint into 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

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

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