{ "openapi": "3.1.0", "info": { "title": "MagicUptime API", "version": "0.2.0", "description": "Tenant and user scoped Bearer keys. Write includes read; membership roles further restrict access. All runtime UI operations use this API. First-run setup requires a node-local setup key. Server settings require user-scoped superadmin keys; deployment encryption keys remain local operations." }, "servers": [ { "url": "/" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/v1/auth/login": { "post": { "summary": "Sign in with email/password; returns 12-hour user token", "operationId": "post_auth_login", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Login" } } } } } }, "/api/v1/auth/logout": { "post": { "summary": "Revoke the current token", "operationId": "post_auth_logout", "parameters": [], "responses": { "204": { "description": "Success" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } } }, "/api/v1/me": { "get": { "summary": "Read current user and effective key scope", "operationId": "get_me", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } }, "patch": { "summary": "Change own password; write scope and current password required", "operationId": "patch_me", "parameters": [], "responses": { "204": { "description": "Success" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordUpdate" } } } } } }, "/api/v1/keys": { "get": { "summary": "List own keys within current tenant scope", "operationId": "get_keys", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyList" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } }, "post": { "summary": "Issue own user- or tenant-scoped key; cannot broaden current scope", "operationId": "post_keys", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyInput" } } } } } }, "/api/v1/keys/{key}": { "delete": { "summary": "Revoke an owned key; write scope required", "operationId": "delete_keys_key", "parameters": [ { "in": "path", "name": "key", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } } }, "/api/v1/tenants": { "get": { "summary": "List accessible tenants", "operationId": "get_tenants", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantList" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } }, "post": { "summary": "Create tenant; user write key required", "operationId": "post_tenants", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Name" } } } } } }, "/api/v1/tenants/{tenant}": { "get": { "summary": "Read tenant", "operationId": "get_tenants_tenant", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } }, "patch": { "summary": "Rename tenant; admin required", "operationId": "patch_tenants_tenant", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Name" } } } } }, "delete": { "summary": "Delete tenant and tenant resources; owner required", "operationId": "delete_tenants_tenant", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } } }, "/api/v1/tenants/{tenant}/members": { "get": { "summary": "List members", "operationId": "get_tenants_tenant_members", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberList" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } }, "post": { "summary": "Add member; owner required. Password required only for a new account.", "operationId": "post_tenants_tenant_members", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberInput" } } } } } }, "/api/v1/tenants/{tenant}/members/{user}": { "patch": { "summary": "Change role and team assignments; owner required", "operationId": "patch_tenants_tenant_members_user", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "user", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberUpdate" } } } } }, "delete": { "summary": "Remove member; owner required; last owner protected", "operationId": "delete_tenants_tenant_members_user", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "user", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } } }, "/api/v1/tenants/{tenant}/teams": { "get": { "summary": "List teams", "operationId": "get_tenants_tenant_teams", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamList" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } }, "post": { "summary": "Create team; admin required", "operationId": "post_tenants_tenant_teams", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Name" } } } } } }, "/api/v1/tenants/{tenant}/teams/{team}": { "get": { "summary": "Read team", "operationId": "get_tenants_tenant_teams_team", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "team", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } }, "put": { "summary": "Replace team; admin required", "operationId": "put_tenants_tenant_teams_team", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "team", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Name" } } } } }, "delete": { "summary": "Delete team; admin required", "operationId": "delete_tenants_tenant_teams_team", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "team", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } } }, "/api/v1/tenants/{tenant}/monitors": { "get": { "summary": "List monitors", "operationId": "get_tenants_tenant_monitors", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "include_results", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Adds spec_hash and grouped latest node results per monitor, plus write/admin permission flags. Eliminates per-monitor result requests for dashboards. Default response remains unchanged." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorResourceList" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } }, "post": { "summary": "Create monitor; write membership required", "operationId": "post_tenants_tenant_monitors", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorResource" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } } } } }, "/api/v1/tenants/{tenant}/monitors/{monitor}": { "get": { "summary": "Read monitor", "operationId": "get_tenants_tenant_monitors_monitor", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "monitor", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorResource" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } }, "put": { "summary": "Replace monitor; write membership required", "operationId": "put_tenants_tenant_monitors_monitor", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "monitor", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorResource" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } } } }, "delete": { "summary": "Delete monitor; write membership required", "operationId": "delete_tenants_tenant_monitors_monitor", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "monitor", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } } }, "/api/v1/tenants/{tenant}/channels": { "get": { "summary": "List channels", "operationId": "get_tenants_tenant_channels", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelResourceList" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } }, "post": { "summary": "Create channel; admin required", "operationId": "post_tenants_tenant_channels", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelResource" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" } } } } } }, "/api/v1/tenants/{tenant}/channels/{channel}": { "get": { "summary": "Read channel", "operationId": "get_tenants_tenant_channels_channel", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "channel", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelResource" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } }, "put": { "summary": "Replace channel; admin required", "operationId": "put_tenants_tenant_channels_channel", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "channel", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelResource" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" } } } } }, "delete": { "summary": "Delete channel; admin required", "operationId": "delete_tenants_tenant_channels_channel", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "channel", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } } }, "/api/v1/tenants/{tenant}/monitors/{monitor}/check": { "post": { "summary": "Run check locally; write scope required. Does not page.", "operationId": "post_tenants_tenant_monitors_monitor_check", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "monitor", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckResult" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } } }, "/api/v1/tenants/{tenant}/monitors/{monitor}/results": { "get": { "summary": "Read latest scheduled result from each node", "operationId": "get_tenants_tenant_monitors_monitor_results", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "monitor", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultResourceList" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } } }, "/api/v1/tenants/{tenant}/channels/{channel}/test": { "post": { "summary": "Queue test notification; admin required", "operationId": "post_tenants_tenant_channels_channel_test", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "channel", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Success" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } } }, "/api/v1/tenants/{tenant}/incidents": { "get": { "summary": "Read most recent incident per monitor", "operationId": "get_tenants_tenant_incidents", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentList" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } } }, "/api/v1/tenants/{tenant}/incidents/{incident}/acknowledge": { "post": { "summary": "Acknowledge incident; write membership required", "operationId": "post_tenants_tenant_incidents_incident_acknowledge", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "incident", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } } }, "/api/v1/cluster": { "get": { "summary": "Read node ID and peer last-seen timestamps", "operationId": "get_cluster", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payload" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } }, "description": "Reports local node_id, successful sync timestamps in peers, and all configured peer IDs in configured_peers. Recent timestamps indicate successful past synchronization, not a guarantee of present reachability." } }, "/api/v1/capabilities": { "get": { "summary": "Read implemented capabilities", "operationId": "get_capabilities", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payload" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } } }, "/api/v1/tenants/{tenant}/notifications": { "get": { "summary": "Read latest 200 notification outbox statuses on this node", "operationId": "get_tenant_notifications", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationList" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } } }, "/api/v1/tenants/{tenant}/notifications/{notification}/retry": { "post": { "summary": "Retry pending local notification; admin required; confirmation rules still apply", "operationId": "post_notification_retry", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "notification", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Success" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" } } } }, "/api/v1/auth/methods": { "get": { "summary": "Discover enabled sign-in methods", "operationId": "get_auth_methods", "responses": { "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" }, "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "boolean" }, "magic_link": { "type": "boolean" }, "oidc": { "type": "boolean" } }, "required": [], "additionalProperties": false } } } }, "503": { "description": "Method disabled or identity provider unavailable" } }, "parameters": [], "security": [] } }, "/api/v1/auth/magic/request": { "post": { "summary": "Request a browser-bound magic link; identical response for unknown/disabled accounts", "operationId": "post_auth_magic_request", "responses": { "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" }, "202": { "description": "Success" }, "503": { "description": "Method disabled or identity provider unavailable" } }, "parameters": [], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": [ "email" ], "additionalProperties": false } } } } } }, "/api/v1/auth/magic/redeem": { "post": { "summary": "Consume a one-use browser-bound challenge on the issuing node", "operationId": "post_auth_magic_redeem", "responses": { "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" }, "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } } }, "503": { "description": "Method disabled or identity provider unavailable" } }, "parameters": [], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ], "additionalProperties": false } } } }, "description": "Requires the HttpOnly sign-in binding cookie set by the start/request endpoint. Magic challenges expire after 10 minutes; OIDC session handoffs after 120 seconds. Successful redemption clears the cookie." } }, "/api/v1/auth/session/redeem": { "post": { "summary": "Consume a one-use browser-bound challenge on the issuing node", "operationId": "post_auth_session_redeem", "responses": { "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" }, "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } } }, "503": { "description": "Method disabled or identity provider unavailable" } }, "parameters": [], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ], "additionalProperties": false } } } }, "description": "Requires the HttpOnly sign-in binding cookie set by the start/request endpoint. Magic challenges expire after 10 minutes; OIDC session handoffs after 120 seconds. Successful redemption clears the cookie." } }, "/api/v1/auth/oidc/start": { "post": { "summary": "Begin OIDC Authorization Code with PKCE; link=true requires a recent global write login session", "operationId": "post_auth_oidc_start", "responses": { "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" }, "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "authorization_url": { "type": "string", "format": "uri" } }, "required": [ "authorization_url" ], "additionalProperties": false } } } }, "503": { "description": "Method disabled or identity provider unavailable" } }, "parameters": [], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "link": { "type": "boolean", "default": false } }, "required": [], "additionalProperties": false } } } } } }, "/api/v1/auth/oidc/callback": { "get": { "summary": "Verify OIDC response and redirect to a browser-bound one-use session handoff", "operationId": "get_auth_oidc_callback", "responses": { "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" }, "303": { "description": "Success", "headers": { "Location": { "schema": { "type": "string" }, "description": "Fixed PUBLIC_URL with #session= fragment" } } }, "503": { "description": "Method disabled or identity provider unavailable" } }, "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "error", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "iss", "in": "query", "required": false, "schema": { "type": "string" } } ], "security": [] } }, "/api/v1/auth/identities": { "get": { "summary": "List the current user\u2019s linked OIDC identities", "operationId": "get_auth_identities", "responses": { "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" }, "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "issuer": { "type": "string" }, "subject": { "type": "string" } }, "required": [], "additionalProperties": false } } } } } } }, "503": { "description": "Method disabled or identity provider unavailable" } }, "parameters": [] } }, "/api/v1/auth/identities/{identity}": { "delete": { "summary": "Unlink an identity; requires recent global write login session and another sign-in method", "operationId": "delete_auth_identities_identity", "responses": { "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid or expired credentials" }, "403": { "description": "Insufficient key scope or membership role" }, "404": { "description": "Resource not found" }, "409": { "description": "Conflict" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape or field type; framework extraction error" }, "204": { "description": "Success" }, "503": { "description": "Method disabled or identity provider unavailable" } }, "parameters": [ { "name": "identity", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/tenants/{tenant}/healthchecks": { "get": { "summary": "Read project connection and current caller permissions", "operationId": "get_tenants_tenant_healthchecks", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthchecksConfiguration" } } } }, "400": { "description": "Invalid input or provider validation rejection" }, "401": { "description": "Invalid application credentials" }, "403": { "description": "Insufficient scope/role or rejected provider project key" }, "404": { "description": "Tenant or provider resource not found" }, "422": { "description": "Invalid JSON shape" }, "429": { "description": "Provider rate limit or local four-request capacity limit" }, "502": { "description": "Provider timeout, insecure redirect, oversized/invalid response or non-read-only read_key" }, "503": { "description": "Required project key is not configured" } }, "description": "Hosted Healthchecks.io only. Project keys are encrypted and replicated in separate tenant integration records; responses never reveal those keys. Remote mutations execute once with no automatic retry. Hosted checks use Healthchecks.io notification rules." }, "put": { "summary": "Replace project credentials; tenant admin with write key required", "operationId": "put_tenants_tenant_healthchecks", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthchecksConfiguration" } } } }, "400": { "description": "Invalid input or provider validation rejection" }, "401": { "description": "Invalid application credentials" }, "403": { "description": "Insufficient scope/role or rejected provider project key" }, "404": { "description": "Tenant or provider resource not found" }, "422": { "description": "Invalid JSON shape" }, "429": { "description": "Provider rate limit or local four-request capacity limit" }, "502": { "description": "Provider timeout, insecure redirect, oversized/invalid response or non-read-only read_key" }, "503": { "description": "Required project key is not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthchecksCredentials" } } } }, "description": "Hosted Healthchecks.io only. Project keys are encrypted and replicated in separate tenant integration records; responses never reveal those keys. Remote mutations execute once with no automatic retry. Hosted checks use Healthchecks.io notification rules." }, "delete": { "summary": "Disconnect project locally; hosted checks remain active", "operationId": "delete_tenants_tenant_healthchecks", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "400": { "description": "Invalid input or provider validation rejection" }, "401": { "description": "Invalid application credentials" }, "403": { "description": "Insufficient scope/role or rejected provider project key" }, "404": { "description": "Tenant or provider resource not found" }, "422": { "description": "Invalid JSON shape" }, "429": { "description": "Provider rate limit or local four-request capacity limit" }, "502": { "description": "Provider timeout, insecure redirect, oversized/invalid response or non-read-only read_key" }, "503": { "description": "Required project key is not configured" } }, "description": "Hosted Healthchecks.io only. Project keys are encrypted and replicated in separate tenant integration records; responses never reveal those keys. Remote mutations execute once with no automatic retry. Hosted checks use Healthchecks.io notification rules." } }, "/api/v1/tenants/{tenant}/healthchecks/checks": { "get": { "summary": "List live project checks", "operationId": "get_tenants_tenant_healthchecks_checks", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/HealthchecksCheck" } } } } } } }, "400": { "description": "Invalid input or provider validation rejection" }, "401": { "description": "Invalid application credentials" }, "403": { "description": "Insufficient scope/role or rejected provider project key" }, "404": { "description": "Tenant or provider resource not found" }, "422": { "description": "Invalid JSON shape" }, "429": { "description": "Provider rate limit or local four-request capacity limit" }, "502": { "description": "Provider timeout, insecure redirect, oversized/invalid response or non-read-only read_key" }, "503": { "description": "Required project key is not configured" } }, "description": "Hosted Healthchecks.io only. Project keys are encrypted and replicated in separate tenant integration records; responses never reveal those keys. Remote mutations execute once with no automatic retry. Hosted checks use Healthchecks.io notification rules." }, "post": { "summary": "Create or upsert a hosted heartbeat check; admin write required", "operationId": "post_tenants_tenant_healthchecks_checks", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthchecksCheck" } } } }, "400": { "description": "Invalid input or provider validation rejection" }, "401": { "description": "Invalid application credentials" }, "403": { "description": "Insufficient scope/role or rejected provider project key" }, "404": { "description": "Tenant or provider resource not found" }, "422": { "description": "Invalid JSON shape" }, "429": { "description": "Provider rate limit or local four-request capacity limit" }, "502": { "description": "Provider timeout, insecure redirect, oversized/invalid response or non-read-only read_key" }, "503": { "description": "Required project key is not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthchecksInput" } } } }, "description": "Hosted Healthchecks.io only. Project keys are encrypted and replicated in separate tenant integration records; responses never reveal those keys. Remote mutations execute once with no automatic retry. Hosted checks use Healthchecks.io notification rules." } }, "/api/v1/tenants/{tenant}/healthchecks/checks/{check}": { "get": { "summary": "Read a live hosted check", "operationId": "get_tenants_tenant_healthchecks_checks_check", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "check", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Canonical lower-case UUID for admin writes; native 40-character unique_key for read-only access." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthchecksCheck" } } } }, "400": { "description": "Invalid input or provider validation rejection" }, "401": { "description": "Invalid application credentials" }, "403": { "description": "Insufficient scope/role or rejected provider project key" }, "404": { "description": "Tenant or provider resource not found" }, "422": { "description": "Invalid JSON shape" }, "429": { "description": "Provider rate limit or local four-request capacity limit" }, "502": { "description": "Provider timeout, insecure redirect, oversized/invalid response or non-read-only read_key" }, "503": { "description": "Required project key is not configured" } }, "description": "Hosted Healthchecks.io only. Project keys are encrypted and replicated in separate tenant integration records; responses never reveal those keys. Remote mutations execute once with no automatic retry. Hosted checks use Healthchecks.io notification rules." }, "patch": { "summary": "Update supplied fields on a hosted check; admin write required", "operationId": "patch_tenants_tenant_healthchecks_checks_check", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "check", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Canonical lower-case UUID for admin writes; native 40-character unique_key for read-only access." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthchecksCheck" } } } }, "400": { "description": "Invalid input or provider validation rejection" }, "401": { "description": "Invalid application credentials" }, "403": { "description": "Insufficient scope/role or rejected provider project key" }, "404": { "description": "Tenant or provider resource not found" }, "422": { "description": "Invalid JSON shape" }, "429": { "description": "Provider rate limit or local four-request capacity limit" }, "502": { "description": "Provider timeout, insecure redirect, oversized/invalid response or non-read-only read_key" }, "503": { "description": "Required project key is not configured" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthchecksInput" } } } }, "description": "Hosted Healthchecks.io only. Project keys are encrypted and replicated in separate tenant integration records; responses never reveal those keys. Remote mutations execute once with no automatic retry. Hosted checks use Healthchecks.io notification rules." }, "delete": { "summary": "Delete a hosted check; admin write required", "operationId": "delete_tenants_tenant_healthchecks_checks_check", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "check", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Canonical lower-case UUID for admin writes; native 40-character unique_key for read-only access." } ], "responses": { "204": { "description": "Success" }, "400": { "description": "Invalid input or provider validation rejection" }, "401": { "description": "Invalid application credentials" }, "403": { "description": "Insufficient scope/role or rejected provider project key" }, "404": { "description": "Tenant or provider resource not found" }, "422": { "description": "Invalid JSON shape" }, "429": { "description": "Provider rate limit or local four-request capacity limit" }, "502": { "description": "Provider timeout, insecure redirect, oversized/invalid response or non-read-only read_key" }, "503": { "description": "Required project key is not configured" } }, "description": "Hosted Healthchecks.io only. Project keys are encrypted and replicated in separate tenant integration records; responses never reveal those keys. Remote mutations execute once with no automatic retry. Hosted checks use Healthchecks.io notification rules." } }, "/api/v1/tenants/{tenant}/healthchecks/checks/{check}/pause": { "post": { "summary": "Pause hosted monitoring; admin write required", "operationId": "post_tenants_tenant_healthchecks_checks_check_pause", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "check", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Canonical lower-case UUID for admin writes; native 40-character unique_key for read-only access." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthchecksCheck" } } } }, "400": { "description": "Invalid input or provider validation rejection" }, "401": { "description": "Invalid application credentials" }, "403": { "description": "Insufficient scope/role or rejected provider project key" }, "404": { "description": "Tenant or provider resource not found" }, "422": { "description": "Invalid JSON shape" }, "429": { "description": "Provider rate limit or local four-request capacity limit" }, "502": { "description": "Provider timeout, insecure redirect, oversized/invalid response or non-read-only read_key" }, "503": { "description": "Required project key is not configured" } }, "description": "Hosted Healthchecks.io only. Project keys are encrypted and replicated in separate tenant integration records; responses never reveal those keys. Remote mutations execute once with no automatic retry. Hosted checks use Healthchecks.io notification rules." } }, "/api/v1/tenants/{tenant}/healthchecks/checks/{check}/resume": { "post": { "summary": "Resume hosted monitoring; admin write required", "operationId": "post_tenants_tenant_healthchecks_checks_check_resume", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "check", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Canonical lower-case UUID for admin writes; native 40-character unique_key for read-only access." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthchecksCheck" } } } }, "400": { "description": "Invalid input or provider validation rejection" }, "401": { "description": "Invalid application credentials" }, "403": { "description": "Insufficient scope/role or rejected provider project key" }, "404": { "description": "Tenant or provider resource not found" }, "422": { "description": "Invalid JSON shape" }, "429": { "description": "Provider rate limit or local four-request capacity limit" }, "502": { "description": "Provider timeout, insecure redirect, oversized/invalid response or non-read-only read_key" }, "503": { "description": "Required project key is not configured" } }, "description": "Hosted Healthchecks.io only. Project keys are encrypted and replicated in separate tenant integration records; responses never reveal those keys. Remote mutations execute once with no automatic retry. Hosted checks use Healthchecks.io notification rules." } }, "/api/v1/tenants/{tenant}/healthchecks/channels": { "get": { "summary": "List existing hosted alert integrations; admin write required", "operationId": "get_tenants_tenant_healthchecks_channels", "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid input or provider validation rejection" }, "401": { "description": "Invalid application credentials" }, "403": { "description": "Insufficient scope/role or rejected provider project key" }, "404": { "description": "Tenant or provider resource not found" }, "422": { "description": "Invalid JSON shape" }, "429": { "description": "Provider rate limit or local four-request capacity limit" }, "502": { "description": "Provider timeout, insecure redirect, oversized/invalid response or non-read-only read_key" }, "503": { "description": "Required project key is not configured" } }, "description": "Hosted Healthchecks.io only. Project keys are encrypted and replicated in separate tenant integration records; responses never reveal those keys. Remote mutations execute once with no automatic retry. Hosted checks use Healthchecks.io notification rules." } }, "/api/v1/admin/nodes": { "get": { "summary": "List enrolled nodes and local outstanding invitations", "operationId": "get_api_v1_admin_nodes", "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or expired credential" }, "403": { "description": "User-scoped superadmin key required, or node is not fresh" } } } }, "/api/v1/admin/nodes/{node}": { "delete": { "summary": "Remove a node and revoke its signing key", "operationId": "delete_api_v1_admin_nodes_node", "parameters": [ { "name": "node", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or expired credential" }, "403": { "description": "User-scoped superadmin key required, or node is not fresh" } } } }, "/api/v1/admin/pairing": { "post": { "summary": "Create a node-bound one-use invitation valid for ten minutes", "operationId": "post_api_v1_admin_pairing", "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or expired credential" }, "403": { "description": "User-scoped superadmin key required, or node is not fresh" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NodeInvitationInput" } } } } } }, "/api/v1/admin/pairing/{invitation}": { "delete": { "summary": "Cancel a local pairing invitation", "operationId": "delete_api_v1_admin_pairing_invitation", "parameters": [ { "name": "invitation", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or expired credential" }, "403": { "description": "User-scoped superadmin key required, or node is not fresh" } } } }, "/api/v1/admin/users": { "get": { "summary": "List users and global tiers", "operationId": "get_api_v1_admin_users", "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or expired credential" }, "403": { "description": "User-scoped superadmin key required, or node is not fresh" } } } }, "/api/v1/admin/users/{user}": { "patch": { "summary": "Set a global user tier; cannot demote own account", "operationId": "patch_api_v1_admin_users_user", "parameters": [ { "name": "user", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or expired credential" }, "403": { "description": "User-scoped superadmin key required, or node is not fresh" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserTier" } } } } } }, "/api/v1/setup": { "get": { "summary": "Check whether this unbootstrapped node can pair", "operationId": "get_api_v1_setup", "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or expired credential" }, "403": { "description": "User-scoped superadmin key required, or node is not fresh" } }, "security": [] } }, "/api/v1/setup/join": { "post": { "summary": "Join using a one-use invitation; requires fresh node and HTTPS peers", "operationId": "post_api_v1_setup_join", "parameters": [], "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Invalid or expired credential" }, "403": { "description": "User-scoped superadmin key required, or node is not fresh" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NodeInvitation" } } } } } }, "/api/v1/setup/bootstrap": { "post": { "summary": "Create the first superadmin, workspace, settings and optional integrations atomically. Requires the node-local setup key from server logs; fresh nodes only.", "operationId": "post_setup_bootstrap", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Missing/invalid setup key or bearer key" }, "403": { "description": "Already initialized, paired, or insufficient user scope/tier" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupBootstrap" } } } }, "security": [] } }, "/api/v1/admin/settings": { "get": { "summary": "Read redacted server settings; user-scoped superadmin read access required. Passwords, OIDC secret and heartbeat URL are never returned.", "operationId": "get_admin_settings", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerConfigurationView" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Missing/invalid setup key or bearer key" }, "403": { "description": "Already initialized, paired, or insufficient user scope/tier" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape" } } }, "put": { "summary": "Update runtime settings; user-scoped superadmin write access required. Shared SMTP/OIDC settings replicate; node URL and heartbeat are specific to this node.", "operationId": "put_admin_settings", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerConfigurationView" } } } }, "400": { "description": "Invalid input" }, "401": { "description": "Missing/invalid setup key or bearer key" }, "403": { "description": "Already initialized, paired, or insufficient user scope/tier" }, "429": { "description": "Rate limited" }, "422": { "description": "Invalid JSON shape" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerConfiguration" } } } } } }, "/readyz": { "get": { "summary": "Public readiness; fails during drain, resource exhaustion or stalled workers", "operationId": "get_readyz", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Invalid credentials" }, "403": { "description": "Insufficient scope or wrong update claim" }, "503": { "description": "Unsafe or unavailable operation" } }, "security": [] } }, "/metrics": { "get": { "summary": "User-scoped superadmin read key; Prometheus operational metrics", "operationId": "get_metrics", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Invalid credentials" }, "403": { "description": "Insufficient scope or wrong update claim" }, "503": { "description": "Unsafe or unavailable operation" } } } }, "/api/v1/admin/operations": { "get": { "summary": "User-scoped superadmin read key; health, workers and storage", "operationId": "get_api_v1_admin_operations", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Invalid credentials" }, "403": { "description": "Insufficient scope or wrong update claim" }, "503": { "description": "Unsafe or unavailable operation" } } } }, "/api/v1/admin/audit": { "get": { "summary": "User-scoped superadmin read key; node-local sanitized audit, 100 per page", "operationId": "get_api_v1_admin_audit", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Invalid credentials" }, "403": { "description": "Insufficient scope or wrong update claim" }, "503": { "description": "Unsafe or unavailable operation" } }, "parameters": [ { "in": "query", "name": "after", "schema": { "type": "integer", "minimum": 0 } } ] } }, "/api/v1/admin/updates": { "get": { "summary": "User-scoped superadmin read key; update state and optional signed feed check", "operationId": "get_api_v1_admin_updates", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Invalid credentials" }, "403": { "description": "Insufficient scope or wrong update claim" }, "503": { "description": "Unsafe or unavailable operation" } }, "parameters": [ { "in": "query", "name": "check", "schema": { "type": "boolean", "default": false } } ] }, "post": { "summary": "User-scoped superadmin write key; freeze configuration and authorize rollout", "operationId": "post_api_v1_admin_updates", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Invalid credentials" }, "403": { "description": "Insufficient scope or wrong update claim" }, "503": { "description": "Unsafe or unavailable operation" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseEnvelope" } } } } } }, "/api/v1/admin/updates/claim": { "post": { "summary": "Coordinator only; sequential rollout claim", "operationId": "post_api_v1_admin_updates_claim", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Invalid credentials" }, "403": { "description": "Insufficient scope or wrong update claim" }, "503": { "description": "Unsafe or unavailable operation" } }, "security": [ { "updateGrant": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStep" } } } } } }, "/api/v1/admin/updates/checkpoint": { "post": { "summary": "Coordinator only; sequential rollout checkpoint", "operationId": "post_api_v1_admin_updates_checkpoint", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Invalid credentials" }, "403": { "description": "Insufficient scope or wrong update claim" }, "503": { "description": "Unsafe or unavailable operation" } }, "security": [ { "updateGrant": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStep" } } } } } }, "/api/v1/admin/updates/rollback": { "post": { "summary": "Coordinator only; switch healthy active job to sequential rollback", "operationId": "post_api_v1_admin_updates_rollback", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Invalid credentials" }, "403": { "description": "Insufficient scope or wrong update claim" }, "503": { "description": "Unsafe or unavailable operation" } }, "security": [ { "updateGrant": [] } ] } }, "/api/v1/admin/updates/finish": { "post": { "summary": "Coordinator only; verify all planned node versions and close job", "operationId": "post_api_v1_admin_updates_finish", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Invalid credentials" }, "403": { "description": "Insufficient scope or wrong update claim" }, "503": { "description": "Unsafe or unavailable operation" } }, "security": [ { "updateGrant": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "completed", "rolled_back" ] } } } } } } } }, "/api/v1/admin/updates/local/drain": { "post": { "summary": "Root supervisor local drain; current coordinator claim required for drain/backup", "operationId": "post_api_v1_admin_updates_local_drain", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Invalid credentials" }, "403": { "description": "Insufficient scope or wrong update claim" }, "503": { "description": "Unsafe or unavailable operation" } }, "security": [ { "updateGrant": [] } ] } }, "/api/v1/admin/updates/local/resume": { "post": { "summary": "Root supervisor local resume; current coordinator claim required for drain/backup", "operationId": "post_api_v1_admin_updates_local_resume", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Invalid credentials" }, "403": { "description": "Insufficient scope or wrong update claim" }, "503": { "description": "Unsafe or unavailable operation" } }, "security": [ { "updateGrant": [] } ] } }, "/api/v1/admin/updates/local/backup": { "post": { "summary": "Root supervisor local backup; current coordinator claim required for drain/backup", "operationId": "post_api_v1_admin_updates_local_backup", "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid input" }, "401": { "description": "Invalid credentials" }, "403": { "description": "Insufficient scope or wrong update claim" }, "503": { "description": "Unsafe or unavailable operation" } }, "security": [ { "updateGrant": [] } ] } }, "/api/v1/setup/smtp/test": { "post": { "summary": "First-run setup key only: validate temporary SMTP settings and send test email without saving", "operationId": "test_setup_smtp", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmtpTest" } } } }, "responses": { "200": { "description": "SMTP server accepted message; verify inbox delivery" }, "400": { "description": "Invalid settings, SMTP/TLS/authentication failure or timeout; no settings saved" }, "401": { "description": "Invalid setup key" }, "403": { "description": "Setup complete or node already paired" }, "429": { "description": "Setup/login rate limit exceeded" } } } }, "/api/v1/tenants/{tenant}/events": { "get": { "summary": "Tenant-scoped authenticated SSE invalidations and cluster heartbeats", "operationId": "tenant_events", "parameters": [ { "in": "path", "name": "tenant", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "ready/change cause a current snapshot fetch; heartbeat carries existing cluster status; access-lost closes the stream. No replay: reconnect and reload current state.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "description": "Invalid or expired key" }, "403": { "description": "Wrong tenant scope or revoked membership" }, "429": { "description": "32 open streams per node limit" }, "503": { "description": "Stale security state or draining node" } } } }, "/api/v1/auth/session": { "put": { "summary": "Set login session duration", "description": "Only user-scoped password/magic-link/OIDC sessions. Default 30 minutes; stay_logged_in extends up to 12 hours from original sign-in. API keys cannot be extended.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "stay_logged_in" ], "properties": { "stay_logged_in": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated expiry", "content": { "application/json": { "schema": { "type": "object", "properties": { "expires_at": { "type": "integer" }, "stay_logged_in": { "type": "boolean" } } } } } }, "401": { "description": "Expired or invalid session" }, "403": { "description": "Not a user login session" } } } }, "/api/v1/tenants/{tenant}/channels/{channel}/history": { "get": { "summary": "Read replicated notification delivery attempts for a channel", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "tenant", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "channel", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "before", "in": "query", "schema": { "type": "string", "maxLength": 300 }, "description": "Opaque next_cursor from the previous page" } ], "responses": { "200": { "description": "Newest first, 50 attempts per page; 90-day retention", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "next_cursor": { "type": [ "string", "null" ] }, "retention_days": { "type": "integer" } } } } } }, "404": { "description": "Channel missing or belongs to another tenant" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "updateGrant": { "type": "apiKey", "in": "header", "name": "X-Update-Token", "description": "Root supervisor only; active job grant. Not a user API credential." } }, "schemas": { "Login": { "type": "object", "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } }, "required": [ "email", "password" ] }, "PasswordUpdate": { "type": "object", "additionalProperties": false, "properties": { "current_password": { "type": "string" }, "password": { "type": "string", "minLength": 12, "maxLength": 256 } }, "required": [ "current_password", "password" ] }, "Name": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "name" ] }, "KeyInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "tenant_id": { "type": [ "string", "null" ] }, "permission": { "type": "string", "enum": [ "read", "write" ] }, "expires_at": { "type": "integer", "description": "Unix seconds; maximum 366 days from now" } }, "required": [ "name", "permission", "expires_at" ] }, "MemberInput": { "type": "object", "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "viewer" ] }, "team_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "email", "role" ] }, "MemberUpdate": { "type": "object", "additionalProperties": false, "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "member", "viewer" ] }, "team_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "role" ] }, "Monitor": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "target": { "type": "string", "format": "uri", "maxLength": 8192 }, "kind": { "type": "string", "enum": [ "http", "tcp", "tls", "smtp", "imap", "smtp_starttls", "imap_starttls" ], "default": "http" }, "protocol": { "type": "string", "enum": [ "auto", "http1", "http2", "http3" ], "default": "auto" }, "interval_seconds": { "type": "integer", "minimum": 5, "maximum": 86400, "default": 60 }, "timeout_seconds": { "type": "integer", "minimum": 1, "maximum": 60, "default": 10 }, "status_codes": { "type": "array", "items": { "type": "integer", "minimum": 100, "maximum": 599 }, "default": [ 200 ], "minItems": 1 }, "keyword": { "type": [ "string", "null" ] }, "forbidden_keyword": { "type": [ "string", "null" ] }, "send": { "type": [ "string", "null" ] }, "expect": { "type": [ "string", "null" ] }, "tls_expiry_days": { "type": "integer", "minimum": 0, "default": 14 }, "failure_threshold": { "type": "integer", "minimum": 1, "maximum": 20, "default": 2 }, "solo_failure_threshold": { "type": "integer", "minimum": 1, "maximum": 100, "default": 5 }, "allow_private": { "type": "boolean", "default": false, "description": "Only tenant admins may create, edit or manually run private monitors" }, "enabled": { "type": "boolean", "default": true }, "channel_ids": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 200 }, "maxItems": 20, "uniqueItems": true, "default": null, "description": "null or omitted routes to all enabled workspace channels; [] disables notifications; IDs must belong to this tenant." } }, "required": [ "name", "target" ] }, "Channel": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "email", "pushover", "webhook" ] }, "recipient": { "type": "string", "maxLength": 512 }, "token": { "type": [ "string", "null" ], "description": "Pushover app token or optional webhook Bearer token; redacted. Omitting preserves only when kind and recipient are unchanged." }, "enabled": { "type": "boolean", "default": true } }, "required": [ "name", "kind", "recipient" ] }, "CheckResult": { "type": "object", "additionalProperties": false, "properties": { "node": { "type": "string" }, "checked_at": { "type": "integer" }, "success": { "type": "boolean" }, "latency_ms": { "type": "integer" }, "detail": { "type": "string" } }, "required": [ "node", "checked_at", "success", "latency_ms", "detail" ] }, "Error": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "Payload": { "type": "object", "additionalProperties": true }, "Tenant": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "integer" } }, "required": [ "id", "name", "created_at" ] }, "User": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "disabled": { "type": "boolean" } }, "required": [ "id", "email", "disabled" ] }, "Key": { "type": "object", "properties": { "id": { "type": "string" }, "user_id": { "type": "string" }, "tenant_id": { "type": [ "string", "null" ] }, "permission": { "type": "string", "enum": [ "read", "write" ] }, "name": { "type": "string" }, "created_at": { "type": "integer" }, "expires_at": { "type": "integer" } }, "required": [ "id", "user_id", "tenant_id", "permission", "name", "created_at", "expires_at" ] }, "Token": { "type": "object", "properties": { "token": { "type": "string" }, "key": { "$ref": "#/components/schemas/Key" } }, "required": [ "token", "key" ] }, "Me": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "key_scope": { "type": "object", "properties": { "tenant_id": { "type": [ "string", "null" ] }, "permission": { "type": "string" } }, "required": [ "tenant_id", "permission" ] } }, "required": [ "user", "key_scope" ] }, "Member": { "type": "object", "properties": { "user_id": { "type": "string" }, "tenant_id": { "type": "string" }, "role": { "type": "string" }, "team_ids": { "type": "array", "items": { "type": "string" } }, "email": { "type": "string" } }, "required": [ "user_id", "tenant_id", "role", "team_ids" ] }, "Team": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "tenant_id", "name" ] }, "MonitorResource": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "spec": { "$ref": "#/components/schemas/Monitor" }, "spec_hash": { "type": "string", "description": "Current monitor configuration SHA-256, only when include_results=true" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Payload" }, "description": "Latest stored results, including older configurations; compare spec_hash and checked_at before interpreting as current." } }, "required": [ "id", "tenant_id", "spec" ] }, "ChannelResource": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "spec": { "$ref": "#/components/schemas/Channel" } }, "required": [ "id", "tenant_id", "spec" ] }, "ResultResource": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "monitor_id": { "type": "string" }, "spec_hash": { "type": "string" }, "result": { "$ref": "#/components/schemas/CheckResult" }, "failure_streak": { "type": "integer" } }, "required": [ "id", "tenant_id", "monitor_id", "spec_hash", "result", "failure_streak" ] }, "Incident": { "type": "object", "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "monitor_id": { "type": "string" }, "generation": { "type": "integer" }, "state": { "type": "string", "enum": [ "open", "resolved" ] }, "opened_at": { "type": "integer" }, "resolved_at": { "type": "integer" }, "confirmed": { "type": "boolean" }, "detail": { "type": "string" }, "acknowledged_by": { "type": "string" }, "acknowledged_at": { "type": "integer" } }, "required": [ "id", "tenant_id", "monitor_id", "generation", "state", "opened_at", "confirmed", "detail" ] }, "TenantList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Tenant" } } }, "required": [ "items" ] }, "KeyList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Key" } } }, "required": [ "items" ] }, "MemberList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } } }, "required": [ "items" ] }, "TeamList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } } }, "required": [ "items" ] }, "MonitorResourceList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorResource" } }, "permissions": { "type": "object", "properties": { "write": { "type": "boolean" }, "admin": { "type": "boolean" } }, "description": "Only included with include_results=true; server rechecks authorization on every mutation." } }, "required": [ "items" ] }, "ChannelResourceList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ChannelResource" } } }, "required": [ "items" ] }, "ResultResourceList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ResultResource" } } }, "required": [ "items" ] }, "IncidentList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } } }, "required": [ "items" ] }, "NotificationList": { "type": "object", "required": [ "node_id", "items" ], "properties": { "node_id": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "channel_id", "attempts", "next_try", "completed" ], "properties": { "id": { "type": "string" }, "channel_id": { "type": "string" }, "attempts": { "type": "integer" }, "next_try": { "type": "integer" }, "completed": { "type": "boolean", "description": "Sent or cancelled as obsolete" } } } } } }, "HealthchecksInput": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "slug": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_-]*$" }, "tags": { "type": "string", "maxLength": 1000 }, "desc": { "type": "string", "maxLength": 10000 }, "schedule": { "type": "string", "maxLength": 1000 }, "tz": { "type": "string", "maxLength": 1000 }, "channels": { "type": "string", "maxLength": 1000 }, "start_kw": { "type": "string", "maxLength": 1000 }, "success_kw": { "type": "string", "maxLength": 1000 }, "failure_kw": { "type": "string", "maxLength": 1000 }, "timeout": { "type": "integer", "minimum": 60, "maximum": 31536000 }, "grace": { "type": "integer", "minimum": 60, "maximum": 31536000 }, "manual_resume": { "type": "boolean" }, "filter_subject": { "type": "boolean" }, "filter_body": { "type": "boolean" }, "filter_http_body": { "type": "boolean" }, "filter_default_fail": { "type": "boolean" }, "methods": { "type": "string", "enum": [ "", "POST" ] }, "unique": { "type": "array", "maxItems": 5, "items": { "type": "string", "enum": [ "name", "slug", "tags", "timeout", "grace" ] }, "description": "Create-only upsert matching fields; use stable slug with unique=[slug] to reconcile an ambiguous create result." } }, "additionalProperties": false, "description": "Optional fields are forwarded; schedule overrides timeout. Healthchecks validates schedule/timezone/integration semantics. PATCH only changes supplied fields." }, "HealthchecksCredentials": { "type": "object", "required": [ "read_key" ], "properties": { "read_key": { "type": "string", "minLength": 16, "maxLength": 256, "writeOnly": true, "description": "Healthchecks.io read-only project key" }, "write_key": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 256, "writeOnly": true, "description": "Optional read/write key for the same project; omitted or null removes write access" } }, "additionalProperties": false }, "HealthchecksConfiguration": { "type": "object", "properties": { "configured": { "type": "boolean" }, "write_configured": { "type": "boolean" }, "can_configure": { "type": "boolean" }, "can_manage": { "type": "boolean" }, "service_url": { "type": "string", "const": "https://healthchecks.io" } } }, "HealthchecksCheck": { "type": "object", "description": "Live Healthchecks.io representation. Admin write access with a configured write key includes UUID/ping URL. Read-only members use the native read-only key and receive unique_key without ping credentials.", "properties": { "name": { "type": "string", "maxLength": 100 }, "slug": { "type": "string", "maxLength": 100, "pattern": "^[a-z0-9_-]*$" }, "tags": { "type": "string", "maxLength": 1000 }, "desc": { "type": "string", "maxLength": 10000 }, "schedule": { "type": "string", "maxLength": 1000 }, "tz": { "type": "string", "maxLength": 1000 }, "channels": { "type": "string", "maxLength": 1000 }, "start_kw": { "type": "string", "maxLength": 1000 }, "success_kw": { "type": "string", "maxLength": 1000 }, "failure_kw": { "type": "string", "maxLength": 1000 }, "timeout": { "type": "integer", "minimum": 60, "maximum": 31536000 }, "grace": { "type": "integer", "minimum": 60, "maximum": 31536000 }, "manual_resume": { "type": "boolean" }, "filter_subject": { "type": "boolean" }, "filter_body": { "type": "boolean" }, "filter_http_body": { "type": "boolean" }, "filter_default_fail": { "type": "boolean" }, "methods": { "type": "string", "enum": [ "", "POST" ] }, "unique": { "type": "array", "maxItems": 5, "items": { "type": "string", "enum": [ "name", "slug", "tags", "timeout", "grace" ] }, "description": "Create-only upsert matching fields; use stable slug with unique=[slug] to reconcile an ambiguous create result." }, "uuid": { "type": "string", "format": "uuid" }, "unique_key": { "type": "string" }, "ping_url": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": [ "new", "up", "grace", "down", "paused" ] }, "n_pings": { "type": "integer" }, "last_ping": { "type": [ "string", "null" ] }, "next_ping": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "UserTier": { "type": "object", "additionalProperties": false, "required": [ "tier" ], "properties": { "tier": { "type": "string", "enum": [ "regular", "superadmin" ] } } }, "NodeInvitationInput": { "type": "object", "additionalProperties": false, "required": [ "node_id", "node_url", "cluster_url" ], "properties": { "node_id": { "type": "string", "maxLength": 100 }, "node_url": { "type": "string", "format": "uri", "description": "HTTPS origin of the fresh node" }, "cluster_url": { "type": "string", "format": "uri", "description": "HTTPS origin of this issuing node" } } }, "NodeInvitation": { "type": "object", "additionalProperties": false, "required": [ "origin", "node_id", "node_url", "token", "expires_at" ], "properties": { "origin": { "type": "string", "format": "uri" }, "node_id": { "type": "string" }, "node_url": { "type": "string", "format": "uri" }, "token": { "type": "string", "writeOnly": true }, "expires_at": { "type": "integer" } } }, "ServerSmtp": { "type": "object", "additionalProperties": false, "properties": { "host": { "type": "string" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "from": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "password": { "type": [ "string", "null" ], "writeOnly": true, "description": "On update, null retains the saved password only when host and username are unchanged." } }, "required": [ "host", "port", "from" ] }, "ServerOidc": { "type": "object", "additionalProperties": false, "properties": { "issuer": { "type": "string", "format": "uri" }, "client_id": { "type": "string" }, "client_secret": { "type": [ "string", "null" ], "writeOnly": true, "description": "On update, null retains the saved secret only when issuer and client ID are unchanged; empty string clears it." } }, "required": [ "issuer", "client_id" ] }, "ServerShared": { "type": "object", "additionalProperties": false, "properties": { "magic_links_enabled": { "type": "boolean" }, "smtp": { "anyOf": [ { "$ref": "#/components/schemas/ServerSmtp" }, { "type": "null" } ] }, "oidc": { "anyOf": [ { "$ref": "#/components/schemas/ServerOidc" }, { "type": "null" } ] } }, "required": [] }, "ServerNode": { "type": "object", "additionalProperties": false, "properties": { "public_url": { "type": [ "string", "null" ], "description": "HTTPS origin; must match the enrolled node URL after pairing." }, "healthchecks_ping_url": { "type": [ "string", "null" ], "writeOnly": true, "description": "Healthchecks.io HTTPS check URL for this node. On update null preserves it; empty string removes it." } }, "required": [] }, "ServerConfiguration": { "type": "object", "additionalProperties": false, "properties": { "shared": { "$ref": "#/components/schemas/ServerShared" }, "node": { "$ref": "#/components/schemas/ServerNode" } }, "required": [ "shared", "node" ] }, "SetupBootstrap": { "type": "object", "additionalProperties": false, "properties": { "setup_key": { "type": "string", "writeOnly": true }, "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 12, "maxLength": 256, "writeOnly": true }, "workspace": { "type": "string", "minLength": 1, "maxLength": 100 }, "configuration": { "$ref": "#/components/schemas/ServerConfiguration" }, "notifications": { "type": "array", "maxItems": 2, "items": { "$ref": "#/components/schemas/Channel" } }, "healthchecks": { "anyOf": [ { "$ref": "#/components/schemas/HealthchecksCredentials" }, { "type": "null" } ] } }, "required": [ "setup_key", "email", "password", "workspace", "configuration" ] }, "ServerConfigurationView": { "type": "object", "additionalProperties": false, "properties": { "shared": { "$ref": "#/components/schemas/ServerSharedView" }, "node": { "$ref": "#/components/schemas/ServerNodeView" } }, "required": [ "shared", "node" ] }, "ServerSharedView": { "type": "object", "additionalProperties": false, "properties": { "magic_links_enabled": { "type": "boolean" }, "smtp": { "anyOf": [ { "$ref": "#/components/schemas/ServerSmtpView" }, { "type": "null" } ] }, "oidc": { "anyOf": [ { "$ref": "#/components/schemas/ServerOidcView" }, { "type": "null" } ] } }, "required": [] }, "ServerSmtpView": { "type": "object", "additionalProperties": false, "properties": { "host": { "type": "string" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "from": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "password": { "type": "null", "description": "Redacted; never returned." }, "password_configured": { "type": "boolean", "readOnly": true } }, "required": [ "host", "port", "from" ] }, "ServerOidcView": { "type": "object", "additionalProperties": false, "properties": { "issuer": { "type": "string", "format": "uri" }, "client_id": { "type": "string" }, "client_secret": { "type": "null", "description": "Redacted; never returned." }, "secret_configured": { "type": "boolean", "readOnly": true } }, "required": [ "issuer", "client_id" ] }, "ServerNodeView": { "type": "object", "additionalProperties": false, "properties": { "public_url": { "type": [ "string", "null" ], "description": "HTTPS origin; must match the enrolled node URL after pairing." }, "healthchecks_ping_url": { "type": "null", "description": "Redacted; never returned." }, "healthchecks_ping_configured": { "type": "boolean", "readOnly": true } }, "required": [] }, "ReleaseEnvelope": { "type": "object", "additionalProperties": false, "required": [ "manifest", "signature" ], "properties": { "manifest": { "type": "string", "maxLength": 16000, "description": "Base64 exact signed manifest JSON" }, "signature": { "type": "string", "maxLength": 100, "description": "Base64 Ed25519 signature" } } }, "UpdateStep": { "type": "object", "additionalProperties": false, "required": [ "node_id" ], "properties": { "node_id": { "type": "string" } } }, "SmtpTest": { "type": "object", "additionalProperties": false, "required": [ "setup_key", "smtp", "recipient" ], "properties": { "setup_key": { "type": "string", "maxLength": 200 }, "recipient": { "type": "string", "format": "email" }, "smtp": { "type": "object", "additionalProperties": false, "required": [ "host", "port", "from" ], "properties": { "host": { "type": "string", "maxLength": 253 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "from": { "type": "string", "description": "Mailbox sender, optionally with display name" }, "username": { "type": [ "string", "null" ], "maxLength": 256 }, "password": { "type": [ "string", "null" ], "maxLength": 4096, "writeOnly": true } } } } } } } }