docs: add OpenAPI 3.1 spec and API Reference tab (#294)

Add a complete OpenAPI 3.1 specification covering ~55 public API endpoints
across 8 categories (Stacks, Containers, API Tokens, Webhooks, Nodes, Fleet,
Scheduled Tasks, Health). Wire it into Mintlify via native OpenAPI rendering
with an interactive "Try It" playground and a dedicated API Reference tab.

Includes an API overview page documenting authentication, token scopes,
node routing, error format, license tier requirements, and WebSocket endpoints.

CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+* **docs:** OpenAPI 3.1 spec covering ~55 public API endpoints across 8 categories (Stacks, Containers, API Tokens, Webhooks, Nodes, Fleet, Scheduled Tasks, Health)
+* **docs:** Interactive API Reference tab in Mintlify documentation powered by native OpenAPI rendering
+* **docs:** API overview page with authentication guide, token scopes, node routing, error format, and WebSocket examples
+
 ## [0.23.0](https://github.com/AnsoCode/Sencho/compare/v0.22.1...v0.23.0) (2026-03-31)
 
 

docs/api-reference/overview.mdx

@@ -0,0 +1,171 @@
+---
+title: API Overview
+description: Authenticate, route requests to nodes, and integrate Sencho into your CI/CD pipelines.
+---
+
+Sencho exposes a REST API for automating stack deployments, managing webhooks, monitoring fleet health, and integrating with CI/CD pipelines. Since Sencho is self-hosted, the API base URL is your own instance.
+
+## Base URL
+
+```
+https://your-sencho-instance:3000/api
+```
+
+Replace with your actual Sencho host and port. All API paths are prefixed with `/api`.
+
+## Authentication
+
+Authenticated endpoints require a **Bearer token** in the `Authorization` header. Generate API tokens from **Settings > API Tokens** in the Sencho dashboard.
+
+```bash
+curl -H "Authorization: Bearer YOUR_API_TOKEN" \
+  https://your-sencho-instance:3000/api/stacks
+```
+
+<Note>
+  API Tokens require a Sencho **Admiral** license. Community and Skipper editions do not include this feature.
+</Note>
+
+### Token scopes
+
+Every token is created with one of three permission levels:
+
+| Scope | Allowed actions |
+|-------|----------------|
+| **Read Only** | `GET` requests only — view stacks, containers, and fleet status |
+| **Deploy Only** | Everything in Read Only, plus stack operations: deploy, down, restart, stop, start, update |
+| **Full Admin** | Full stack, container, and node management — all read and write operations |
+
+Regardless of scope, all API tokens are blocked from managing other tokens, users, licenses, and SSO configuration.
+
+## Node routing
+
+Sencho manages multiple nodes (local and remote). To target a specific node, include one of:
+
+- **Header:** `x-node-id: 1`
+- **Query parameter:** `?nodeId=1`
+
+If omitted, the request targets the default node.
+
+```bash
+# Target node ID 2
+curl -H "Authorization: Bearer TOKEN" \
+  -H "x-node-id: 2" \
+  https://your-sencho-instance:3000/api/stacks
+```
+
+## Error format
+
+All error responses follow the same shape:
+
+```json
+{
+  "error": "Human-readable error message",
+  "code": "MACHINE_READABLE_CODE"
+}
+```
+
+The `code` field is present for specific error types:
+
+| Code | Meaning |
+|------|---------|
+| `PRO_REQUIRED` | Endpoint requires a Pro (Skipper or Admiral) license |
+| `ADMIRAL_REQUIRED` | Endpoint requires an Admiral license |
+| `SCOPE_DENIED` | API token scope does not allow this operation |
+
+## Rate limiting
+
+Authentication endpoints (`/api/auth/*`) are rate-limited to **5 requests per 15 minutes** in production. API token-authenticated requests are not rate-limited.
+
+## License tier requirements
+
+Some endpoints are gated by license tier:
+
+| Tier | Gated features |
+|------|---------------|
+| **Pro (Skipper+)** | Webhooks, Fleet snapshots, Stack rollback |
+| **Admiral** | API Tokens, Scheduled Tasks |
+
+Requests to gated endpoints on a lower tier return `403` with the appropriate error code.
+
+## WebSocket endpoints
+
+Sencho also provides real-time streaming via WebSocket connections. These are not part of the OpenAPI spec (OpenAPI does not support WebSocket protocols) but are documented here for completeness.
+
+### Stack log streaming
+
+Stream live logs from a stack's containers.
+
+**URL:** `wss://your-sencho-instance:3000/api/stacks/{stackName}/logs?nodeId={nodeId}`
+
+**Authentication:** Pass the token as a cookie (`sencho_token`) or Bearer token. For WebSocket connections, authentication is verified during the upgrade handshake.
+
+<CodeGroup>
+
+```javascript Node.js
+import WebSocket from "ws";
+
+const ws = new WebSocket(
+  "wss://your-sencho-instance:3000/api/stacks/my-app/logs",
+  { headers: { Cookie: "sencho_token=YOUR_JWT" } }
+);
+
+ws.on("message", (data) => {
+  console.log(data.toString());
+});
+```
+
+```bash cURL (upgrade check)
+curl -i -N \
+  -H "Connection: Upgrade" \
+  -H "Upgrade: websocket" \
+  -H "Cookie: sencho_token=YOUR_JWT" \
+  https://your-sencho-instance:3000/api/stacks/my-app/logs
+```
+
+</CodeGroup>
+
+### Container exec
+
+Open an interactive shell session inside a running container.
+
+**URL:** `wss://your-sencho-instance:3000/ws`
+
+**Authentication:** Cookie-based JWT only. API tokens with `read-only` or `deploy-only` scope are blocked.
+
+<CodeGroup>
+
+```javascript Node.js
+import WebSocket from "ws";
+
+const ws = new WebSocket("wss://your-sencho-instance:3000/ws", {
+  headers: { Cookie: "sencho_token=YOUR_JWT" },
+});
+
+ws.on("open", () => {
+  // Initiate exec session
+  ws.send(
+    JSON.stringify({
+      action: "execContainer",
+      containerId: "abc123...",
+    })
+  );
+});
+
+ws.on("message", (data) => {
+  // Terminal output
+  process.stdout.write(data.toString());
+});
+
+// Send terminal input
+ws.send(JSON.stringify({ type: "input", data: "ls -la\n" }));
+
+// Resize terminal
+ws.send(JSON.stringify({ type: "resize", cols: 120, rows: 40 }));
+```
+
+</CodeGroup>
+
+<Warning>
+  Container exec requires a Sencho **Admiral Team** license and is blocked for API tokens and node proxy tokens.
+</Warning>

docs/docs.json

@@ -67,55 +67,169 @@
       }
     ]
   },
+  "api": {
+    "auth": {
+      "method": "bearer",
+      "name": "Authorization"
+    }
+  },
   "navigation": {
-    "groups": [
+    "tabs": [
       {
-        "group": "Getting Started",
+        "tab": "Documentation",
-        "pages": [
+        "groups": [
-          "getting-started/introduction",
+          {
-          "getting-started/quickstart",
+            "group": "Getting Started",
-          "getting-started/configuration",
+            "pages": [
-          "getting-started/sso-quickstart"
+              "getting-started/introduction",
+              "getting-started/quickstart",
+              "getting-started/configuration",
+              "getting-started/sso-quickstart"
+            ]
+          },
+          {
+            "group": "Features",
+            "pages": [
+              "features/overview",
+              "features/dashboard",
+              "features/stack-management",
+              "features/editor",
+              "features/resources",
+              "features/app-store",
+              "features/global-observability",
+              "features/host-console",
+              "features/multi-node",
+              "features/fleet-view",
+              "features/alerts-notifications",
+              "features/webhooks",
+              "features/rbac",
+              "features/atomic-deployments",
+              "features/fleet-backups",
+              "features/audit-log",
+              "features/api-tokens",
+              "features/private-registries",
+              "features/scheduled-operations",
+              "features/sso",
+              "features/licensing"
+            ]
+          },
+          {
+            "group": "Reference",
+            "pages": [
+              "reference/settings",
+              "reference/security-advisories"
+            ]
+          },
+          {
+            "group": "Operations",
+            "pages": [
+              "operations/troubleshooting",
+              "operations/backup"
+            ]
+          }
         ]
       },
       {
-        "group": "Features",
+        "tab": "API Reference",
+        "openapi": "openapi.yaml",
         "pages": [
-          "features/overview",
+          "api-reference/overview",
-          "features/dashboard",
+          {
-          "features/stack-management",
+            "group": "Health",
-          "features/editor",
+            "pages": [
-          "features/resources",
+              "GET /api/health"
-          "features/app-store",
+            ]
-          "features/global-observability",
+          },
-          "features/host-console",
+          {
-          "features/multi-node",
+            "group": "Stacks",
-          "features/fleet-view",
+            "pages": [
-          "features/alerts-notifications",
+              "GET /api/stacks",
-          "features/webhooks",
+              "POST /api/stacks",
-          "features/rbac",
+              "GET /api/stacks/{stackName}",
-          "features/atomic-deployments",
+              "PUT /api/stacks/{stackName}",
-          "features/fleet-backups",
+              "DELETE /api/stacks/{stackName}",
-          "features/audit-log",
+              "GET /api/stacks/{stackName}/envs",
-          "features/api-tokens",
+              "GET /api/stacks/{stackName}/env",
-          "features/private-registries",
+              "PUT /api/stacks/{stackName}/env",
-          "features/scheduled-operations",
+              "GET /api/stacks/{stackName}/containers",
-          "features/sso",
+              "GET /api/stacks/{stackName}/services",
-          "features/licensing"
+              "POST /api/stacks/{stackName}/deploy",
-        ]
+              "POST /api/stacks/{stackName}/down",
-      },
+              "POST /api/stacks/{stackName}/start",
-      {
+              "POST /api/stacks/{stackName}/stop",
-        "group": "Reference",
+              "POST /api/stacks/{stackName}/restart",
-        "pages": [
+              "POST /api/stacks/{stackName}/update",
-          "reference/settings",
+              "POST /api/stacks/{stackName}/rollback",
-          "reference/security-advisories"
+              "GET /api/stacks/{stackName}/backup"
-        ]
+            ]
-      },
+          },
-      {
+          {
-        "group": "Operations",
+            "group": "Containers",
-        "pages": [
+            "pages": [
-          "operations/troubleshooting",
+              "GET /api/containers",
-          "operations/backup"
+              "GET /api/containers/{id}/logs",
+              "POST /api/containers/{id}/start",
+              "POST /api/containers/{id}/stop",
+              "POST /api/containers/{id}/restart"
+            ]
+          },
+          {
+            "group": "API Tokens",
+            "pages": [
+              "POST /api/api-tokens",
+              "GET /api/api-tokens",
+              "DELETE /api/api-tokens/{id}"
+            ]
+          },
+          {
+            "group": "Webhooks",
+            "pages": [
+              "GET /api/webhooks",
+              "POST /api/webhooks",
+              "PUT /api/webhooks/{id}",
+              "DELETE /api/webhooks/{id}",
+              "GET /api/webhooks/{id}/history",
+              "POST /api/webhooks/{id}/trigger"
+            ]
+          },
+          {
+            "group": "Nodes",
+            "pages": [
+              "GET /api/nodes",
+              "POST /api/nodes",
+              "GET /api/nodes/{id}",
+              "PUT /api/nodes/{id}",
+              "DELETE /api/nodes/{id}",
+              "POST /api/nodes/{id}/test"
+            ]
+          },
+          {
+            "group": "Fleet",
+            "pages": [
+              "GET /api/fleet/overview",
+              "GET /api/fleet/node/{nodeId}/stacks",
+              "GET /api/fleet/node/{nodeId}/stacks/{stackName}/containers",
+              "POST /api/fleet/snapshots",
+              "GET /api/fleet/snapshots",
+              "GET /api/fleet/snapshots/{id}",
+              "POST /api/fleet/snapshots/{id}/restore",
+              "DELETE /api/fleet/snapshots/{id}"
+            ]
+          },
+          {
+            "group": "Scheduled Tasks",
+            "pages": [
+              "GET /api/scheduled-tasks",
+              "POST /api/scheduled-tasks",
+              "GET /api/scheduled-tasks/{id}",
+              "PUT /api/scheduled-tasks/{id}",
+              "DELETE /api/scheduled-tasks/{id}",
+              "PATCH /api/scheduled-tasks/{id}/toggle",
+              "POST /api/scheduled-tasks/{id}/run",
+              "GET /api/scheduled-tasks/{id}/runs",
+              "GET /api/scheduled-tasks/{id}/runs/export"
+            ]
+          }
         ]
       }
     ]