{ "openapi": "3.1.0", "info": { "title": "Farsight API", "version": "1", "description": "Uptime monitoring: monitors, incidents, alerts, status page. Everything the dashboard does. The full contract with every field is in docs/api.md; agents should start at /llms.txt." }, "servers": [ { "url": "/" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer fs_<48 hex>" }, "session": { "type": "apiKey", "in": "cookie", "name": "farsight_session" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "field": { "type": "string" }, "fields": { "type": "array" } } } } } } }, "paths": { "/api/health": { "get": { "summary": "Liveness: {ok, version, uptime_s}", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "public" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/status": { "get": { "summary": "The public status page as JSON", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "public" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/status": { "get": { "summary": "The public status page (HTML); ?range=24h|7d|30d|90d|12mo", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "public" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/status/history": { "get": { "summary": "Every incident of a public service, three months a page; ?before=YYYY-MM", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "public" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/status/{slug}": { "get": { "summary": "One public service's page (HTML); ?range=", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "public" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/hb/{token}": { "get": { "summary": "Heartbeat ping (also POST and HEAD)", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "public" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "summary": "Heartbeat ping with an optional text body", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "public" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/hb/{token}/fail": { "post": { "summary": "Report a failure for a heartbeat monitor", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "public" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/auth/state": { "get": { "summary": "Setup needed, signed in, sign-in methods, Turnstile site key", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "auth" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/auth/passkey/options": { "post": { "summary": "Passkey sign-in options (needs a Turnstile token)", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "auth" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/auth/passkey/verify": { "post": { "summary": "Finish passkey sign-in; sets the session cookie", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "auth" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/auth/password": { "post": { "summary": "Email and password; returns a ticket for the code step", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "auth" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/auth/code": { "post": { "summary": "Authenticator or recovery code for a ticket; sets the cookie", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "auth" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/auth/forgot": { "post": { "summary": "Email a password reset link (always answers ok)", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "auth" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/auth/reset": { "post": { "summary": "Set a new password with the link token and a second factor", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "auth" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/auth/logout": { "post": { "summary": "End this session", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "auth" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/auth/setup/{token}": { "get": { "summary": "First-run setup link state, with the authenticator QR", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "auth" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "summary": "Finish first-run setup; returns recovery codes", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "auth" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/auth/enroll/{token}": { "get": { "summary": "Break-glass enrolment link state", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "auth" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/api/v1/auth/enroll/{token}/options": { "post": { "summary": "Passkey creation options for an enrolment link", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "auth" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/auth/enroll/{token}/verify": { "post": { "summary": "Add the passkey and sign in", "description": "No sign-in. See docs/api.md for the bodies and answers.", "tags": [ "auth" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/auth/step-up/passkey/options": { "post": { "summary": "Step-up with a passkey: options", "description": "Dashboard session (cookie) only. See docs/api.md for the bodies and answers.", "tags": [ "auth" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/auth/step-up/passkey/verify": { "post": { "summary": "Step-up with a passkey: verify", "description": "Dashboard session (cookie) only. See docs/api.md for the bodies and answers.", "tags": [ "auth" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/auth/step-up/password": { "post": { "summary": "Step-up with password and code", "description": "Dashboard session (cookie) only. See docs/api.md for the bodies and answers.", "tags": [ "auth" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/me": { "get": { "summary": "The signed-in owner", "description": "Dashboard session (cookie) only. See docs/api.md for the bodies and answers.", "tags": [ "me" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ] } }, "/api/v1/me/sessions": { "get": { "summary": "Sessions", "description": "Dashboard session (cookie) only. See docs/api.md for the bodies and answers.", "tags": [ "me" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ] } }, "/api/v1/me/sessions/{id}": { "delete": { "summary": "Revoke a session (step-up)", "description": "Dashboard session (cookie) only. See docs/api.md for the bodies and answers.", "tags": [ "me" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "session": [] } ] } }, "/api/v1/me/sessions/revoke-others": { "post": { "summary": "Revoke every other session (step-up)", "description": "Dashboard session (cookie) only. See docs/api.md for the bodies and answers.", "tags": [ "me" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/me/passkeys": { "get": { "summary": "Passkeys", "description": "Dashboard session (cookie) only. See docs/api.md for the bodies and answers.", "tags": [ "me" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ] } }, "/api/v1/me/passkeys/options": { "post": { "summary": "Add a passkey: creation options (step-up)", "description": "Dashboard session (cookie) only. See docs/api.md for the bodies and answers.", "tags": [ "me" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/me/passkeys/verify": { "post": { "summary": "Add a passkey: verify (step-up)", "description": "Dashboard session (cookie) only. See docs/api.md for the bodies and answers.", "tags": [ "me" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/me/passkeys/{id}": { "patch": { "summary": "Rename a passkey", "description": "Dashboard session (cookie) only. See docs/api.md for the bodies and answers.", "tags": [ "me" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } }, "delete": { "summary": "Remove a passkey (step-up)", "description": "Dashboard session (cookie) only. See docs/api.md for the bodies and answers.", "tags": [ "me" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "session": [] } ] } }, "/api/v1/me/password": { "post": { "summary": "Change the password and sign out every other session (step-up)", "description": "Dashboard session (cookie) only. See docs/api.md for the bodies and answers.", "tags": [ "me" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/me/totp/options": { "post": { "summary": "New authenticator secret to confirm (step-up)", "description": "Dashboard session (cookie) only. See docs/api.md for the bodies and answers.", "tags": [ "me" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/me/totp": { "post": { "summary": "Confirm the new authenticator and sign out every other session (step-up)", "description": "Dashboard session (cookie) only. See docs/api.md for the bodies and answers.", "tags": [ "me" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/me/recovery-codes": { "post": { "summary": "New recovery codes (step-up)", "description": "Dashboard session (cookie) only. See docs/api.md for the bodies and answers.", "tags": [ "me" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/me/blocked-ips": { "get": { "summary": "Blocked addresses", "description": "Scope admin (or a session). See docs/api.md for the bodies and answers.", "tags": [ "me" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/api/v1/me/blocked-ips/{ip}": { "delete": { "summary": "Unblock an address (step-up)", "description": "Dashboard session (cookie) only. See docs/api.md for the bodies and answers.", "tags": [ "me" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "ip", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "session": [] } ] } }, "/api/v1/keys": { "get": { "summary": "API keys", "description": "Scope admin (or a session). See docs/api.md for the bodies and answers.", "tags": [ "keys" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ] }, "post": { "summary": "Make an API key (owner session, step-up); the key is shown once", "description": "Dashboard session (cookie) only. See docs/api.md for the bodies and answers.", "tags": [ "keys" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/keys/{id}": { "delete": { "summary": "Revoke an API key (owner session, step-up)", "description": "Dashboard session (cookie) only. See docs/api.md for the bodies and answers.", "tags": [ "keys" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "session": [] } ] } }, "/api/v1/summary": { "get": { "summary": "Counts, open incidents, blind state, groups, tags", "description": "Scope read (or a session). See docs/api.md for the bodies and answers.", "tags": [ "summary" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/api/v1/monitors": { "get": { "summary": "Monitors with state and stats; filters status, group, tag, kind, q", "description": "Scope read (or a session). See docs/api.md for the bodies and answers.", "tags": [ "monitors" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ] }, "post": { "summary": "Create a monitor", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "monitors" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/monitors/test": { "post": { "summary": "Run one check of an unsaved monitor", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "monitors" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/monitors/bulk": { "post": { "summary": "Create or update many by slug (dry_run supported)", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "monitors" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/monitors/by-slug/{slug}": { "put": { "summary": "Create or replace by slug (idempotent)", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "monitors" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/monitors/{id}": { "get": { "summary": "One monitor (id or slug:)", "description": "Scope read (or a session). See docs/api.md for the bodies and answers.", "tags": [ "monitors" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] }, { "session": [] } ] }, "patch": { "summary": "Change fields of a monitor", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "monitors" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } }, "delete": { "summary": "Delete a monitor and its history (step-up)", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "monitors" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/api/v1/monitors/{id}/pause": { "post": { "summary": "Pause", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "monitors" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/monitors/{id}/resume": { "post": { "summary": "Resume", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "monitors" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/monitors/{id}/mute": { "post": { "summary": "Mute alerts until a time or for minutes", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "monitors" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/monitors/{id}/unmute": { "post": { "summary": "Unmute", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "monitors" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/monitors/{id}/check": { "post": { "summary": "Check now", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "monitors" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/monitors/{id}/heartbeat-token": { "post": { "summary": "New secret ping URL for a heartbeat monitor", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "monitors" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/monitors/{id}/checks": { "get": { "summary": "Recent checks, newest first", "description": "Scope read (or a session). See docs/api.md for the bodies and answers.", "tags": [ "monitors" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/api/v1/checks": { "get": { "summary": "Every monitor's checks, newest first, each with its monitor_id: before, limit, outcome, monitor_id", "description": "Scope read (or a session). See docs/api.md for the bodies and answers.", "tags": [ "checks" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/api/v1/monitors/{id}/series": { "get": { "summary": "Chart data: range 1h, 24h, 7d, 30d, 90d", "description": "Scope read (or a session). See docs/api.md for the bodies and answers.", "tags": [ "monitors" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/api/v1/monitors/{id}/uptime": { "get": { "summary": "Daily uptime and downtime", "description": "Scope read (or a session). See docs/api.md for the bodies and answers.", "tags": [ "monitors" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/api/v1/incidents": { "get": { "summary": "Incidents: state open|closed|all, monitor_id", "description": "Scope read (or a session). See docs/api.md for the bodies and answers.", "tags": [ "incidents" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/api/v1/incidents/{id}": { "get": { "summary": "One incident with its failed checks", "description": "Scope read (or a session). See docs/api.md for the bodies and answers.", "tags": [ "incidents" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] }, { "session": [] } ] }, "patch": { "summary": "Acknowledge or add a note", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "incidents" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/channels": { "get": { "summary": "Alert channels (secrets masked)", "description": "Scope read (or a session). See docs/api.md for the bodies and answers.", "tags": [ "channels" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ] }, "post": { "summary": "Add an alert channel (step-up)", "description": "Scope admin (or a session). See docs/api.md for the bodies and answers.", "tags": [ "channels" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/channels/{id}": { "get": { "summary": "One channel", "description": "Scope read (or a session). See docs/api.md for the bodies and answers.", "tags": [ "channels" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] }, { "session": [] } ] }, "patch": { "summary": "Change name, enabled, events; config needs admin and step-up", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "channels" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } }, "delete": { "summary": "Remove a channel (step-up)", "description": "Scope admin (or a session). See docs/api.md for the bodies and answers.", "tags": [ "channels" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/api/v1/channels/{id}/test": { "post": { "summary": "Send a test message now", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "channels" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/deliveries": { "get": { "summary": "Delivery log", "description": "Scope read (or a session). See docs/api.md for the bodies and answers.", "tags": [ "deliveries" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/api/v1/status-page": { "get": { "summary": "Status page settings and which monitors are public", "description": "Scope read (or a session). See docs/api.md for the bodies and answers.", "tags": [ "status-page" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ] }, "put": { "summary": "Change the status page and monitors' public settings", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "status-page" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/status-page/logo": { "put": { "summary": "Upload the status page's logo (raw PNG, JPEG, WebP or SVG body, 256 KB at most)", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "status-page" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } }, "delete": { "summary": "Remove the status page's logo (and the icon made from it)", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "status-page" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/api/v1/status-page/icon": { "put": { "summary": "Upload the home-screen icon made from the logo (raw square PNG, 180 to 1024 px, 256 KB at most; ?logo= names the logo it was drawn from; 409 without a logo or when it changed)", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "status-page" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/status-page/preview": { "post": { "summary": "Render the status page from a draft (settings and monitor changes) without saving it", "description": "Scope write (or a session). See docs/api.md for the bodies and answers.", "tags": [ "status-page" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/settings": { "get": { "summary": "Settings", "description": "Scope read (or a session). See docs/api.md for the bodies and answers.", "tags": [ "settings" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ] }, "patch": { "summary": "Change settings (step-up; private targets: owner session only)", "description": "Scope admin (or a session). See docs/api.md for the bodies and answers.", "tags": [ "settings" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/export": { "get": { "summary": "Export monitors, channels and the status page (step-up)", "description": "Scope admin (or a session). See docs/api.md for the bodies and answers.", "tags": [ "export" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/api/v1/import": { "post": { "summary": "Import an export (dry_run defaults to true)", "description": "Scope admin (or a session). See docs/api.md for the bodies and answers.", "tags": [ "import" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/api/v1/diagnostics": { "get": { "summary": "Version, memory, rates, database, writer, canary, outbox, email, egress", "description": "Scope read (or a session). See docs/api.md for the bodies and answers.", "tags": [ "diagnostics" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/api/v1/events": { "get": { "summary": "The timeline", "description": "Scope read (or a session). See docs/api.md for the bodies and answers.", "tags": [ "events" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ] } }, "/api/v1/stream": { "get": { "summary": "Server-Sent Events: hello, check, state, incident, blind, monitors", "description": "Scope read (or a session). See docs/api.md for the bodies and answers.", "tags": [ "stream" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ] } } } }