gsadmin/sencho
1
0
Fork 0
mirror of https://github.com/Studio-Saelix/sencho.git synced 2026-08-05 08:27:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
Anso
2026-03-31 16:13:07 -04:00
committed by GitHub
parent 574fa9a36b
commit eae83c997b
4 changed files with 2614 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+8
View File
@@ -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
+171
View File
@@ -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
+157 -43
View File
@@ -67,55 +67,169 @@
}
]
},
"api": {
"auth": {
"method": "bearer",
"name": "Authorization"
}
},
"navigation": {
"groups": [
"tabs": [
{
"group": "Getting Started",
"pages": [
"getting-started/introduction",
"getting-started/quickstart",
"getting-started/configuration",
"getting-started/sso-quickstart"
"tab": "Documentation",
"groups": [
{
"group": "Getting Started",
"pages": [
"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",
"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"
"api-reference/overview",
{
"group": "Health",
"pages": [
"GET /api/health"
]
},
{
"group": "Stacks",
"pages": [
"GET /api/stacks",
"POST /api/stacks",
"GET /api/stacks/{stackName}",
"PUT /api/stacks/{stackName}",
"DELETE /api/stacks/{stackName}",
"GET /api/stacks/{stackName}/envs",
"GET /api/stacks/{stackName}/env",
"PUT /api/stacks/{stackName}/env",
"GET /api/stacks/{stackName}/containers",
"GET /api/stacks/{stackName}/services",
"POST /api/stacks/{stackName}/deploy",
"POST /api/stacks/{stackName}/down",
"POST /api/stacks/{stackName}/start",
"POST /api/stacks/{stackName}/stop",
"POST /api/stacks/{stackName}/restart",
"POST /api/stacks/{stackName}/update",
"POST /api/stacks/{stackName}/rollback",
"GET /api/stacks/{stackName}/backup"
]
},
{
"group": "Containers",
"pages": [
"GET /api/containers",
"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"
]
}
]
}
]
docs/openapi.yaml
+2278
View File
File diff suppressed because it is too large Load Diff