# Read retained changes or subscribe

Source: https://docs.wabe.sh/api-reference/operations/readnotifications/

`GET https://api.wabe.sh/v1/disks/{disk}/notifications`

## Authorization

Project API key from the Wabe Dashboard or actor runtime access token for the disk URL supplied by the broker.

## Parameters

- `disk` (path, string, required) — Project disk name, or the disk ID in the actor runtime disk URL.

- `sequence` (query, string) — Exclusive opaque cursor; omitted or 0 starts at retained history.

- `sse` (query, boolean) — Replay retained history then stream live events with SSE.

- `include_value` (query, boolean) — Deliver previously captured content in value_chunk records.

- `entity` (query, string) — Restrict the resource kind. Allowed values: `file`, `kv`.

- `file_prefix` (query, string) — Literal normalized file-path prefix; cannot combine with namespace.

- `namespace` (query, string) — Exact KV namespace; cannot combine with file_prefix.

- `limit` (query, integer) — Finite GET only; maximum examined events, including filtered events.

- `Last-Event-ID` (header, string) — Cursor fallback when sequence query is omitted.

- `branch` (query, string)

## Responses

### 200

A finite NDJSON page or a live SSE stream, selected by sse.

`application/x-ndjson`

Example

```text
{"type":"checkpoint","sequence":"62ad930b-c1e6-4d3c-ab84-8bf74a025d2f:42"}
```

Schema

```json
{
  "type": "string"
}
```

Stream record schema

```json
{
  "type": "object",
  "required": [
    "type"
  ],
  "properties": {
    "type": {
      "enum": [
        "notification",
        "checkpoint",
        "value_chunk",
        "value_end",
        "error"
      ]
    }
  },
  "description": "NDJSON or SSE data record. Notifications carry sequence, entity (file/kv), operation, revision, resource metadata and value_available. Checkpoints carry sequence. Value chunks carry sequence, offset and base64; value_end carries sequence and bytes. Errors carry code and message."
}
```

`text/event-stream`

Example

```text
event: checkpoint
id: 62ad930b-c1e6-4d3c-ab84-8bf74a025d2f:42
data: {"type":"checkpoint","sequence":"62ad930b-c1e6-4d3c-ab84-8bf74a025d2f:42"}

```

Schema

```json
{
  "type": "string",
  "description": "When sse=true; Last-Event-ID can supply the resume cursor."
}
```

Stream record schema

```json
{
  "type": "object",
  "required": [
    "type"
  ],
  "properties": {
    "type": {
      "enum": [
        "notification",
        "checkpoint",
        "value_chunk",
        "value_end",
        "error"
      ]
    }
  },
  "description": "NDJSON or SSE data record. Notifications carry sequence, entity (file/kv), operation, revision, resource metadata and value_available. Checkpoints carry sequence. Value chunks carry sequence, offset and base64; value_end carries sequence and bytes. Errors carry code and message."
}
```

### 400

Invalid settings, cursor or filters.

`application/json`

Schema

```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "code",
    "message"
  ],
  "additionalProperties": false
}
```

`text/plain`

Schema

```json
{
  "type": "string"
}
```

### 401

Missing, invalid or revoked project API key, or an invalid runtime access token.

`application/json`

Schema

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "error",
    "message"
  ]
}
```

### 403

Actor runtime token does not authorize this disk or instance generation.

`application/json`

Schema

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "error",
    "message"
  ]
}
```

### 404

sequence_expired: reload state and resume from sequence=0.

`application/json`

Schema

```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "code",
    "message"
  ],
  "additionalProperties": false
}
```

`text/plain`

Schema

```json
{
  "type": "string"
}
```

### 409

Conflict, nonempty destination or referenced object.

`text/plain`

Schema

```json
{
  "type": "string"
}
```

### 500

Storage failure.

`application/json`

Schema

```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "code",
    "message"
  ],
  "additionalProperties": false
}
```

`text/plain`

Schema

```json
{
  "type": "string"
}
```

### 503

Notifications closed.

`application/json`

Schema

```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "code",
    "message"
  ],
  "additionalProperties": false
}
```