FCE-3915: Add the Insights API reference

.gitmodules

@@ -25,3 +25,6 @@
 [submodule "packages/react-native-worklets"]
 	path = packages/react-native-worklets
 	url = https://github.com/fishjam-cloud/fishjam-react-native-worklets.git
+[submodule "api/cloud"]
+	path = api/cloud
+	url = git@github.com:fishjam-cloud/cloud.git

docs/api/reference.md

@@ -6,7 +6,7 @@ type: reference
 
 Describes APIs for direct interaction with Fishjam.
 
-Fishjam publishes documentation for the Sandbox API, Fishjam Server APIs, and the Composition API.
+Fishjam publishes documentation for the Sandbox API, Fishjam Server APIs, the Composition API, and the Insights API.
 
 ## Sandbox API
 
@@ -63,3 +63,13 @@ Next, you can should subscribe to notifications by sending `SubscribeRequest` ev
 Calls authenticate with your Management Token, from the [**Fishjam developer panel**](https://fishjam.io/app).
 
 Request bodies are snake_case and closed: a field the endpoint does not define is rejected with `422` rather than ignored, so a misspelling fails loudly instead of silently doing nothing.
+
+## Insights
+
+The Insights API lets you browse your rooms that ended in the last 60 days. For each room, you can see which peers had issues, such as high round trip time or packet loss, and how their bitrate, packet loss, and round trip time changed over time. All requests go to `https://fishjam.io/api/v1`.
+
+### REST API
+
+[Insights REST API Reference](/api/insights)
+
+Calls authenticate with your Management Token, from the [**Fishjam developer panel**](https://fishjam.io/app).

docs/how-to/backend/production-deployment.mdx

@@ -411,6 +411,10 @@ For scaling considerations:
 - [Understanding Fishjam Architecture](../../explanation/architecture)
 - [Security best practices](../../explanation/security-tokens)
 
+For investigating call quality after a room ends:
+
+- [Insights API](../../api/reference#insights)
+
 For specific backend frameworks:
 
 - [FastAPI example](../../how-to/backend/fastapi-example)

docs/how-to/client/debug-logging.mdx

@@ -71,3 +71,7 @@ When enabled, you may see logs similar to:
 [FISHJAM] Couldn't get camera permission: NotAllowedError ...
 [FISHJAM] ICE connection: disconnected
 ```
+
+## See also
+
+Debug logs show what happens on one client while it runs. To check the network quality of every peer after a room ends, use the [Insights API](../../api/reference#insights).

docusaurus.config.ts

@@ -284,6 +284,7 @@ const config: Config = {
           items: [
             { to: "/api/rest", label: "Server API" },
             { to: "/api/compositions", label: "Composition API" },
+            { to: "/api/insights", label: "Insights API" },
           ],
         },
         {
@@ -410,6 +411,11 @@ const config: Config = {
               slug: "composition",
               url: "/docs/api/composition-openapi.json",
             },
+            {
+              title: "Insights API",
+              slug: "insights",
+              url: "/docs/api/insights-openapi.json",
+            },
           ],
           hideSearch: true,
           persistAuth: true,
@@ -438,6 +444,24 @@ const config: Config = {
         },
       } as ScalarOptions,
     ],
+    [
+      "@scalar/docusaurus",
+      {
+        id: "insights-api",
+        label: "Insights API",
+        route: "/api/insights",
+        showNavLink: false,
+        configuration: {
+          url: "/docs/api/insights-openapi.json",
+          hideSearch: true,
+          persistAuth: true,
+          defaultOpenFirstTag: false,
+          authentication: {
+            preferredSecurityScheme: "ManagementTokenAuth",
+          },
+        },
+      } as ScalarOptions,
+    ],
     [
       "docusaurus-plugin-typedoc",
       {

scripts/update_api.sh

@@ -55,6 +55,11 @@ copy_composition_openapi() {
     echo "Copied openapi.json of composition to the assets directory."
 }
 
+copy_insights_openapi() {
+    cp backend/openapi/insights.json "$ASSETS_DIRECTORY/insights-openapi.json"
+    echo "Copied insights.json of cloud to the assets directory."
+}
+
 PROTO_FILES="server_notifications agent_notifications notifications/shared"
 copy_protos() {
     for file in $PROTO_FILES; do
@@ -74,4 +79,7 @@ copy_protos
 checkout_submodule_branch composition $COMPOSITION_BRANCH
 copy_composition_openapi
 
+checkout_submodule cloud
+copy_insights_openapi
+
 echo $'\nSubmodule update and copy complete.'