{ "openapi": "3.1.0", "info": { "title": "Perstat API", "description": "The Perstat API gives you programmatic access to your monitoring data: monitors, incidents, status pages, maintenance windows, webhooks, and organization management.\n\n## Authentication\nAuthenticate with an API key as a Bearer token: create keys in your organization settings (API keys section) in the Perstat app, then send Authorization: Bearer pst_... with every request. Keys are organization-bound, carry explicit scopes (resource:read or resource:write, where write implies read), and can be narrowed to specific projects or monitors. During the beta, API keys are accepted on a growing subset of endpoints, marked with x-api-key-enabled; the remaining documented endpoints currently require a browser session and gain key support incrementally.\n\n## Stability\nThis specification is versioned independently of the product. Additive changes (new fields, new endpoints) can happen at any time; removals or renames only after a deprecation window of at least 90 days, announced in the changelog on perstat.io. Operation ids are stable identifiers.\n\n## Webhooks\nOutbound webhook deliveries are signed with an HMAC-SHA256 signature in the x-perstat-signature header (sha256= over the raw body) so you can verify authenticity with your signing secret.", "version": "1.0.0-beta.1", "contact": { "name": "Perstat", "url": "https://perstat.io" } }, "servers": [ { "url": "https://api.perstat.io", "description": "Production" } ], "tags": [ { "name": "Organizations", "description": "Manage organizations, their members, roles, and invitations." }, { "name": "Projects", "description": "Group monitors into projects within an organization." }, { "name": "Monitors", "description": "Create and manage monitors and read their measurement time series." }, { "name": "Incidents", "description": "The incident lifecycle from detection or manual creation through acknowledgement, notes, resolution, downtime curation, post-mortems, and status page publishing." }, { "name": "Maintenance", "description": "Schedule and manage maintenance windows that suppress alerts and announce planned work on status pages." }, { "name": "On-Call", "description": "Read the on-call configuration, manage the rotation roster, and resolve who is currently on duty." }, { "name": "Status Pages", "description": "Configure status pages, their monitors, viewer accounts, access protection, and custom domains." }, { "name": "Public Status", "description": "Unauthenticated endpoints of published status pages: page data, badges, feeds, logos, and email subscriptions." }, { "name": "Webhooks", "description": "Manage outbound webhook and Slack notification targets, their signing secrets, and delivery tests." }, { "name": "Agents", "description": "List and decommission host agents enrolled in an organization." } ], "paths": { "/me/organizations": { "get": { "tags": [ "Organizations" ], "operationId": "my_organizations", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationDto" } } } } }, "401": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List organizations you belong to", "description": "Returns all organizations the caller is a member of, each with its id, name, and URL slug. This is the natural discovery entry point for any integration." } }, "/monitors/{monitor_id}": { "get": { "tags": [ "Monitors" ], "operationId": "get_monitor", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorDto" } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get monitor detail", "description": "Returns full detail for a single monitor: type, configuration, check interval, probe regions, enabled state, the confirmation policy, and the latest quorum-confirmed status and severity. Requires membership in the monitor's organization. Accepts API keys.", "x-api-key-enabled": true }, "delete": { "tags": [ "Monitors" ], "operationId": "delete_monitor", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a monitor", "description": "Permanently deletes a monitor together with its dependent data. This is irreversible. Requires a project management role in the owning organization; the deletion is recorded in the activity log." }, "patch": { "tags": [ "Monitors" ], "summary": "Update a monitor", "operationId": "update_monitor", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMonitorRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorDto" } } } }, "400": { "description": "A field was refused; `error` and `field` name it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorWriteError" } } } }, "401": { "description": "" }, "402": { "description": "Plan limit: `too_many_regions`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorWriteError" } } } }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "description": "Partially updates a monitor: name, type, configuration, check interval, probe regions, confirmation policy, and the enabled flag. Omitted fields keep their current value; the same interval and region rules as on create apply. Disabling a monitor also resolves its open incidents, since a paused monitor can no longer confirm recovery. Refused fields return 400 (402 for too many regions) with the same error body as on create. Requires project management rights." } }, "/monitors/{monitor_id}/checks": { "get": { "tags": [ "Monitors" ], "operationId": "list_monitor_checks", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorCheckDto" } } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List recent checks of a monitor", "description": "Returns the most recent individual probe checks of a monitor, newest first, including probe region, outcome, latency, and error detail for failed checks. Individual checks are raw observations; the confirmed monitor status follows the quorum policy and is exposed on the monitor resource itself. Accepts API keys.", "x-api-key-enabled": true } }, "/monitors/{monitor_id}/incidents": { "get": { "tags": [ "Incidents" ], "operationId": "list_monitor_incidents", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IncidentDto" } } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List incidents for a monitor", "description": "Returns up to 50 recent incidents for the monitor, including status, severity, cause, affected regions, and start and resolution timestamps. Requires membership in the monitor's organization. Accepts API keys.", "x-api-key-enabled": true } }, "/monitors/{monitor_id}/series": { "get": { "tags": [ "Monitors" ], "operationId": "monitor_series", "parameters": [ { "name": "monitor_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "range", "in": "query", "description": "3h|6h|12h|1d|7d|14d|30d|90d (default 1d)", "required": false, "schema": { "type": "string" } }, { "name": "series_metric", "in": "query", "description": "Dienst-Monitore: cpu|mem (Default cpu); Kurve = Prozess-CPU-% bzw. RAM-MB", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorSeriesDto" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get monitor time series", "description": "Returns the aggregated measurement time series of a monitor over a selectable range from 3 hours to 90 days (default 1 day), bucketed server-side into evenly spaced points with uptime, latency, and check statistics. For agent-based threshold monitors the curve carries the measured metric instead of latency, and service monitors accept a series_metric parameter to choose between process CPU and memory. Accepts API keys.", "x-api-key-enabled": true } }, "/organizations": { "post": { "tags": [ "Organizations" ], "operationId": "create_organization", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDto" } } } }, "400": { "description": "" }, "401": { "description": "" }, "409": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create an organization", "description": "Creates a new organization owned by the caller; the URL slug is derived from the name. Returns 409 when the per-user organization limit is reached or the slug is already taken." } }, "/organizations/{org_id}": { "patch": { "tags": [ "Organizations" ], "operationId": "rename_organization", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationDto" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Rename an organization", "description": "Renames the organization. Note that the URL slug is re-derived from the new name as a side effect and deduplicated across the owner's organizations. Requires organization management rights." } }, "/organizations/{org_id}/agents": { "get": { "tags": [ "Agents" ], "summary": "List agents of an organization", "operationId": "list_agents", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AgentDto" } } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "description": "Returns the enrolled agents of the organization with hostname, platform, version, online state, last heartbeat, and the latest CPU, memory, and disk readings. Each entry also carries monitor_count, the number of active monitors bound to that agent, which are the monitors that would be archived if the agent were removed. Any organization member may read the list." } }, "/organizations/{org_id}/agents/{agent_id}": { "delete": { "tags": [ "Agents" ], "summary": "Remove an agent from an organization", "operationId": "delete_agent", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "agent_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "description": "Removes the agent from the organization and immediately invalidates its per-agent token, so it stops reporting and disappears from listings. Monitors bound to this agent are archived in the same transaction: they stop checking, release their slot in the plan limit, and any open incidents on them are resolved, so no further alerts are sent for a host that no longer exists. Archived monitors keep their history, availability figures, and exclusion windows, and can be restored (they come back paused). Uninstalling the agent software from the host is a separate step. Requires project management rights." } }, "/organizations/{org_id}/incidents": { "get": { "tags": [ "Incidents" ], "operationId": "list_org_incidents", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IncidentDto" } } } } }, "401": { "description": "" }, "403": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List open incidents of an organization", "description": "Returns the currently open incidents of the organization, including status, severity, cause, affected regions, and start time. Monitor references are public monitor ids; manual incidents created without a monitor have no monitor reference. Requires membership. Accepts API keys.", "x-api-key-enabled": true }, "post": { "tags": [ "Incidents" ], "operationId": "create_incident", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIncidentRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentDetailDto" } } } }, "400": { "description": "" }, "401": { "description": "" }, "402": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a manual incident", "description": "Creates a manual incident, optionally linked to a monitor of the same organization. Severity defaults to critical, a business severity level (sev1 to sev3) and a backdated start time may be supplied, and configured webhooks receive an opened event. Requires the incident command plan capability, otherwise 402." } }, "/organizations/{org_id}/incidents/{incident_id}": { "get": { "tags": [ "Incidents" ], "operationId": "get_incident_detail", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "incident_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentDetailDto" } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get incident detail", "description": "Returns full detail for a single incident: status, severity, lifecycle state, cause, affected regions, timestamps, acknowledgement, and commander information. User references are rendered as member email addresses; the monitor reference is its public id and is empty for standalone manual incidents. Accepts API keys.", "x-api-key-enabled": true } }, "/organizations/{org_id}/incidents/{incident_id}/ack": { "post": { "tags": [ "Incidents" ], "operationId": "ack_incident", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "incident_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentDetailDto" } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Acknowledge an incident", "description": "Acknowledges the incident and takes ownership: records the acknowledgement, assigns the caller as commander when nobody is assigned yet, stops the on-call paging escalation, and ends the loud alarm on all connected clients. Returns the full incident detail. Any organization member may acknowledge." } }, "/organizations/{org_id}/incidents/{incident_id}/discard-downtime": { "post": { "tags": [ "Incidents" ], "summary": "Discard a downtime as false alarm", "operationId": "discard_downtime", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "incident_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscardDowntimeRequest" } } }, "required": true }, "responses": { "204": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" }, "409": { "description": "Läuft noch oder bereits verworfen" } }, "security": [ { "bearer": [] } ], "description": "Marks a finished downtime window as a false alarm so it is excluded from uptime percentages, day bars, and the status badge; optionally the incident entry is hidden as well. This changes SLA-effective numbers. Requires an owner or admin role and a reason of at least 5 characters; the action is audited and reversible, and returns 409 if the downtime is still open or already discarded." } }, "/organizations/{org_id}/incidents/{incident_id}/note": { "post": { "tags": [ "Incidents" ], "operationId": "add_incident_note", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "incident_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentDetailDto" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Add a note or status update", "description": "Appends a timeline note to the incident and optionally sets the lifecycle state (investigating, identified, or monitoring). Notes are internal by default; only an explicit public visibility makes them appear on status pages. An empty body without a state change returns 400." } }, "/organizations/{org_id}/incidents/{incident_id}/pages": { "get": { "tags": [ "Incidents" ], "operationId": "list_incident_pages", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "incident_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List status pages linked to an incident", "description": "Returns the ids of the status pages the incident is currently linked to. Requires membership in the organization." }, "post": { "tags": [ "Incidents" ], "operationId": "link_incident_pages", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "incident_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkPagesRequest" } } }, "required": true }, "responses": { "200": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "402": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Link an incident to status pages", "description": "Links the incident to one or more of the organization's status pages so it appears there. Linking is additive and idempotent; use the unlink operation to remove a link. Page ids that do not belong to the organization return 400. Requires the incident command plan capability, otherwise 402." } }, "/organizations/{org_id}/incidents/{incident_id}/pages/{page_id}": { "delete": { "tags": [ "Incidents" ], "operationId": "unlink_incident_page", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "incident_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "page_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "" }, "401": { "description": "" }, "402": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Unlink an incident from a status page", "description": "Removes the link between an incident and one of the organization's status pages so the incident no longer appears on that page. Requires the incident command plan capability, otherwise 402." } }, "/organizations/{org_id}/incidents/{incident_id}/postmortem": { "get": { "tags": [ "Incidents" ], "operationId": "get_postmortem", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "incident_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostmortemDto" } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get an incident post-mortem", "description": "Returns the post-mortem attached to an incident, including impact, root cause, lessons, and its draft or published state. Any organization member may read it; 404 if none exists. Reading is not plan-gated, only writing and publishing are." }, "put": { "tags": [ "Incidents" ], "operationId": "upsert_postmortem", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "incident_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostmortemUpsertRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostmortemDto" } } } }, "401": { "description": "" }, "402": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create or update an incident post-mortem", "description": "Creates or fully replaces the post-mortem document of the incident with title, summary, impact, root cause, contributing factors, what went well and wrong, lessons, and visibility (internal or public). This is a full-replace PUT; all fields must be supplied. Requires the incident command plan capability and returns 402 without it." } }, "/organizations/{org_id}/incidents/{incident_id}/postmortem/publish": { "post": { "tags": [ "Incidents" ], "operationId": "publish_postmortem", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "incident_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostmortemDto" } } } }, "401": { "description": "" }, "402": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Publish an incident post-mortem", "description": "Marks the incident's post-mortem as published, making it eligible to appear on public status pages when its visibility is set to public. Returns the updated post-mortem, or 404 when none exists yet. Requires the incident command plan capability, otherwise 402." } }, "/organizations/{org_id}/incidents/{incident_id}/resolve": { "post": { "tags": [ "Incidents" ], "operationId": "resolve_incident", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "incident_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentDetailDto" } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Resolve an incident manually", "description": "Manually closes an open incident and returns the updated detail. On an actual close a resolved event is recorded and outbound notification connectors fire. Repeating the call on an already closed incident has no side effects. Any organization member may resolve." } }, "/organizations/{org_id}/incidents/{incident_id}/restore-downtime": { "post": { "tags": [ "Incidents" ], "summary": "Restore a discarded downtime", "operationId": "restore_downtime", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "incident_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" }, "409": { "description": "" } }, "security": [ { "bearer": [] } ], "description": "Reverts a previously discarded downtime so it counts again toward uptime, daily bars, and status pages. Requires an owner or admin role; returns 409 when the downtime is not currently discarded. The action is written to the activity log." } }, "/organizations/{org_id}/invitations": { "get": { "tags": [ "Organizations" ], "operationId": "list_invitations", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvitationDto" } } } } }, "401": { "description": "" }, "403": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List pending organization invitations", "description": "Returns the organization's pending invitations with invited email, assigned role, and expiry time. Requires member management rights." }, "post": { "tags": [ "Organizations" ], "operationId": "create_invitation", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteResponse" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "409": { "description": "Already a member or invite exists" } }, "security": [ { "bearer": [] } ], "summary": "Invite a user to an organization", "description": "Creates a pending invitation for the given email and role, enforcing role assignment rules and the plan's seat limit (402 when members plus open invitations exceed it). An invitation email is sent when possible; if delivery is unavailable or fails, the response contains the invite token so the link can be shared manually. Returns 409 if the user is already a member or an invitation already exists. Invitations are accepted through the web application, not through this API." } }, "/organizations/{org_id}/invitations/{inv_id}": { "delete": { "tags": [ "Organizations" ], "operationId": "revoke_invitation", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "inv_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Revoke a pending organization invitation", "description": "Revokes a pending invitation of the organization so its token can no longer be used to join. Requires member management rights; the revocation is audited. Returns 204 on success and 404 when the invitation does not exist." } }, "/organizations/{org_id}/maintenance-windows": { "get": { "tags": [ "Maintenance" ], "operationId": "list_maintenance_windows", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MaintenanceWindowDto" } } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List maintenance windows", "description": "Returns all maintenance windows of the organization with title, body, schedule, cancellation state, public visibility, and the affected monitors. Timestamps are Unix seconds UTC. Requires membership." }, "post": { "tags": [ "Maintenance" ], "operationId": "create_maintenance_window", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaintenanceRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaintenanceWindowDto" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a maintenance window", "description": "Schedules a maintenance window with title, body, start and end (Unix seconds), and the affected monitors. Alerts are suppressed during the window; with public_visible false the window stays internal and is not shown on status pages. End must be after start (400 otherwise), and monitor ids that do not belong to the organization are ignored. Returns 201 with the created window. Requires project management rights." } }, "/organizations/{org_id}/maintenance-windows/{id}": { "delete": { "tags": [ "Maintenance" ], "operationId": "delete_maintenance_window", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a maintenance window", "description": "Permanently removes a maintenance window from the organization, including an active one. Use the cancel operation instead to end a window while keeping its history. Requires project management rights." }, "patch": { "tags": [ "Maintenance" ], "operationId": "update_maintenance_window", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaintenanceRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaintenanceWindowDto" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a maintenance window", "description": "Updates a maintenance window as a full replacement of title, body, start and end (Unix seconds), public visibility, and the affected monitors. End must be after start (400 otherwise), and monitor ids that do not belong to the organization are ignored. Returns the updated window. Requires project management rights." } }, "/organizations/{org_id}/maintenance-windows/{id}/cancel": { "post": { "tags": [ "Maintenance" ], "operationId": "cancel_maintenance_window", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Cancel a maintenance window", "description": "Cancels a scheduled maintenance window so it no longer takes effect or announces itself; the window record itself is kept. Responds 204 without a body. Use delete to remove the record entirely. Requires project management rights." } }, "/organizations/{org_id}/members": { "get": { "tags": [ "Organizations" ], "operationId": "list_members", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MemberDto" } } } } }, "401": { "description": "" }, "403": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List organization members", "description": "Returns all members of the organization with public user id, email, role, and join date. Any organization member may read the list; member emails are visible to every role by design." } }, "/organizations/{org_id}/members/{user_id}": { "delete": { "tags": [ "Organizations" ], "operationId": "remove_member", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" }, "409": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Remove a member from an organization", "description": "Removes a user's membership from the organization. The user_id path segment is the user's public id, not an email. Requires member management rights, cannot target members at or above the caller's own role level, and refuses to remove the last remaining owner with 409." }, "patch": { "tags": [ "Organizations" ], "operationId": "update_member_role", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoleRequest" } } }, "required": true }, "responses": { "204": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" }, "409": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Change a member's role", "description": "Updates an organization member's role. The caller needs member management rights, may not modify members above their own level nor assign a role beyond it, and demoting the last owner is rejected with 409. Unknown role values return 400. The change is audit-logged." } }, "/organizations/{org_id}/on-call/duty": { "get": { "tags": [ "On-Call" ], "operationId": "get_on_call_duty", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnCallDutyDto" } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get current on-call duty", "description": "Resolves who is currently on call for the organization from its rotation settings. Returns the user on duty, or a coverage gap flag when no rotation is configured or nobody is scheduled right now." } }, "/organizations/{org_id}/on-call/members": { "get": { "tags": [ "On-Call" ], "operationId": "get_on_call_members", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnCallMembersDto" } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List the on-call rotation roster", "description": "Returns the ordered on-call rotation roster of the organization as public user ids with positions. Roster entries of users who have left the organization are omitted. Reading the roster is not plan-gated." }, "put": { "tags": [ "On-Call" ], "operationId": "put_on_call_members", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnCallMembersInputDto" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnCallMembersDto" } } } }, "400": { "description": "" }, "401": { "description": "" }, "402": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Replace the on-call roster", "description": "Replaces the ordered on-call rotation roster of the organization. Ids that are not current members are skipped; an empty list clears the roster, while a non-empty list in which no id resolves returns 400 to protect against accidental wipes. Requires organization admin rights and an on-call capable plan (402 otherwise)." } }, "/organizations/{org_id}/on-call/settings": { "get": { "tags": [ "On-Call" ], "operationId": "get_on_call_settings", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnCallSettingsDto" } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get on-call settings", "description": "Returns the organization's on-call configuration: enabled state, timezone, rotation mode, escalation stage timings, the currently resolved duty user, and whether the plan includes on-call. Any member may read; a default configuration is returned when nothing has been set up yet." } }, "/organizations/{org_id}/projects": { "get": { "tags": [ "Projects" ], "operationId": "list_org_projects", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectDto" } } } } }, "401": { "description": "" }, "403": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List projects in an organization", "description": "Returns all projects of an organization visible to the calling member, in their configured order." }, "post": { "tags": [ "Projects" ], "operationId": "create_project", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDto" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "Role may not manage projects" }, "409": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a project in an organization", "description": "Creates a project with the given name; a URL slug is derived server-side from the name. Requires project management rights. A name that normalizes to an empty slug is rejected with 400, a slug collision with 409." } }, "/organizations/{org_id}/status-pages": { "get": { "tags": [ "Status Pages" ], "operationId": "list_status_pages", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StatusPageDto" } } } } }, "401": { "description": "" }, "403": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List status pages of an organization", "description": "Returns all status pages of the organization with name, slug, publication state, and access protection flags. Requires membership." }, "post": { "tags": [ "Status Pages" ], "operationId": "create_status_page", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStatusPageRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageDto" } } } }, "400": { "description": "" }, "401": { "description": "" }, "402": { "description": "Tarif-Limit für Status-Seiten erreicht" }, "403": { "description": "" }, "409": { "description": "Slug bereits vergeben" } }, "security": [ { "bearer": [] } ], "summary": "Create a status page", "description": "Creates a status page with the given name; the URL slug is derived server-side. Returns 201 with the created page, 402 when the plan's status page limit is reached, and 409 when the slug is already taken. Requires project management rights." } }, "/organizations/{org_id}/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "list_webhook_targets", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookTargetDto" } } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List webhook targets", "description": "Lists the organization's outbound webhook and Slack targets, including subscribed events, active state, a masked secret hint, and the result of the last delivery. The full signing secret is never included; it is returned only once on create or rotation. Requires project management rights." }, "post": { "tags": [ "Webhooks" ], "operationId": "create_webhook_target", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookTargetRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTargetCreatedDto" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Create a webhook or Slack target", "description": "Creates an outbound notification target of kind webhook (generic, HMAC-signed) or slack (incoming webhook URL). Subscribed events default to all supported event types; the URL and event names are validated. For generic webhooks the signing secret is generated server-side and returned only in this response; afterwards it is available only masked or via rotation. Requires project management rights." } }, "/organizations/{org_id}/webhooks/{target_id}": { "delete": { "tags": [ "Webhooks" ], "operationId": "delete_webhook_target", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "target_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a webhook target", "description": "Permanently removes a webhook or Slack target from the organization. Returns 204 on success and 404 when the target does not belong to the organization. Requires project management rights." }, "patch": { "tags": [ "Webhooks" ], "operationId": "update_webhook_target", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "target_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookTargetRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTargetDto" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a webhook target", "description": "Partially updates a webhook or Slack target: name, destination URL, subscribed event list, and active flag. Omitted fields keep their current value; the URL and event names are validated, and an explicitly empty name returns 400. The signing secret cannot be changed here, use the rotate-secret operation." } }, "/organizations/{org_id}/webhooks/{target_id}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate a webhook signing secret", "operationId": "rotate_webhook_secret", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "target_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSecretDto" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "description": "Generates a new signing secret for the webhook target and returns it exactly once; signatures made with the previous secret are invalid immediately, there is no dual-secret grace window. Only valid for targets of kind webhook, Slack targets return 400. Requires project management rights." } }, "/organizations/{org_id}/webhooks/{target_id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Send a test event to a webhook", "operationId": "test_webhook_target", "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "target_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResultDto" } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "description": "Synchronously delivers an incident.test event to exactly this webhook or Slack target with a 10 second timeout, and records the outcome as the target's last delivery attempt. Returns whether delivery succeeded and any transport-level error message. Requires project management rights." } }, "/projects/{project_id}": { "delete": { "tags": [ "Projects" ], "operationId": "delete_project", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "reassign_to", "in": "query", "description": "public_id eines Ziel-Projekts: verbliebene Dienste werden vorher dorthin verschoben", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a project", "description": "Deletes a project. Without parameters this is a destructive cascade: all monitors contained in the project are deleted as well. With the optional reassign_to query parameter, remaining monitors are first moved to another project the caller can manage. Passing the deleted project itself as reassign_to returns 400." }, "patch": { "tags": [ "Projects" ], "operationId": "rename_project", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenameRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectDto" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Rename a project", "description": "Updates the display name of a project; the name is the only updatable field. The slug stays unchanged, so existing references keep working. Empty names return 400. The change is recorded in the organization audit log. Requires project management rights." } }, "/projects/{project_id}/monitors": { "get": { "tags": [ "Monitors" ], "operationId": "list_monitors", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorDto" } } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List monitors in a project", "description": "Returns all monitors of a project. Each entry includes the latest quorum-confirmed status and severity rather than the raw result of the last single check. Accepts API keys.", "x-api-key-enabled": true }, "post": { "tags": [ "Monitors" ], "operationId": "create_monitor", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMonitorRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorDto" } } } }, "400": { "description": "A field was refused; `error` and `field` name it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorWriteError" } } } }, "401": { "description": "" }, "402": { "description": "Plan limit: `quota_reached` or `too_many_regions`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorWriteError" } } } }, "403": { "description": "Role may not manage monitors" }, "404": { "description": "" }, "409": { "description": "`name_taken`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorWriteError" } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a monitor in a project", "description": "Creates a monitor of the given type with its configuration, check interval, probe regions, and optional confirmation policy (an alert profile reference or inline quorum values). The interval is raised to the plan minimum and clamped between 30 seconds and 24 hours, omitted regions fall back to a preselected default set, and plan limits on monitor count or region count return 402. Agent monitors instead bind to an enrolled agent, are evaluated server-side, and accept metric-specific configuration such as thresholds or grace periods. A name that collides with an existing monitor slug in the project returns 409. Refusals (400, 402, 409) carry a JSON body with a stable error code such as invalid_target, too_many_regions, quota_reached or name_taken, the refused field as a path such as config.url, for a malformed target the reason such as scheme_in_host, and an English message." } }, "/public/status-pages/{slug}": { "get": { "tags": [ "Public Status" ], "summary": "Get a public status page", "description": "Returns a published status page by slug with overall state, components, active incidents, and maintenance windows. Public pages need no authentication; protected pages answer 401 with a login_required marker instead of any page data. A renamed page may return a redirect hint pointing to its new slug.", "operationId": "public_status_page", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStatusPageDto" } } } }, "401": { "description": "Private Seite: {error:\"login_required\", name, has_logo, has_logo_dark}" }, "404": { "description": "" } } } }, "/public/status-pages/{slug}/badge.svg": { "get": { "tags": [ "Public Status" ], "summary": "Render a status page badge SVG", "operationId": "public_status_page_badge", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "metric", "in": "query", "description": "status (Default) oder uptime", "required": false, "schema": { "type": "string" } }, { "name": "token", "in": "query", "description": "Viewer-Token für private Seiten", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "image/svg+xml": {} } }, "404": { "description": "" } }, "description": "Returns an embeddable shields-style SVG badge showing the page's overall status or, with metric=uptime, the aggregated uptime percentage. Responses are client-cacheable for five minutes and served with permissive cross-origin embedding headers. Protected pages require a valid viewer token or unlock cookie and otherwise answer 404 to hide their existence; the viewer token travels as a query parameter because image tags cannot send headers." } }, "/public/status-pages/{slug}/feed.rss": { "get": { "tags": [ "Public Status" ], "summary": "Fetch a status page RSS feed", "operationId": "public_status_page_feed", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "description": "Viewer-Token für private Seiten", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/rss+xml": {} } }, "404": { "description": "" } }, "description": "Returns an RSS 2.0 feed combining a status page's incidents and upcoming maintenance windows, newest first. Protected pages require a valid viewer token via header or query; without access the endpoint responds 404 to hide the page's existence. Shared-password pages cannot be consumed by feed readers because their unlock is cookie-based." } }, "/public/status-pages/{slug}/logo": { "get": { "tags": [ "Public Status" ], "summary": "Fetch a status page's logo", "operationId": "public_status_page_logo", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "image/*": {} } }, "404": { "description": "" } }, "description": "Serves the logo image of a published status page, addressed by slug, with a five minute public cache header. Returns 404 when the page has no logo. The content type is that of the uploaded image." } }, "/public/status-pages/{slug}/logo/dark": { "get": { "tags": [ "Public Status" ], "summary": "Fetch a status page's dark logo", "operationId": "public_status_page_logo_dark", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "image/*": {} } }, "404": { "description": "" } }, "description": "Serves the dark-mode logo image of a published status page, addressed by slug, with a five minute public cache header. Returns 404 when the page has no dark-mode logo. The content type is that of the uploaded image." } }, "/public/status-pages/{slug}/subscribe": { "post": { "tags": [ "Public Status" ], "summary": "Subscribe to status page updates", "operationId": "subscribe_to_status_page", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscribeRequest" } } }, "required": true }, "responses": { "202": { "description": "" }, "400": { "description": "" }, "404": { "description": "" } }, "description": "Requests an email subscription to a public status page using double opt-in; a confirmation email is sent only for new or still unconfirmed addresses. Always answers 202 for valid addresses and never reveals whether an address is already subscribed. Returns 404 when the page does not exist or does not offer subscriptions." } }, "/status-pages/{id}": { "get": { "tags": [ "Status Pages" ], "operationId": "get_status_page", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageDetailDto" } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Get status page detail", "description": "Returns the full configuration of a status page, including its settings, the assigned monitors with their display options, and whether light and dark logos are uploaded. Requires membership in the owning organization." }, "delete": { "tags": [ "Status Pages" ], "operationId": "delete_status_page", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Archive a status page", "description": "Takes the status page offline immediately and moves it to the archive, from which it can be restored for 90 days. This is not a hard delete. Requires a project management role and responds 204 on success." }, "patch": { "tags": [ "Status Pages" ], "operationId": "update_status_page", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStatusPageRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageDto" } } } }, "400": { "description": "" }, "401": { "description": "" }, "402": { "description": "Privat braucht perstat.private_status_pages, Branding-Ausblenden perstat.white_label (Tarif)" }, "403": { "description": "" }, "404": { "description": "" }, "409": { "description": "Slug bereits vergeben" }, "429": { "description": "Zu viele Slug-Wechsel (max. 3/Woche)" } }, "security": [ { "bearer": [] } ], "summary": "Update status page settings", "description": "Updates the settings of a status page: name, slug, headline, description, publication state, access mode, header navigation, and branding options. Private access modes and hiding the platform branding are plan-gated (402). Slug collisions return 409, and slug changes are rate-limited to three per week (429). Requires project management rights." } }, "/status-pages/{id}/domains": { "get": { "tags": [ "Status Pages" ], "operationId": "list_status_page_domains", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StatusPageDomainDto" } } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "List custom domains of a status page", "description": "Returns the custom domains configured for the status page with verification status, CNAME target, certificate state, and the last error if any. Requires project management rights." }, "post": { "tags": [ "Status Pages" ], "operationId": "create_status_page_domain", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStatusPageDomainRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageDomainDto" } } } }, "400": { "description": "" }, "402": { "description": "" }, "403": { "description": "" }, "404": { "description": "" }, "409": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Add a custom domain to a status page", "description": "Registers a custom domain for the status page and returns the unique CNAME target the customer must configure; ownership verification then runs automatically in the background. Gated by the plan's per-page custom domain limit (402 when exceeded); reserved platform namespaces are rejected and duplicate domains return 409." } }, "/status-pages/{id}/domains/{domain_id}": { "delete": { "tags": [ "Status Pages" ], "operationId": "delete_status_page_domain", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" }, "502": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Remove a custom domain", "description": "Removes a custom domain from the status page and deactivates serving for it. Returns 204 on success; if deactivating a verified domain fails upstream, the call returns 502 and the domain is kept so the call can be retried. Requires project management rights." } }, "/status-pages/{id}/domains/{domain_id}/verify": { "post": { "tags": [ "Status Pages" ], "summary": "Verify a custom domain", "operationId": "verify_status_page_domain", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageDomainDto" } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "description": "Runs the DNS verification for a custom domain synchronously: the domain's CNAME record is checked against its unique target, and on success the domain is marked verified and activated for serving. Returns the current domain state either way. Requires project management rights." } }, "/status-pages/{id}/monitors": { "post": { "tags": [ "Status Pages" ], "operationId": "set_status_page_monitors", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetStatusPageMonitorsRequest" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageDetailDto" } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Set the monitors shown on a status page", "description": "Replaces the full ordered list of monitors shown on the status page, with per-entry display options such as display name, group label, and which uptime visualizations are shown. Returns the updated status page detail. Requires project management rights." } }, "/status-pages/{id}/shared-password": { "put": { "tags": [ "Status Pages" ], "summary": "Set or rotate the shared password", "operationId": "set_status_page_shared_password", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetSharedPasswordRequest" } } }, "required": true }, "responses": { "204": { "description": "" }, "400": { "description": "Kennwort < 12 Zeichen" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "description": "Sets or rotates the shared password of a status page. The password must be at least 12 characters and is stored only as a hash; rotation immediately invalidates all existing shared access sessions. Setting the password is separate from enabling the shared-password access mode in the page settings." }, "delete": { "tags": [ "Status Pages" ], "summary": "Remove a status page shared password", "operationId": "delete_status_page_shared_password", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "description": "Disables shared password access for a status page, clears the stored credential, and invalidates all existing shared access sessions immediately." } }, "/status-pages/{id}/viewers": { "get": { "tags": [ "Status Pages" ], "summary": "List private status page viewers", "operationId": "list_status_page_viewers", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StatusPageViewerDto" } } } } }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "description": "Lists the viewer accounts that can sign in to a private status page, including username, email, creation time, and last successful login. Requires project management rights because the data contains personal information." }, "post": { "tags": [ "Status Pages" ], "summary": "Create a status page viewer account", "operationId": "create_status_page_viewer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateViewerRequest" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateViewerResponse" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" }, "409": { "description": "Username bereits vergeben" } }, "security": [ { "bearer": [] } ], "description": "Creates a login for a private status page. The password is generated server-side and returned exactly once in the response; only a hash is stored at rest. Returns 409 when the username is already taken on this page. Requires project management rights." } }, "/status-pages/{id}/viewers/{viewer_id}": { "delete": { "tags": [ "Status Pages" ], "summary": "Delete a status page viewer account", "operationId": "delete_status_page_viewer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "viewer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "description": "Removes a viewer account from a private status page and revokes that viewer's active sessions. Returns 404 when the viewer does not belong to the page." } } }, "components": { "schemas": { "AgentDto": { "type": "object", "required": [ "id", "hostname", "os", "arch", "agent_version", "modules", "labels", "enrolled_at_unix", "online", "latest_version", "outdated", "inventory_enabled", "monitor_count" ], "properties": { "agent_version": { "type": "string" }, "arch": { "type": "string" }, "enrolled_at_unix": { "type": "integer", "format": "int64" }, "hostname": { "type": "string" }, "id": { "type": "string" }, "inventory_enabled": { "type": "boolean", "description": "Opt-in: Prozessnamen-Inventar übertragen (erweiterte Konfiguration)." }, "labels": {}, "last_cpu_pct": { "type": [ "number", "null" ], "format": "double" }, "last_disk_pct": { "type": [ "number", "null" ], "format": "double" }, "last_heartbeat_at_unix": { "type": [ "integer", "null" ], "format": "int64" }, "last_mem_pct": { "type": [ "number", "null" ], "format": "double" }, "latest_version": { "type": "string", "description": "Neueste verfügbare Agent-Version (für „Update verfügbar\"-Hinweis)." }, "modules": { "type": "array", "items": { "type": "string" } }, "monitor_count": { "type": "integer", "format": "int64", "description": "Aktive Monitore, die auf diesen Agenten zeigen. Der Entfernen-Dialog\nmuss VOR dem Klick sagen können, wie viele davon mit archiviert werden\n(siehe `revoke_agent`) — „N Monitore verschwinden gleich mit\" ist keine\nNachricht, die man erst hinterher bekommen darf." }, "online": { "type": "boolean", "description": "Heartbeat jünger als 180 s (3× Push-Intervall) → online." }, "os": { "type": "string" }, "outdated": { "type": "boolean", "description": "Agent-Version liegt hinter `latest_version`." }, "platform": { "type": [ "string", "null" ] }, "process_inventory": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Zuletzt übertragenes Inventar (nur Prozessnamen) + Zeitpunkt; fürs\nTransparenz-Panel und die Vorschläge im Dienst-Monitor-Formular." }, "process_inventory_at_unix": { "type": [ "integer", "null" ], "format": "int64" } } }, "AlarmGateDto": { "type": "object", "required": [ "origins", "grace_seconds" ], "properties": { "grace_seconds": { "type": "integer", "format": "int64", "description": "Spaetestens so viele Sekunden nach Beginn wird laut alarmiert." }, "origins": { "type": "array", "items": { "type": "string" }, "description": "Ursprungs-Dienste (public_ids). Ist EINER belegt unten, wird gehalten." } } }, "AlarmGateOut": { "type": "object", "description": "Die Alarm-Regel nach aussen: Ursprünge als public_id, damit der Klient\ndieselben Bezeichner sieht wie ueberall sonst.", "required": [ "origins", "grace_seconds" ], "properties": { "grace_seconds": { "type": "integer", "format": "int64" }, "origins": { "type": "array", "items": { "type": "string" } } } }, "CreateIncidentRequest": { "type": "object", "description": "Manuellen Incident anlegen. `monitor_id` optional (Public-ID) — fehlt er, ist\nes ein eigenständiger Incident ohne Monitor (Dienstleister-/Info-Meldung).", "required": [ "summary" ], "properties": { "cause": { "type": [ "string", "null" ] }, "monitor_id": { "type": [ "string", "null" ] }, "severity": { "type": [ "string", "null" ], "description": "`critical` (Ausfall, Default) oder `degraded` (Einschränkung)." }, "severity_level": { "type": [ "string", "null" ], "description": "Fachliche Stufe: `sev1|sev2|sev3` (optional)." }, "started_at_unix": { "type": [ "integer", "null" ], "format": "int64", "description": "Beginn (Unix-Sekunden); fehlt → jetzt. Für Backfill vergangener Vorfälle." }, "summary": { "type": "string" } } }, "CreateMonitorRequest": { "type": "object", "required": [ "name", "type", "config" ], "properties": { "config": {}, "interval_seconds": { "type": [ "integer", "null" ], "format": "int32" }, "name": { "type": "string" }, "policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MonitorPolicyDto", "description": "Confirmation-Policy (Alarmprofil-Zuweisung oder Inline-Eigenwerte)." } ] }, "regions": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Pruef-Regionen. Weggelassen/leer → 3 vorausgewaehlte (ewr/fra/sgp)." }, "type": { "type": "string" } } }, "CreateOrganizationRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "CreateProjectRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "CreateStatusPageDomainRequest": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string" }, "method": { "type": [ "string", "null" ], "description": "Veraltet/ignoriert — Verifizierung ist immer CNAME (autoritativ). Bleibt\nfür Abwärtskompatibilität des Contracts erhalten." } } }, "CreateStatusPageRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "CreateViewerRequest": { "type": "object", "required": [ "username", "email" ], "properties": { "email": { "type": "string" }, "username": { "type": "string" } } }, "CreateViewerResponse": { "type": "object", "required": [ "viewer", "password" ], "properties": { "password": { "type": "string", "description": "Generiertes Klartext-Passwort — wird NUR HIER, EINMALIG zurückgegeben.\nAt rest liegt ausschließlich der Argon2-Hash." }, "viewer": { "$ref": "#/components/schemas/StatusPageViewerDto" } } }, "CreateWebhookTargetRequest": { "type": "object", "required": [ "name" ], "properties": { "credential": { "type": [ "string", "null" ], "description": "Schlüssel des Anbieters: Integrationsschlüssel (PagerDuty) bzw.\nAPI-Schlüssel (Opsgenie). Pflicht für genau diese beiden Arten." }, "events": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Default: alle Ereignisse." }, "kind": { "type": [ "string", "null" ], "description": "Benannte Art aus dem Katalog. Weggelassen = `webhook` (Bestandsverhalten\nder ersten Fassung, als es nur Webhook und Slack gab)." }, "name": { "type": "string" }, "region": { "type": [ "string", "null" ], "description": "Anbieter-Region für `pagerduty`/`opsgenie`: `global` (Default) | `eu`." }, "url": { "type": [ "string", "null" ], "description": "Anbieter-URL. Pflicht für `slack`, `teams`, `discord`, `google_chat`,\n`webhook`; bei `pagerduty`/`opsgenie` ignoriert (der Server leitet den\nEndpunkt aus Art und Region ab)." } } }, "DiscardDowntimeRequest": { "type": "object", "required": [ "reason" ], "properties": { "delete_incident": { "type": "boolean", "description": "Zugehörige Incident-Meldung ebenfalls aus der öffentlichen Historie entfernen." }, "reason": { "type": "string", "description": "Pflicht-Begründung (Audit-Trail)." } } }, "EffectiveAlarmConfirmationDto": { "type": "object", "required": [ "source", "alarm_quorum_mode", "alarm_quorum_value", "alarm_consecutive" ], "properties": { "alarm_consecutive": { "type": "integer", "format": "int32" }, "alarm_min_duration_seconds": { "type": [ "integer", "null" ], "format": "int32" }, "alarm_quorum_mode": { "type": "string" }, "alarm_quorum_value": { "type": "integer", "format": "int32" }, "source": { "type": "string", "description": "`flow` for configured editor flows, otherwise `monitor_override` or\n`legacy`." } } }, "IncidentDetailDto": { "type": "object", "required": [ "id", "monitor_id", "status", "severity", "lifecycle_state", "cause", "summary", "down_regions", "region_count", "started_at_unix", "auto_resolved" ], "properties": { "acknowledged_at_unix": { "type": [ "integer", "null" ], "format": "int64" }, "acknowledged_by_email": { "type": [ "string", "null" ] }, "alarm_held_by_name": { "type": [ "string", "null" ] }, "alarm_held_until_unix": { "type": [ "integer", "null" ], "format": "int64", "description": "Abhaengige Alarme: bis wann die Alarmkette zurueckgehalten wird\n(Unix-Sekunden), und WER sie haelt. Beides gehoert nach aussen , ein\nzurueckgehaltener Alarm, den man nicht sehen kann, ist von einem\nverschluckten nicht zu unterscheiden." }, "auto_resolved": { "type": "boolean" }, "cause": { "type": "string" }, "check_kind": { "type": [ "string", "null" ] }, "commander_email": { "type": [ "string", "null" ] }, "down_regions": { "type": "array", "items": { "type": "string" } }, "evidence": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/IncidentEvidenceDto", "description": "Immutable trigger snapshot; null for legacy/manual/simulated incidents." } ] }, "failure_phase_started_at_unix": { "type": [ "integer", "null" ], "format": "int64", "description": "First quorum-confirmed failure of the uninterrupted measurement phase." }, "id": { "type": "string" }, "lifecycle_state": { "type": "string" }, "monitor_id": { "type": "string" }, "monitor_name": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ], "description": "Stable project public id for monitor drill-down, including legacy or\nmanual incidents without an immutable evidence snapshot." }, "project_name": { "type": [ "string", "null" ] }, "region_count": { "type": "integer", "format": "int32" }, "resolved_at_unix": { "type": [ "integer", "null" ], "format": "int64" }, "severity": { "type": "string" }, "severity_level": { "type": [ "string", "null" ] }, "started_at_unix": { "type": "integer", "format": "int64" }, "status": { "type": "string" }, "summary": { "type": "string" } } }, "IncidentDto": { "type": "object", "required": [ "id", "monitor_id", "status", "severity", "cause", "down_regions", "region_count", "started_at_unix" ], "properties": { "cause": { "type": "string" }, "down_regions": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "monitor_id": { "type": "string" }, "monitor_name": { "type": [ "string", "null" ] }, "project_name": { "type": [ "string", "null" ] }, "region_count": { "type": "integer", "format": "int32" }, "resolved_at_unix": { "type": [ "integer", "null" ], "format": "int64" }, "severity": { "type": "string" }, "started_at_unix": { "type": "integer", "format": "int64" }, "status": { "type": "string" } } }, "IncidentEvidenceCheckDto": { "type": "object", "required": [ "check_id", "checked_at_unix", "status" ], "properties": { "cause_layer": { "type": [ "string", "null" ], "description": "Target attribution such as `target_dns` or `target_app`." }, "check_id": { "type": "string" }, "checked_at_unix": { "type": "integer", "format": "int64" }, "detail": { "type": [ "string", "null" ] }, "latency_ms": { "type": [ "integer", "null" ], "format": "int32" }, "region": { "type": [ "string", "null" ] }, "response_code": { "type": [ "integer", "null" ], "format": "int32" }, "status": { "type": "string" } } }, "IncidentEvidenceDto": { "type": "object", "required": [ "version", "monitor_id", "monitor_name", "project_id", "project_name", "check_kind", "triggered_at_unix", "reason", "required_regions", "failed_regions", "reporting_regions", "consecutive_failures_required", "checks" ], "properties": { "actual_summary": { "type": [ "string", "null" ] }, "check_kind": { "type": "string" }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/IncidentEvidenceCheckDto" } }, "confirmation_state": { "type": [ "string", "null" ] }, "confirmed_outage_since_unix": { "type": [ "integer", "null" ], "format": "int64" }, "consecutive_failures_observed": { "type": [ "integer", "null" ], "format": "int32" }, "consecutive_failures_required": { "type": "integer", "format": "int32" }, "expected_regions": { "type": [ "integer", "null" ], "format": "int32" }, "expected_summary": { "type": [ "string", "null" ] }, "failed_regions": { "type": "integer", "minimum": 0 }, "failure_class": { "type": [ "string", "null" ] }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/IncidentEvidenceFindingDto" } }, "first_failure_at_unix": { "type": [ "integer", "null" ], "format": "int64" }, "minimum_confirmed_outage_seconds": { "type": [ "integer", "null" ], "format": "int32" }, "monitor_id": { "type": "string" }, "monitor_name": { "type": "string" }, "project_id": { "type": "string" }, "project_name": { "type": "string", "description": "Project is the stored product context; Perstat has no environment field." }, "reason": { "type": "string" }, "reporting_regions": { "type": "integer", "format": "int32" }, "required_regions": { "type": "integer", "format": "int32" }, "triggered_at_unix": { "type": "integer", "format": "int64" }, "version": { "type": "integer", "format": "int32" } } }, "IncidentEvidenceFindingDto": { "type": "object", "required": [ "failure_class", "expected_summary", "actual_summary", "occurrence_count", "regions", "latest_checked_at_unix" ], "properties": { "actual_summary": { "type": "string" }, "expected_summary": { "type": "string" }, "failure_class": { "type": "string" }, "latest_checked_at_unix": { "type": "integer", "format": "int64" }, "occurrence_count": { "type": "integer", "minimum": 0 }, "regions": { "type": "array", "items": { "type": "string" } } } }, "InvitationDto": { "type": "object", "required": [ "id", "email", "role", "expires_at_unix" ], "properties": { "email": { "type": "string" }, "expires_at_unix": { "type": "integer", "format": "int64" }, "id": { "type": "string", "description": "Public-ID der Einladung (`inv_…`)." }, "role": { "type": "string" } } }, "InviteRequest": { "type": "object", "required": [ "email", "role" ], "properties": { "email": { "type": "string" }, "role": { "type": "string" } } }, "InviteResponse": { "type": "object", "required": [ "invitation" ], "properties": { "invitation": { "$ref": "#/components/schemas/InvitationDto" }, "invite_token": { "type": [ "string", "null" ], "description": "Dev-Modus (kein SMTP): das einmalige Einladungs-Token, damit das Frontend\nden Einladungs-Link selbst anzeigen kann. Mit Mailer wäre dies `null` und\nder Link würde per E-Mail zugestellt." } } }, "LinkPagesRequest": { "type": "object", "description": "Incident explizit auf gewählte Status-Seiten publizieren (Public-IDs).", "required": [ "status_page_ids" ], "properties": { "status_page_ids": { "type": "array", "items": { "type": "string" } } } }, "MaintenanceMonitorDto": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "description": "Monitor-public_id." }, "name": { "type": "string" } } }, "MaintenanceRequest": { "type": "object", "required": [ "scheduled_start", "scheduled_end" ], "properties": { "body": { "type": "string" }, "monitors": { "type": "array", "items": { "type": "string" }, "description": "Betroffene Monitore (public_ids; fremde IDs werden ignoriert)." }, "public_visible": { "type": "boolean", "description": "Auf den Status-Seiten anzeigen (Default true). `false` = internes Fenster:\nAlarme bleiben unterdrückt, aber die öffentliche Seite zeigt nichts." }, "scheduled_end": { "type": "integer", "format": "int64" }, "scheduled_start": { "type": "integer", "format": "int64", "description": "Unix-Sekunden (UTC)." }, "title": { "type": "string" } } }, "MaintenanceWindowDto": { "type": "object", "required": [ "id", "title", "body", "scheduled_start", "scheduled_end", "cancelled", "public_visible", "monitors" ], "properties": { "body": { "type": "string" }, "cancelled": { "type": "boolean" }, "id": { "type": "string", "description": "Fenster-public_id." }, "monitors": { "type": "array", "items": { "$ref": "#/components/schemas/MaintenanceMonitorDto" } }, "public_visible": { "type": "boolean", "description": "Erscheint das Fenster auf den Status-Seiten? (Alarm-Unterdrückung und\nSLA-Ausschluss gelten unabhängig davon.)" }, "scheduled_end": { "type": "integer", "format": "int64" }, "scheduled_start": { "type": "integer", "format": "int64", "description": "Unix-Sekunden (UTC)." }, "title": { "type": "string" } } }, "MemberDto": { "type": "object", "required": [ "user_id", "email", "role", "joined_at_unix" ], "properties": { "email": { "type": "string" }, "joined_at_unix": { "type": "integer", "format": "int64" }, "name": { "type": [ "string", "null" ], "description": "Anzeigename, falls gesetzt. Siehe [`MeResponse::name`]." }, "role": { "type": "string" }, "user_id": { "type": "string", "description": "Public-ID des Users (`usr_…`)." } } }, "MonitorCheckDto": { "type": "object", "required": [ "id", "monitor_id", "status", "created_at_unix" ], "properties": { "created_at_unix": { "type": "integer", "format": "int64" }, "detail": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "latency_ms": { "type": [ "integer", "null" ], "format": "int32" }, "monitor_id": { "type": "string" }, "region": { "type": [ "string", "null" ] }, "response_code": { "type": [ "integer", "null" ], "format": "int32" }, "severity": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "subchecks": { "description": "Structured per-dimension breakdown (family/TLS) — see check-engines\n`SubResult`. Null for checks recorded before this field existed.\nFreeform (`Value`, KEIN `Object`): der Server sendet ein ARRAY von\nSubResults — ein object-Typ ließe streng typisierte Clients\n(swift-openapi-generator → OpenAPIObjectContainer) am Array scheitern." } } }, "MonitorDto": { "type": "object", "required": [ "id", "project_id", "name", "slug", "type", "config", "interval_seconds", "enabled", "regions" ], "properties": { "alarm_gate": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AlarmGateOut", "description": "Abhaengige Alarme. Wie die Policy nur in der EINZELANSICHT gefuellt ,\nin Listen bleibt sie weg, damit eine Monitor-Liste nicht je Zeile eine\nzweite Abfrage ausloest." } ] }, "config": {}, "enabled": { "type": "boolean" }, "id": { "type": "string" }, "interval_seconds": { "type": "integer", "format": "int32" }, "last_severity": { "type": [ "string", "null" ], "description": "Severity des rohen jüngsten Checks (informativ; nicht für die Tönung)." }, "last_status": { "type": [ "string", "null" ], "description": "**Bestätigter** Anzeige-Status für den Gesundheits-Punkt je Dienst:\n`failed` (rot) = offener Incident/Quorum-Ausfall, `degraded` (gelb) =\nunbestätigtes Problem (z. B. einzelner Vantage-Point), `passed` (grün).\nNone = noch kein Check. Folgt damit derselben Logik wie Alarm/Push." }, "name": { "type": "string" }, "policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MonitorPolicyDto", "description": "Confirmation-Policy (Alarmprofil/Inline). Nur in der Einzelansicht\ngefüllt; in Listen None." } ] }, "project_id": { "type": "string" }, "regions": { "type": "array", "items": { "type": "string" } }, "slug": { "type": "string" }, "type": { "type": "string" } } }, "MonitorPolicyDto": { "type": "object", "description": "Roh-Policy eines Monitors fürs Formular (zugewiesenes Profil als public_id +\noptionale Inline-Eigenwerte; alle None = Default).", "properties": { "alarm_consecutive": { "type": [ "integer", "null" ], "format": "int32" }, "alarm_min_duration_seconds": { "type": [ "integer", "null" ], "format": "int32", "description": "Legacy per-monitor duration. A configured organization flow is the\ncanonical effective source." }, "alarm_quorum_mode": { "type": [ "string", "null" ] }, "alarm_quorum_value": { "type": [ "integer", "null" ], "format": "int32" }, "alert_profile_id": { "type": [ "string", "null" ] }, "effective_alarm": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EffectiveAlarmConfirmationDto" } ] }, "failed_interval_seconds": { "type": [ "integer", "null" ], "format": "int32" }, "recovery_consecutive": { "type": [ "integer", "null" ], "format": "int32" }, "recovery_quorum_mode": { "type": [ "string", "null" ] }, "recovery_quorum_value": { "type": [ "integer", "null" ], "format": "int32" } } }, "MonitorSeriesDto": { "type": "object", "description": "Zeitreihe für die Monitor-Detailansicht: serverseitig in Buckets aggregiert,\ndamit auch große Zeiträume (bis 90 Tage) wenige, gleichmäßige Punkte liefern.", "required": [ "range", "bucket_seconds", "from_unix", "to_unix", "stats", "points" ], "properties": { "bucket_seconds": { "type": "integer", "format": "int64" }, "from_unix": { "type": "integer", "format": "int64" }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorSeriesPointDto" } }, "range": { "type": "string" }, "stats": { "$ref": "#/components/schemas/MonitorSeriesStatsDto" }, "to_unix": { "type": "integer", "format": "int64" } } }, "MonitorSeriesPointDto": { "type": "object", "description": "Ein aggregierter Zeit-Bucket je Region für den Detail-Chart.", "required": [ "bucket_unix", "up", "down", "degraded" ], "properties": { "avg_ms": { "type": [ "integer", "null" ], "format": "int32" }, "bucket_unix": { "type": "integer", "format": "int64" }, "degraded": { "type": "integer", "format": "int64" }, "down": { "type": "integer", "format": "int64" }, "max_ms": { "type": [ "integer", "null" ], "format": "int32" }, "region": { "type": [ "string", "null" ] }, "up": { "type": "integer", "format": "int64" } } }, "MonitorSeriesStatsDto": { "type": "object", "description": "Range-Aggregat für die Stat-Cards (Uptime/Ø/P95/Anzahl).", "required": [ "checks" ], "properties": { "avg_ms": { "type": [ "integer", "null" ], "format": "int32" }, "checks": { "type": "integer", "format": "int64" }, "p95_ms": { "type": [ "integer", "null" ], "format": "int32" }, "uptime_pct": { "type": [ "number", "null" ], "format": "double" } } }, "MonitorWriteError": { "type": "object", "description": "Body of a refused monitor write. Branch on `error`, which is stable;\n`message` explains the refusal in English.", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable code: `quota_reached`, `name_taken`, `invalid_request`,\n`unknown_type`, `empty_name`, `unknown_region`, `internal_region`,\n`too_many_regions`, `alarm_standard_unreachable`, `invalid_target`,\n`unknown_agent_metric`, `invalid_service_name` or `foreign_agent`.", "example": "invalid_target" }, "field": { "type": [ "string", "null" ], "description": "The refused field as a path into the monitor, such as `config.url` or\n`regions`. Absent when no single field is at fault.", "example": "config.url" }, "limit": { "type": [ "integer", "null" ], "format": "int64", "description": "With `too_many_regions`: the most regions the plan checks a monitor from.\nWith `alarm_standard_unreachable`: the distinct regions the organization's\nalarm standard needs." }, "message": { "type": "string", "description": "The reason as an English sentence that names the field." }, "reason": { "type": [ "string", "null" ], "description": "With `invalid_target`: what is wrong with the target. One of `missing`,\n`whitespace`, `scheme_in_host`, `path_in_host`, `malformed_label`,\n`too_long`, `unsupported_scheme`, `no_host`, `needs_two_labels` or\n`port_range`.", "example": "unsupported_scheme" } } }, "NavLink": { "type": "object", "description": "Ein Navigationselement der Header-Bar.", "required": [ "label", "href" ], "properties": { "href": { "type": "string" }, "label": { "type": "string" } } }, "NoteRequest": { "type": "object", "properties": { "body": { "type": "string" }, "state": { "type": [ "string", "null" ] }, "visibility": { "type": [ "string", "null" ], "description": "`\"public\"` → das Update erscheint auf der öffentlichen Status-Seite.\nAlles andere (None/\"\") bleibt intern (sicherer Default, kein Leak)." } } }, "OnCallDutyDto": { "type": "object", "required": [ "coverage_gap" ], "properties": { "coverage_gap": { "type": "boolean" }, "current_duty_user_id": { "type": [ "string", "null" ] } } }, "OnCallMemberDto": { "type": "object", "required": [ "user_id", "position" ], "properties": { "position": { "type": "integer", "format": "int32" }, "user_id": { "type": "string", "description": "Interner User-UUID." } } }, "OnCallMembersDto": { "type": "object", "required": [ "members" ], "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/OnCallMemberDto" } } } }, "OnCallMembersInputDto": { "type": "object", "required": [ "members" ], "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/OnCallMemberDto" } } } }, "OnCallSettingsDto": { "type": "object", "required": [ "enabled", "timezone", "rotation_mode", "escalation_stage1_minutes", "escalation_stage2_minutes", "channel_step_minutes", "entitled" ], "properties": { "channel_step_minutes": { "type": "integer", "format": "int32" }, "current_duty_user_id": { "type": [ "string", "null" ], "description": "Wer hat JETZT Dienst (aufgelöst); null bei Coverage-Gap." }, "enabled": { "type": "boolean" }, "entitled": { "type": "boolean", "description": "Ist On-Call im Tarif enthalten (monitor.on_call)? Steuert die UI-Sperre." }, "escalation_stage1_minutes": { "type": "integer", "format": "int32" }, "escalation_stage2_minutes": { "type": "integer", "format": "int32" }, "manual_duty_user_id": { "type": [ "string", "null" ], "description": "Interner User-UUID des manuellen Diensthabenden (oder null)." }, "rotation_mode": { "type": "string", "description": "\"manual\" | \"weekly\"" }, "timezone": { "type": "string" } } }, "OrganizationDto": { "type": "object", "required": [ "id", "name", "slug" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "PostmortemDto": { "type": "object", "description": "Post-mortem (Nachbereitung) eines Incidents.", "required": [ "title", "summary", "impact", "root_cause", "contributing_factors", "what_went_well", "what_went_wrong", "lessons", "status", "visibility" ], "properties": { "contributing_factors": { "type": "string" }, "impact": { "type": "string" }, "lessons": { "type": "string" }, "published_at_unix": { "type": [ "integer", "null" ], "format": "int64" }, "root_cause": { "type": "string" }, "status": { "type": "string" }, "summary": { "type": "string" }, "title": { "type": "string" }, "visibility": { "type": "string" }, "what_went_well": { "type": "string" }, "what_went_wrong": { "type": "string" } } }, "PostmortemUpsertRequest": { "type": "object", "description": "Post-mortem anlegen/aktualisieren (Inhalte; Publizieren ist ein eigener Schritt).", "properties": { "contributing_factors": { "type": "string" }, "impact": { "type": "string" }, "lessons": { "type": "string" }, "root_cause": { "type": "string" }, "summary": { "type": "string" }, "title": { "type": "string" }, "visibility": { "type": [ "string", "null" ], "description": "`internal` (Default) oder `public` (auf publizierten Status-Seiten sichtbar)." }, "what_went_well": { "type": "string" }, "what_went_wrong": { "type": "string" } } }, "ProjectDto": { "type": "object", "required": [ "id", "organization_id", "name", "slug" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "organization_id": { "type": "string" }, "slug": { "type": "string" } } }, "PublicBarDto": { "type": "object", "required": [ "ts", "status", "impact_seconds" ], "properties": { "impact_seconds": { "type": "integer", "format": "int64", "description": "Akkumulierte Ausfall-/Beeinträchtigungsdauer des Tages in Sekunden (0 = keine)." }, "status": { "type": "string", "description": "passed | degraded | failed | unknown." }, "ts": { "type": "integer", "format": "int64", "description": "Tagesbeginn (Unix-Sekunden, UTC)." } } }, "PublicComponentDto": { "type": "object", "required": [ "label", "group", "status", "uptime_window_days", "show_sparkline", "show_uptime_bars", "show_uptime_chart", "sparkline", "bars" ], "properties": { "bars": { "type": "array", "items": { "$ref": "#/components/schemas/PublicBarDto" }, "description": "Status je Tag, alt → neu (Uptime-Balken)." }, "group": { "type": "string", "description": "Effektive Gruppe (Override oder Projektname) — Sektions-Bündelung." }, "label": { "type": "string" }, "show_sparkline": { "type": "boolean" }, "show_uptime_bars": { "type": "boolean" }, "show_uptime_chart": { "type": "boolean" }, "sparkline": { "type": "array", "items": { "type": "number", "format": "double" }, "description": "Ø-Antwortzeit (ms) je Tag, alt → neu (Sparkline)." }, "status": { "type": "string", "description": "passed | degraded | failed | unknown." }, "uptime_pct": { "type": [ "number", "null" ], "format": "double", "description": "Uptime% im Anzeigefenster; `null`, wenn keine Daten." }, "uptime_window_days": { "type": "integer", "format": "int32", "description": "Effektives Fenster in Tagen (auf Tarif-Retention geklammert)." } } }, "PublicIncidentDto": { "type": "object", "required": [ "id", "component", "status", "severity", "lifecycle_state", "summary", "started_at", "updates" ], "properties": { "component": { "type": "string", "description": "Betroffene Komponente (Seiten-Label des Monitors)." }, "id": { "type": "string", "description": "Opake Incident-ID (Permalink/React-Key)." }, "lifecycle_state": { "type": "string", "description": "detected|acknowledged|investigating|identified|monitoring|resolved." }, "postmortem": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PublicPostmortemDto", "description": "Veröffentlichtes öffentliches Post-mortem (nur bei publizierter Nachbereitung)." } ] }, "resolved_at": { "type": [ "integer", "null" ], "format": "int64" }, "severity": { "type": "string", "description": "critical | degraded (technische Schwere; steuert die Tönung)." }, "started_at": { "type": "integer", "format": "int64", "description": "Unix-Sekunden (UTC)." }, "status": { "type": "string", "description": "open | resolved." }, "summary": { "type": "string", "description": "Optionale öffentliche Zusammenfassung (\"\" = keine)." }, "updates": { "type": "array", "items": { "$ref": "#/components/schemas/PublicIncidentUpdateDto" }, "description": "Öffentliche Timeline-Updates (älteste zuerst)." } } }, "PublicIncidentUpdateDto": { "type": "object", "required": [ "kind", "body", "created_at" ], "properties": { "body": { "type": "string" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix-Sekunden (UTC)." }, "kind": { "type": "string", "description": "note | status." }, "state": { "type": [ "string", "null" ], "description": "Lebenszyklus-Phase, falls dieses Update eine Statusänderung war." } } }, "PublicMaintenanceDto": { "type": "object", "description": "Öffentlich sichtbares Wartungsfenster (für die Status-Seite).", "required": [ "id", "title", "body", "scheduled_start", "scheduled_end", "components" ], "properties": { "body": { "type": "string" }, "components": { "type": "array", "items": { "type": "string" }, "description": "Betroffene Komponenten (Seiten-Labels)." }, "id": { "type": "string" }, "scheduled_end": { "type": "integer", "format": "int64" }, "scheduled_start": { "type": "integer", "format": "int64", "description": "Unix-Sekunden (UTC)." }, "title": { "type": "string" } } }, "PublicPostmortemDto": { "type": "object", "description": "Veröffentlichtes, kundenseitiges Post-mortem (nur die Außendarstellung).", "required": [ "summary", "impact", "root_cause", "lessons", "published_at" ], "properties": { "impact": { "type": "string" }, "lessons": { "type": "string" }, "published_at": { "type": "integer", "format": "int64", "description": "Unix-Sekunden (UTC)." }, "root_cause": { "type": "string" }, "summary": { "type": "string" } } }, "PublicStatusPageDto": { "type": "object", "required": [ "name", "overall", "components", "incidents", "maintenances", "header_nav", "has_logo", "has_logo_dark", "collapsed_groups", "vantage_points", "subscriptions_enabled", "white_label" ], "properties": { "collapsed_groups": { "type": "array", "items": { "type": "string" }, "description": "Gruppen-Namen, die initial eingeklappt dargestellt werden (Anzeige-Vorgabe;\nder Viewer kann sie manuell aufklappen)." }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/PublicComponentDto" } }, "description": { "type": [ "string", "null" ] }, "has_logo": { "type": "boolean", "description": "Ob ein Logo existiert (→ `/public/status-pages/{slug}/logo`)." }, "has_logo_dark": { "type": "boolean", "description": "Ob ein Dark-Mode-Logo existiert (→ `/public/status-pages/{slug}/logo/dark`).\nDie Public-SPA nutzt es im Dark-Theme, sonst Fallback aufs Standard-Logo." }, "header_nav": { "type": "array", "items": { "$ref": "#/components/schemas/NavLink" }, "description": "Header-Navigation (Label + URL)." }, "headline": { "type": [ "string", "null" ], "description": "Optionaler Untertitel/Tagline." }, "incidents": { "type": "array", "items": { "$ref": "#/components/schemas/PublicIncidentDto" }, "description": "Aktive + innerhalb des Fensters behobene Incidents (öffentlich sichtbar),\noffene zuerst. Leer, wenn keine." }, "maintenances": { "type": "array", "items": { "$ref": "#/components/schemas/PublicMaintenanceDto" }, "description": "Laufende + demnächst geplante Wartungsfenster, die Monitore dieser Seite\nbetreffen. Leer, wenn keine." }, "name": { "type": "string", "description": "Öffentlicher Titel = der Seitenname (prominentes Editor-Feld)." }, "overall": { "type": "string", "description": "Gesamtstatus = schlechtester Komponenten-Status." }, "redirect_slug": { "type": [ "string", "null" ], "description": "Gesetzt, wenn der angefragte Slug ein reservierter Alt-Slug ist: die SPA\nleitet dann hart auf `.perstat.io` um." }, "subscriptions_enabled": { "type": "boolean", "description": "Ob die Org dieser Seite Statusseiten-Abonnements anbieten darf (Tarif-Cap\n`monitor.status_page_subscribers`). Die Public-SPA blendet das Abo-Formular\nnur dann ein. Der Subscribe-Endpoint gated zusätzlich serverseitig." }, "vantage_points": { "type": "array", "items": { "$ref": "#/components/schemas/VantagePointDto" }, "description": "Aktive Prüf-Standorte (PoPs) der Plattform für die „Geprüft aus\"-Transparenz\n(ADR-0010). Global (kein Tenant-Bezug); leer, wenn keine bekannten Standorte." }, "white_label": { "type": "boolean", "description": "EFFEKTIVES White-Label dieser Seite: Tarif-Cap `monitor.white_label`\n(ab Command) UND Per-Seite-Toggle `hide_datargo_brand`. Blendet\n„Powered by Perstat\" aus; die Public-SPA versteckt den Footer-Hinweis." } } }, "RenameRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "SetSharedPasswordRequest": { "type": "object", "required": [ "password" ], "properties": { "password": { "type": "string", "description": "Klartext-Kennwort (min. 12 Zeichen). Wird Argon2-gehasht; at rest liegt nur\nder Hash. Wird NIE im DTO zurückgegeben." } } }, "SetStatusPageMonitorsRequest": { "type": "object", "required": [ "monitors" ], "properties": { "monitors": { "type": "array", "items": { "$ref": "#/components/schemas/StatusPageMonitorInput" }, "description": "Geordnete Monitor-Liste (Position = sort_order)." } } }, "StatusPageDetailDto": { "type": "object", "required": [ "page", "monitors", "has_logo", "has_logo_dark" ], "properties": { "has_logo": { "type": "boolean", "description": "Ob die Seite ein Logo hat (für den Editor)." }, "has_logo_dark": { "type": "boolean", "description": "Ob die Seite ein Dark-Mode-Logo hat (für den Editor)." }, "monitors": { "type": "array", "items": { "$ref": "#/components/schemas/StatusPageMonitorDto" } }, "page": { "$ref": "#/components/schemas/StatusPageDto" } } }, "StatusPageDomainDto": { "type": "object", "required": [ "id", "domain", "verification_method", "status", "verification_token", "cname_target", "edge_synced" ], "properties": { "cert_status": { "type": [ "string", "null" ], "description": "Vom Edge gemeldeter Cert-Status." }, "cname_target": { "type": "string", "description": "CNAME-Ziel, das der Kunde setzen soll." }, "domain": { "type": "string" }, "edge_synced": { "type": "boolean", "description": "`true`, sobald die Domain erfolgreich als VHost an die Edge gepusht wurde.\nEine verifizierte Domain mit `edge_synced=false` ist noch in Bereitstellung\n(Edge-Push steht aus / wird vom Reconcile nachgezogen) und serviert noch nicht." }, "id": { "type": "string", "description": "public_id (`spd_…`)." }, "last_error": { "type": [ "string", "null" ] }, "status": { "type": "string", "description": "`pending` | `verified` | `failed`." }, "verification_method": { "type": "string", "description": "`cname` | `txt`." }, "verification_token": { "type": "string", "description": "Wert für den TXT-Record `_datargo-verify.`." }, "verified_at": { "type": [ "integer", "null" ], "format": "int64", "description": "Unix-Sekunden der Verifikation." } } }, "StatusPageDto": { "type": "object", "required": [ "id", "organization_id", "name", "slug", "enabled", "public_viewable", "password_protected", "shared_password_protected", "shared_password_set", "hide_datargo_brand", "header_nav", "collapsed_groups" ], "properties": { "collapsed_groups": { "type": "array", "items": { "type": "string" }, "description": "Gruppen-Namen, die auf der publizierten Seite standardmäßig eingeklappt sind." }, "description": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "header_nav": { "type": "array", "items": { "$ref": "#/components/schemas/NavLink" }, "description": "Header-Navigation (Label + URL)." }, "headline": { "type": [ "string", "null" ] }, "hide_datargo_brand": { "type": "boolean", "description": "Per-Seite-Schalter „Perstat-Branding ausblenden\". Wirksam nur zusammen\nmit der Tarif-Cap `monitor.white_label` (siehe `white_label_available`\nim Detail-DTO); ohne Cap bleibt der gespeicherte Wert wirkungslos." }, "id": { "type": "string" }, "name": { "type": "string" }, "organization_id": { "type": "string" }, "password_protected": { "type": "boolean", "description": "Privat: publizierte Seite hinter Viewer-Login (orthogonal zu `public_viewable`)." }, "public_viewable": { "type": "boolean" }, "shared_password_protected": { "type": "boolean", "description": "Gemeinsames Kennwort: EIN geteiltes Passwort schaltet die ganze Seite frei\n(orthogonal zu `public_viewable`, mutually-exclusive zu `password_protected`)." }, "shared_password_set": { "type": "boolean", "description": "Ob ein geteiltes Kennwort GESETZT ist (Hash vorhanden). Niemals das Klartext —\nnur dieser bool, damit der Editor „gesetzt/leer\" anzeigen kann." }, "slug": { "type": "string" } } }, "StatusPageMonitorDto": { "type": "object", "required": [ "monitor", "label", "project", "sort_order", "show_sparkline", "show_uptime_bars", "show_uptime_chart", "uptime_window_days" ], "properties": { "display_name": { "type": [ "string", "null" ], "description": "Rohe abweichende Bezeichnung (`null` → Monitor-Name) — für den Editor." }, "group_label": { "type": [ "string", "null" ], "description": "Gruppen-Override (`null` → Projektname als Default-Gruppe) — für den Editor." }, "label": { "type": "string", "description": "Effektives öffentliches Label (Override oder Monitor-Name)." }, "monitor": { "type": "string", "description": "Monitor-public_id (`mon_…`)." }, "project": { "type": "string", "description": "Projektname des Monitors = Default-/Platzhalter-Gruppe." }, "show_sparkline": { "type": "boolean" }, "show_uptime_bars": { "type": "boolean" }, "show_uptime_chart": { "type": "boolean" }, "sort_order": { "type": "integer", "format": "int32" }, "uptime_window_days": { "type": "integer", "format": "int32", "description": "Uptime/Historie-Fenster in Tagen (7|14|30|90|180|365)." } } }, "StatusPageMonitorInput": { "type": "object", "required": [ "monitor" ], "properties": { "display_name": { "type": [ "string", "null" ] }, "group_label": { "type": [ "string", "null" ], "description": "Gruppen-Override (leer/null → Projektname als Default-Gruppe)." }, "monitor": { "type": "string", "description": "Monitor-public_id (`mon_…`)." }, "show_sparkline": { "type": "boolean" }, "show_uptime_bars": { "type": "boolean" }, "show_uptime_chart": { "type": "boolean" }, "uptime_window_days": { "type": "integer", "format": "int32", "description": "7|14|30|90|180|365 (sonst → 90)." } } }, "StatusPageViewerDto": { "type": "object", "required": [ "id", "username", "email", "created_at_unix" ], "properties": { "created_at_unix": { "type": "integer", "format": "int64" }, "email": { "type": "string" }, "id": { "type": "string", "description": "public_id (`spv_…`)." }, "last_login_at_unix": { "type": [ "integer", "null" ], "format": "int64", "description": "Letzter erfolgreicher Login (Unix-Sekunden), `null` falls noch nie." }, "username": { "type": "string" } } }, "SubscribeRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string" } } }, "UpdateMonitorRequest": { "type": "object", "properties": { "alarm_gate": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AlarmGateDto", "description": "Abhaengige Alarme. Weggelassen = unveraendert, `null` = Regel entfernen." } ] }, "config": {}, "enabled": { "type": [ "boolean", "null" ] }, "interval_seconds": { "type": [ "integer", "null" ], "format": "int32" }, "name": { "type": [ "string", "null" ] }, "policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MonitorPolicyDto", "description": "Confirmation-Policy (Alarmprofil oder Inline). Weggelassen = unverändert." } ] }, "regions": { "type": [ "array", "null" ], "items": { "type": "string" } }, "type": { "type": [ "string", "null" ] } } }, "UpdateRoleRequest": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string" } } }, "UpdateStatusPageRequest": { "type": "object", "required": [ "name", "public_viewable", "enabled" ], "properties": { "access_mode": { "type": [ "string", "null" ], "description": "Zugriffsmodus (neuer, expliziter Weg): \"draft\" | \"public\" | \"shared_password\"\n| \"viewer_login\". Wenn gesetzt, hat er Vorrang vor den Legacy-Flags\n`public_viewable`/`password_protected` und ist die EINE Quelle der Wahrheit\nfür genau ein Gate." }, "collapsed_groups": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Gruppen-Namen, die standardmäßig eingeklappt dargestellt werden; fehlt das\nFeld, bleibt die bisherige Liste erhalten." }, "description": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "header_nav": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/NavLink" }, "description": "Header-Navigation; fehlt sie, bleibt die bisherige erhalten." }, "headline": { "type": [ "string", "null" ] }, "hide_datargo_brand": { "type": [ "boolean", "null" ], "description": "Perstat-Branding der Seite ausblenden (Seite + Abo-Mails). Fehlt das Feld,\nbleibt der bisherige Wert. Tarif-Feature: ohne `monitor.white_label` lehnt\nder Server das EINSCHALTEN mit 402 ab (Ausschalten geht immer)." }, "name": { "type": "string" }, "password_protected": { "type": "boolean", "description": "Seite als privat (passwortgeschützt = Viewer-Login) schalten. Legacy-Fallback,\nwenn `access_mode` fehlt. Tarif-Feature: ohne `monitor.private_status_pages`\nlehnt der Server das Einschalten mit 403 ab." }, "public_viewable": { "type": "boolean" }, "slug": { "type": [ "string", "null" ], "description": "Optionaler neuer Subdomain-Slug. Wird serverseitig normalisiert (slugify);\nfehlt er oder ist leer, bleibt der bisherige Slug erhalten." } } }, "UpdateWebhookTargetRequest": { "type": "object", "properties": { "active": { "type": [ "boolean", "null" ] }, "credential": { "type": [ "string", "null" ], "description": "Ersetzt den Anbieter-Schlüssel (PagerDuty/Opsgenie), z. B. nachdem er\ndort rotiert wurde. Für den generischen Webhook gibt es stattdessen\n`rotate-secret` (server-erzeugtes Signatur-Secret)." }, "events": { "type": [ "array", "null" ], "items": { "type": "string" } }, "name": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ], "description": "Wechselt die Anbieter-Region (`global` | `eu`) und damit den Endpunkt." }, "url": { "type": [ "string", "null" ], "description": "Nur für Arten mit kundeneigener Adresse." } } }, "VantagePointDto": { "type": "object", "description": "Aktiver Vantage-Point für die „Geprüft aus\"-Transparenz auf der öffentlichen\nStatusseite (ADR-0010). Trägt NUR den Kontinent-Key — Produkt-Entscheid\n2026-06-24: keine PoP-/Städtenamen mehr im Frontend, „nur Region (=Kontinent)\".\nClients lokalisieren über `region.`.", "required": [ "continent" ], "properties": { "continent": { "type": "string" } } }, "WebhookSecretDto": { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": "string", "description": "Neues volles Signatur-Secret, NUR in dieser Antwort." } } }, "WebhookTargetCreatedDto": { "type": "object", "required": [ "target" ], "properties": { "secret": { "type": [ "string", "null" ], "description": "Volles Signatur-Secret, NUR in dieser Antwort und NUR bei `webhook`.\nAnbieter-Schlüssel erscheinen hier nicht: die kennt der Kunde bereits." }, "target": { "$ref": "#/components/schemas/WebhookTargetDto" } } }, "WebhookTargetDto": { "type": "object", "required": [ "id", "name", "kind", "url", "events", "active", "created_at_unix" ], "properties": { "active": { "type": "boolean" }, "created_at_unix": { "type": "integer", "format": "int64" }, "events": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string", "description": "public_id (`wht_…`)." }, "kind": { "type": "string", "description": "Benannte Art: `slack` | `teams` | `discord` | `google_chat` |\n`pagerduty` | `opsgenie` | `webhook`." }, "last_delivery_at_unix": { "type": [ "integer", "null" ], "format": "int64" }, "last_delivery_ok": { "type": [ "boolean", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "region": { "type": [ "string", "null" ], "description": "Anbieter-Region bei `pagerduty`/`opsgenie` (`global` | `eu`), sonst\n`null`. Wird aus dem gespeicherten Endpunkt zurückgewonnen." }, "secret_hint": { "type": [ "string", "null" ], "description": "Maskierter Hinweis auf das gespeicherte Geheimnis (Signatur-Secret beim\ngenerischen Webhook, Anbieter-Schlüssel bei PagerDuty/Opsgenie). Das\nvolle Signatur-Secret gibt es genau EINMAL beim Anlegen bzw. der\nRotation; einen Anbieter-Schlüssel gibt die API NIE zurück." }, "url": { "type": "string" } } }, "WebhookTestResultDto": { "type": "object", "required": [ "ok" ], "properties": { "error": { "type": [ "string", "null" ] }, "ok": { "type": "boolean" } } } }, "securitySchemes": { "backofficeBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "pstsvc_ opaque service token" }, "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque session token" } } } }