Stream events (SSE)

curl --request GET \
  --url https://api.example.com/v1/events

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/events"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "1001",
  "type": "session-created",
  "sessionId": "6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d",
  "timestamp": "2026-08-08T12:00:00.000Z",
  "payload": {
    "session": {
      "id": "6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d",
      "repository": "/Users/dev/repos/midaz",
      "status": "idle",
      "clientKind": "inline",
      "createdAt": "2026-08-08T12:00:00.000Z",
      "updatedAt": "2026-08-08T12:00:00.000Z"
    }
  }
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

Stream events (SSE)

The global event firehose as server-sent events (text/event-stream). Every client consumes this one stream; events are encoded once per update and fanned out per connection, and a slow client is dropped rather than blocking the others. Filter to one session with the sessionId query parameter. Each SSE frame’s id field carries the event id; on reconnect, send it in the Last-Event-ID request header to resume from the first event after it — delivery survives client restarts. Event ids are monotonic integers and the replay buffer is time-boxed: when Last-Event-ID is older than the oldest retained event, the server starts the stream live rather than erroring; the client detects the gap between its last id and the first received id and must re-sync state through the GET endpoints before trusting the stream again. The data field of each frame is one JSON Event envelope, discriminated by its type property. A REPLAY MAY BE SERVED IN BLOCKS. When the backlog past Last-Event-ID is long, the server writes a bounded block of frames and then ends the connection rather than materialising the whole backlog onto it. The block-end is an ordinary end of connection carrying no marker: a client resumes as it would from any drop, sending the last id it received as Last-Event-ID, and continues from exactly there. Nothing is lost and nothing is duplicated — a client that already skips ids at or below the last one it delivered needs no change at all, and a replay short enough to fit in one block is served exactly as before. A CURSOR THIS STORE CANNOT HONOUR IS REFUSED, not served. A Last-Event-ID naming an event newer than anything the store holds gets 409 (NRY-0026) instead of an open stream: the replay past it is empty by definition and every live event is below it, so a 200 there is a connection that can never carry a frame — silent for the life of the process, with nothing timing out to say so. It is what a client holds after the store underneath it was replaced. A cursor that is merely OLD is unaffected and still starts the stream live. The remedy is to resume with no Last-Event-ID, never to retry the same cursor.

GET

events

Stream events (SSE)

curl --request GET \
  --url https://api.example.com/v1/events

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/events"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "1001",
  "type": "session-created",
  "sessionId": "6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d",
  "timestamp": "2026-08-08T12:00:00.000Z",
  "payload": {
    "session": {
      "id": "6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d",
      "repository": "/Users/dev/repos/midaz",
      "status": "idle",
      "clientKind": "inline",
      "createdAt": "2026-08-08T12:00:00.000Z",
      "updatedAt": "2026-08-08T12:00:00.000Z"
    }
  }
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

Headers

Last-Event-ID

string

Resume the stream from the first event after this id, as defined by the SSE specification.

Query Parameters

sessionId

string<uuid>

Only stream events for this session.

hostEvents

boolean

default:false

When sessionId narrows the stream, also deliver the events that belong to no session at all — things true of the whole machine, like an installed package's files changing under everybody (ladder-changed). Off by default, so an existing consumer's stream is unchanged. Ignored without sessionId, where the unfiltered firehose already carries them.

Response

An open server-sent event stream. Each frame's data field is one Event envelope.

The typed event envelope carried in each SSE frame's data field, discriminated by type.

string

required

Monotonic per-stream event id, usable as Last-Event-ID.

type

string

required

The event type, discriminating the payload.

Allowed value: "session-created"

timestamp

string<date-time>

required

payload

object

required

A session came into existence.

Show child attributes

Example:

{
  "session": {
    "id": "6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d",
    "repository": "/Users/dev/repos/midaz",
    "status": "idle",
    "clientKind": "inline",
    "createdAt": "2026-08-08T12:00:00.000Z",
    "updatedAt": "2026-08-08T12:00:00.000Z"
  }
}

sessionId

string<uuid>

laneId

string<uuid>

Overview

Host

Sessions

Messages

Events

Lanes

Monitors

Agents

Skills and commands

Permissions

Peers

Packages

Workflows

Schedules

Providers

Records

Error handling

Stream events (SSE)

Headers

Query Parameters

Response