Add websockets stream api docs

docs/networks/node-ops/access-onchain-data/access-nodes/accessing-data/websockets-stream-api.md

@@ -0,0 +1,184 @@
+---
+title: Flow Websockets Stream API Specification
+sidebar_label: Websockets Stream API
+sidebar_position: 3
+---
+
+# Flow Websockets Stream API Documentation
+
+## Overview
+
+The Stream API allows clients to receive real-time updates from the Flow blockchain via WebSocket connections. It
+supports subscribing to various topics, such as blocks, events, and transactions, enabling low-latency access to live
+data.
+
+### Important Information
+
+- **Endpoint**: The WebSocket server is available at:
+  ```
+  wss://api.flow.com/ws
+  ```
+- **Limits**:
+    - Each connection supports up to 50 concurrent subscriptions. Exceeding this limit will result in an error.
+    - TODO: list all limits here
+- **Supported Topics**:
+    - `blocks`
+    - `block_headers`
+    - `block_digests`
+    - `events`
+    - `transaction_statuses`
+    - `account_statuses`
+- **Notes**: Always handle errors gracefully and close unused subscriptions to maintain efficient connections.
+
+---
+
+## Setting Up a WebSocket Connection
+
+Use any WebSocket client library to connect to the endpoint. Below is an example using JavaScript:
+
+```javascript
+const ws = new WebSocket('wss://api.flow.com/ws');
+
+ws.onopen = () => {
+    console.log('Connected to WebSocket server');
+};
+
+ws.onclose = () => {
+    console.log('Disconnected from WebSocket server');
+};
+
+ws.onerror = (error) => {
+    console.error('WebSocket error:', error);
+};
+```
+
+---
+
+## Subscribing to Topics
+
+To receive data from a specific topic, send a subscription request in JSON format over the WebSocket connection.
+
+### Request Format
+
+```json
+{
+  "subscription_id": "some-uuid-42",
+  "action": "subscribe",
+  "topic": "blocks",
+  "parameters": {
+    "start_block_height": "123456789"
+  }
+}
+```
+
+- **`subscription_id`**: A unique identifier for the subscription (UUID string). If omitted, the server generates one.
+- **`action`**: The action to perform. Supported actions include: `subscribe`, `unsubscribe`, `list_subscriptions`.
+- **`topic`**: The topic to subscribe to. See the supported topics in the Overview.
+- **`parameters`**: Additional parameters for subscriptions, such as `start_block_height`, `start_block_id`, and others.
+
+### Response Format
+
+```json
+{
+  "subscription_id": "some-uuid-42",
+  "error": null
+}
+```
+
+---
+
+## Unsubscribing from Topics
+
+To stop receiving data from a specific topic, send an unsubscribe request.
+
+### Request Format
+
+```json
+{
+  "subscription_id": "some-uuid-42",
+  "action": "unsubscribe"
+}
+```
+
+### Response Format
+
+```json
+{
+  "subscription_id": "some-uuid-42",
+  "error": null
+}
+```
+
+---
+
+## Listing Active Subscriptions
+
+You can retrieve a list of all active subscriptions for the current WebSocket connection.
+
+### Request Format
+
+```json
+{
+  "action": "list_subscriptions"
+}
+```
+
+### Response Format
+
+```json
+{
+  "subscriptions": [
+    {
+      "subscription_id": "uuid-1",
+      "topic": "blocks",
+      "parameters": {
+        "start_block_height": "123456789"
+      }
+    },
+    {
+      "subscription_id": "uuid-2",
+      "topic": "events",
+      "parameters": {}
+    }
+  ]
+}
+```
+
+---
+
+## Errors Example
+
+If a request is invalid or cannot be processed, the server responds with an error message.
+
+### OK Response
+
+```json
+{
+  "subscription_id": "some-uuid-42",
+  "payload": {
+    "id": "0x1234...",
+    "height:": "123456789",
+    "timestamp": "2025-01-02T10:00:00Z"
+  },
+  "error": null
+}
+```
+
+### Error Response
+
+```json
+{
+  "subscription_id": "some-uuid-42",
+  "payload": null,
+  "error": {
+    "code": 500,
+    "message": "Access Node failed"
+  }
+}
+```
+
+### Common Error Codes
+
+- **400**: Invalid message format or parameters
+- **404**: Subscription not found
+- **500**: Internal server error

docs/networks/node-ops/access-onchain-data/access-nodes/websockets-stream-api/list-subscriptions-message.md

@@ -0,0 +1,48 @@
+---
+title: List subscriptions request message format
+sidebar_label: Listing subscriptions
+sidebar_position: 3
+---
+
+# List subscriptions message format
+
+List subscriptions requests must be sent as JSON in text frames, one request per frame.
+This message is different from other as it doesn't require you to provide subscription ID.
+Thus, the response for this message is different too.
+
+### Example of request
+
+```json
+{
+  "action": "list_subscriptions"
+}
+```
+
+### Example of response
+
+```json
+{
+  "subscriptions": [
+    {
+      "subscription_id": "uuid-1",
+      "topic": "blocks",
+      "parameters": {
+        "start_block_height": "123456789"
+      }
+    },
+    {
+      "subscription_id": "uuid-2",
+      "topic": "events",
+      "parameters": {}
+    }
+  ]
+}
+```
+
+If there are no active subscriptions, `subscriptions` array will be empty.
+
+### Request fields
+
+| Name     | Type   | Mandatory | Description                                                                             |
+|----------|--------|-----------|-----------------------------------------------------------------------------------------|
+| `action` | STRING | YES       | Action to perform. Must be `list_subscriptions` to initiate a list subscription request |

docs/networks/node-ops/access-onchain-data/access-nodes/websockets-stream-api/subscribe-message.md

@@ -0,0 +1,81 @@
+---
+title: Subscribe request message format
+sidebar_label: Subscribing to topic
+sidebar_position: 1
+---
+
+# Subscribe request format
+
+Subscribe requests must be sent as JSON in text frames, one request per frame.
+
+### Example of subscribe request
+
+```json
+{
+  "subscription_id": "fa770c92-a1f1-4375-9a7b-e13d9aac0786",
+  "action": "subscribe",
+  "topic": "block_digests",
+  "parameters": {
+    "start_block_height": "99,416,580"
+  }
+}
+```
+
+### Example of successful response
+
+```json
+{
+  "subscription_id": "fa770c92-a1f1-4375-9a7b-e13d9aac0786"
+}
+```
+
+### Example of failed response
+
+```json
+{
+  "subscription_id": "fa770c92-a1f1-4375-9a7b-e13d9aac0786",
+  "error": {
+    "code": 400,
+    "message": "invalid message"
+  }
+}
+```
+
+### Example of messages provided by subscription (if successful)
+
+```json
+{
+  "subscription_id": "fa770c92-a1f1-4375-9a7b-e13d9aac0786",
+  "payload": {
+    "id": "0x1234...",
+    "height:": "123456789",
+    "timestamp": "2025-01-02T10:00:00Z"
+  }
+}
+```
+
+### Example of messages provided by subscription (if error)
+
+```json
+{
+  "subscription_id": "fa770c92-a1f1-4375-9a7b-e13d9aac0786",
+  "error": {
+    "code": 500,
+    "message": "access node is not responsible"
+  }
+}
+```
+
+### Request fields:
+
+| Name              | Type   | Mandatory | Description                                                                                |
+|-------------------|--------|-----------|--------------------------------------------------------------------------------------------|
+| `subscription_id` | UUID   | NO        | Optional unique identifier for the subscription. Server will generate one if omitted       |
+| `action`          | STRING | YES       | Action to perform. Must be `subscribe` to initiate a subscription                          |
+| `topic`           | STRING | YES       | The topic to subscribe to, such as `blocks`, `block_digests`, etc.                         |
+| `parameters`      | STRING | NO        | Additional parameters for the subscription, such as `start_block_id`, `start_block_height` |
+
+You can use `subscription_id` as a client-generated identifier to track responses asynchronously.
+If you don't provide `subscription_id`, the server will generate one and include it in the response.
+
+The order of params is not significant.

docs/networks/node-ops/access-onchain-data/access-nodes/websockets-stream-api/unsubscribe-message.md

@@ -0,0 +1,44 @@
+---
+title: Unsubscribe request message format
+sidebar_label: Unsubscribing from topic
+sidebar_position: 2
+---
+
+# Unsubscribe message format
+
+Unsubscribe requests must be sent as JSON in text frames, one request per frame.
+
+### Example of unsubscribe request
+
+```json
+{
+  "subscription_id": "fa770c92-a1f1-4375-9a7b-e13d9aac0786",
+  "action": "unsubscribe"
+}
+```
+
+### Example of successful response
+
+```json
+{
+  "subscription_id": "fa770c92-a1f1-4375-9a7b-e13d9aac0786"
+}
+```
+
+### Example of error response
+
+```json
+{
+  "error": {
+    "code": 404,
+    "message": "subscription not found"
+  }
+}
+```
+
+### Request fields
+
+| Name              | Type   | Mandatory | Description                                                           |
+|-------------------|--------|-----------|-----------------------------------------------------------------------|
+| `subscription_id` | UUID   | YES       | Unique identifier of the subscription                                 |
+| `action`          | STRING | YES       | Action to perform. Must be `unsubscribe` to initiate a unsubscription |