{ "openapi": "3.1.2", "info": { "title": "Spectate API", "version": "1.0.0", "description": "Manage your Spectate team from code: monitors, hosts, domains, projects, alerting, on-call, incidents and status pages. This API backs the official SDKs and the Terraform provider; everything they do, you can do with plain HTTP.\n\n## Authentication\n\nEvery request sends a **team API token** as a bearer token:\n\n```http\nGET /v1/token HTTP/1.1\nHost: api.spectate.net\nAuthorization: Bearer spct_\u2026\n```\n\nOwners and managers create tokens in the dashboard under **Team \u2192 API tokens**. A token:\n\n- belongs to the team, not to the member who created it, and keeps working when that member leaves;\n- can only do what its **abilities** allow, for example `monitors:read` or `incidents:write`. Each endpoint lists the ability it requires. There is no wildcard: a token never gains an ability it wasn't created with;\n- is shown once. Spectate stores only a hash of it; lost tokens can't be recovered, only regenerated or revoked;\n- may expire. Revoked and expired tokens stop working immediately.\n\nTokens look like `spct_` followed by 46 letters and digits, the last 6 of which are a checksum, so secret scanners can recognise them. Call `GET /v1/token` to check a token and see its abilities.\n\n## Requests and responses\n\n- Send and expect JSON. Request bodies are `application/json`; responses are always JSON, also for errors.\n- IDs are UUIDs. Timestamps are ISO 8601 in UTC, for example `2026-10-25T14:03:00+00:00`.\n- `PATCH` changes only the fields you send. Fields you leave out keep their value; send `null` to clear a nullable field.\n- Secrets you send (passwords, webhook secrets) are never returned.\n\n## Pagination\n\nList endpoints are paginated with `page` (from 1) and `per_page` (1\u2013100, default 25). The response has the items in `data`, plus `current_page`, `last_page`, `per_page`, `total`, `from`, `to` and the URLs of the neighbouring pages. Filters use `filter[name]=value`; sorting uses `sort=field` (ascending) or `sort=-field` (descending).\n\n## Errors\n\nEvery error has the same shape:\n\n```json\n{\n \"error\": {\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Monitor not found.\"\n }\n}\n```\n\nBranch on `error.code`, which is stable; `error.message` is for people and may change. Some codes add `error.details`. Validation errors (`422`, `VALIDATION_FAILED`) list the invalid fields in `error.details.errors`.\n\n| Status | Meaning |\n| --- | --- |\n| `400` | The query is malformed (`INVALID_QUERY`), for example an unknown filter or sort. |\n| `401` | No token, or the token is invalid, revoked or expired. |\n| `403` | The token lacks an ability (`FORBIDDEN`), the plan doesn't allow it (`PLAN_LIMIT_REACHED`, `PLAN_FEATURE_UNAVAILABLE`), or the team is being deleted or suspended. |\n| `404` | No such resource in this team (`RESOURCE_NOT_FOUND`) or no such endpoint (`NOT_FOUND`). |\n| `409` | The request conflicts with the current state, for example enabling monitoring on a paused team. |\n| `422` | The request body is invalid (`VALIDATION_FAILED`). |\n| `429` | Rate limited (`RATE_LIMITED`); see below. |\n| `5xx` | Something went wrong on our side (`INTERNAL_ERROR`). Retry with backoff. |\n\n## Rate limits\n\nEach token may make **300 requests a minute**, of which **60 may change something** (`POST`, `PUT`, `PATCH`, `DELETE`). Responses carry `X-RateLimit-Limit` and `X-RateLimit-Remaining`; when you're over, the API answers `429` with a `Retry-After` header in seconds.\n\n## Versioning\n\nThis is version 1, under `/v1`. Within it, changes are additive only: new endpoints, new optional request fields, new response fields and new enum values. Treat unknown fields and enum values as possible. Anything that would break a client gets a new version, announced well before the old one is retired.\n" }, "servers": [ { "url": "https://api.spectate.net/v1", "description": "Production" } ], "tags": [ { "name": "API tokens", "description": "Check the token you authenticate with. Tokens themselves are created, regenerated and revoked in the dashboard (Team \u2192 API tokens) by owners and managers, never through the API." }, { "name": "Monitors", "description": "Uptime monitors check a URL, host, port or DNS name from Spectate's regions every interval, and raise alerts when it goes down, gets slow or its certificate is about to expire. Monitors and hosts together count against the plan's resource limit." }, { "name": "Hosts", "description": "Servers with the Spectate agent, which reports CPU, memory, disk and network metrics every minute. Hosts register themselves when the agent is installed with an install token; the API reads, renames, assigns and deletes them. Hosts and monitors together count against the plan's resource limit." }, { "name": "Host install tokens", "description": "Tokens the agent's installer uses to register servers as hosts of the team. One token can register a whole fleet until it expires after 7 days or is revoked; hosts that registered keep reporting either way." }, { "name": "Metric conditions", "description": "Alert rules for host metrics, such as \"disk usage above 90% for 10 minutes\". A condition applies to the hosts it names and to every host of the projects it names; when it holds for its duration, it raises an alert with its severity on the host." }, { "name": "Domains", "description": "Domain registrations Spectate watches at their registry (RDAP or WHOIS): it alerts before a domain expires and, optionally, when its registrar, nameservers or DNSSEC keys change. The plan limits the number of domains." }, { "name": "Projects", "description": "Projects group monitors and hosts, for example per product or environment, and give them shared escalation paths. Every team has a default project that new monitors and hosts join when no project is given." }, { "name": "Channels", "description": "Where alerts are delivered: email, Slack, Discord, Microsoft Teams, Telegram, webhooks, Pushover, SMS and voice calls. Escalation paths send to channels. A channel that keeps failing is turned off automatically; a successful test turns it back on." }, { "name": "Escalation paths", "description": "What happens when an alert fires: notify channels, page whoever is on call, declare an incident, wait, or branch on severity, source, labels or working hours, step by step until someone acknowledges the alert. Paths are trees: a `branch` step ends its list of steps and continues in its `then` and `else` steps. The dashboard shows the same paths in its flow editor." }, { "name": "Alert sources", "description": "External tools that fire and resolve alerts in Spectate: Prometheus Alertmanager, Grafana, Sentry, email, or your own scripts through a webhook. Each source has its own secret URL (and email address); its alerts follow its escalation paths." }, { "name": "Alerts", "description": "Problems Spectate or an alert source detected. An alert escalates along its escalation path until someone acknowledges it, and resolves on its own when the problem is over, or when someone resolves it by hand. Resolved alerts can be deleted. Alerts can lead to incidents." }, { "name": "On-call", "description": "Who gets paged when an escalation path's `notify_on_call` step runs. A schedule has rotation layers, where members take turns, and overrides, where someone covers for a while. Overrides win over every layer; where layers overlap, the top one wins. On-call is part of the Team plan and up." }, { "name": "Incidents", "description": "Problems that affect customers, worked on by the team: declare one, post updates as you learn more, assign a commander and a communications lead, resolve it and write the postmortem. Changes show in the incident's Slack channel and timeline, named after the API token that made them. Publish to status pages with `publishIncidentStatusPageUpdate`." }, { "name": "Status pages", "description": "Public pages that show the status of your components, your incidents and scheduled maintenance, on `.spectate.page` or your own domain. Visitors can subscribe to updates by email and report problems. The plan limits the number of pages; private pages, password protection and custom domains depend on the plan too. Logos and the favicon are uploaded in the dashboard." }, { "name": "Status page components", "description": "The parts of your service a status page shows, such as \"API\" or \"Dashboard\", optionally in groups. A component's status is derived: the worst ongoing impact of an unresolved incident, then maintenance, else operational. A component can follow a monitor for its uptime history, and with monitor automation the monitor's downtime opens an incident on the page." }, { "name": "Scheduled maintenance", "description": "Planned maintenance announced on a status page. While it is in progress, its components show as under maintenance. An automatic maintenance starts and completes on schedule by itself; a manual one changes when you set its status. Subscribers are emailed when it is scheduled, starts and completes." }, { "name": "Status page incidents", "description": "Incidents as visitors of a status page read them, with their updates. How an incident affects components is a timeline of impact periods, which drives each component's status and uptime history. Publishing an update sets the impacts as of then; you can also edit the periods directly. Monitor automation opens and resolves incidents for components that follow a monitor, until someone takes over by posting an update. The team's own incidents publish here with `publishIncidentStatusPageUpdate`." }, { "name": "Status page subscribers", "description": "People who subscribed to a status page's updates by email, from the page itself. A subscription is confirmed by double opt-in; only confirmed subscribers are emailed. Subscribers can't be added through the API." }, { "name": "Status page issue reports", "description": "Problems visitors reported from a status page, when the page has issue reports on. Reports above the page's threshold can show a notice on the page and fire an alert." }, { "name": "Team", "description": "The team the API token belongs to: its name, time zone, plan and whether monitoring runs. Deleting the team and changing billing happen in the dashboard." }, { "name": "Members", "description": "The people in the team and their roles. Members join by accepting an invite. Use member IDs in on-call rotations and incident roles." }, { "name": "Invites", "description": "Invites to join the team, sent by email. The invitee accepts in the dashboard, signed in with that address, and gets the invite's role. Invites expire after 7 days. Pending invites count towards the plan's member limit." }, { "name": "Billing", "description": "The team's plan, subscription, notification credits and how much of the plan's limits it uses. Read only: subscriptions and credit packs are bought and changed in the dashboard. Needs `billing:read`, which only owners and billing members can grant." } ], "security": [ { "TeamApiToken": [] } ], "paths": { "/token": { "get": { "operationId": "getApiToken", "description": "Returns the token that authenticated this request: its name, abilities, team and expiry.\nAny valid token may call it, whatever its abilities, so SDKs and the Terraform provider use\nit to check credentials before doing anything else. Revoked and expired tokens get `401`.", "summary": "Get the current API token", "tags": [ "API tokens" ], "responses": { "200": { "description": "The token that authenticated the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiToken" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/monitors": { "get": { "operationId": "listMonitors", "description": "Returns the team's monitors, newest first unless you sort. Filters combine with AND.", "summary": "List monitors", "tags": [ "Monitors" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Monitors per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 }, { "name": "filter[state]", "in": "query", "description": "Only monitors in this state.", "schema": { "$ref": "#/components/schemas/MonitorState" }, "example": "down" }, { "name": "filter[uptime_status]", "in": "query", "description": "Only monitors with this uptime status, whether paused or not.", "schema": { "$ref": "#/components/schemas/UptimeStatus" }, "example": "up" }, { "name": "filter[protocol]", "in": "query", "description": "Only monitors of this protocol.", "schema": { "$ref": "#/components/schemas/MonitorProtocol" }, "example": "https" }, { "name": "filter[enabled]", "in": "query", "description": "Only running (`true`) or paused (`false`) monitors.", "schema": { "type": "boolean" }, "example": true }, { "name": "filter[project_id]", "in": "query", "description": "Only monitors of this project.", "schema": { "type": "string", "format": "uuid" } }, { "name": "filter[search]", "in": "query", "description": "Case-insensitive text in the label, target, protocol or region.", "schema": { "type": "string" }, "example": "example.com" }, { "name": "sort", "in": "query", "description": "Sort by `label`, `created_at`, `last_checked_at` or `state` (down, pending, up, paused, then label). Prefix `-` for descending. Default `-created_at`.", "schema": { "type": "string" }, "example": "-created_at", "explode": false } ], "responses": { "200": { "description": "Paginated set of `Monitor`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Monitor" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "post": { "operationId": "createMonitor", "description": "The monitor starts checking at once unless `enabled` is `false`. Without `project_id` it\njoins the team's default project. Monitors and hosts together are limited by the plan\n(`403` `PLAN_LIMIT_REACHED`), and so is the shortest `interval` (`422`). Targets on private\nor reserved addresses are refused (`422`).", "summary": "Create a monitor", "tags": [ "Monitors" ], "requestBody": { "description": "`CreateMonitor`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMonitor" } } } }, "responses": { "201": { "description": "The new monitor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`PLAN_LIMIT_REACHED`: the plan doesn't allow another one; `details.feature` names the limit.\n\n`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/monitors/{monitor}": { "get": { "operationId": "getMonitor", "description": "Returns the monitor's settings and its latest results: uptime status, response time,\ncertificate and uptime percentages.", "summary": "Get a monitor", "tags": [ "Monitors" ], "parameters": [ { "name": "monitor", "in": "path", "required": true, "description": "Monitor ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The monitor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "patch": { "operationId": "updateMonitor", "description": "Changes only the fields you send; `advanced_settings` is merged into the current settings.\nChanging `protocol` requires a `uri` in the new protocol's format. The next check uses the\nnew settings.", "summary": "Update a monitor", "tags": [ "Monitors" ], "parameters": [ { "name": "monitor", "in": "path", "required": true, "description": "Monitor ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`UpdateMonitor`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMonitor" } } } }, "responses": { "200": { "description": "The updated monitor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "deleteMonitor", "description": "Its checks stop at once and it no longer appears in the API or the dashboard. Seven days\nlater the monitor is deleted permanently with all its data: check history, alerts and\nfailure snapshots. Until then support can restore it on request. Incidents stay, and status\npage components that showed the monitor keep their place without it. Deleting the same\nmonitor again returns `404`.", "summary": "Delete a monitor", "tags": [ "Monitors" ], "parameters": [ { "name": "monitor", "in": "path", "required": true, "description": "Monitor ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/monitors/{monitor}/pause": { "post": { "operationId": "pauseMonitor", "description": "Stops its checks; ongoing alerts stay as they are. Pausing a paused monitor changes\nnothing.", "summary": "Pause a monitor", "tags": [ "Monitors" ], "parameters": [ { "name": "monitor", "in": "path", "required": true, "description": "Monitor ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The paused monitor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`PLAN_LIMIT_REACHED`: the plan doesn't allow another one; `details.feature` names the limit.\n\n`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "`TEAM_MONITORING_PAUSED`: the team's monitoring is paused (no paid plan), so nothing can be resumed until it subscribes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/monitors/{monitor}/resume": { "post": { "operationId": "resumeMonitor", "description": "Starts its checks again, also when the system paused it for the plan limit, if the plan\nhas room now (`403` `PLAN_LIMIT_REACHED` otherwise). While the team's monitoring is paused\n(no paid plan) nothing can be resumed (`409` `TEAM_MONITORING_PAUSED`). Resuming a running\nmonitor changes nothing.", "summary": "Resume a monitor", "tags": [ "Monitors" ], "parameters": [ { "name": "monitor", "in": "path", "required": true, "description": "Monitor ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The running monitor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Monitor" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`PLAN_LIMIT_REACHED`: the plan doesn't allow another one; `details.feature` names the limit.\n\n`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "`TEAM_MONITORING_PAUSED`: the team's monitoring is paused (no paid plan), so nothing can be resumed until it subscribes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/hosts": { "get": { "operationId": "listHosts", "description": "Returns the team's hosts, newest first unless you sort.", "summary": "List hosts", "tags": [ "Hosts" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Hosts per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 }, { "name": "filter[state]", "in": "query", "description": "Only hosts in this state.", "schema": { "$ref": "#/components/schemas/HostState" }, "example": "stale" }, { "name": "filter[project_id]", "in": "query", "description": "Only hosts of this project.", "schema": { "type": "string", "format": "uuid" } }, { "name": "filter[search]", "in": "query", "description": "Case-insensitive text in the label, host info (hostname, platform, architecture) or agent version.", "schema": { "type": "string" }, "example": "web" }, { "name": "sort", "in": "query", "description": "Sort by `label`, `last_seen_at` or `created_at`. Prefix `-` for descending. Default `-created_at`.", "schema": { "type": "string" }, "example": "label", "explode": false } ], "responses": { "200": { "description": "Paginated set of `Host`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Host" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/hosts/{host}": { "get": { "operationId": "getHost", "description": "Returns the host with what its agent reports about the system. Metrics themselves are in the\ndashboard.", "summary": "Get a host", "tags": [ "Hosts" ], "parameters": [ { "name": "host", "in": "path", "required": true, "description": "Host ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The host.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Host" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "patch": { "operationId": "updateHost", "description": "Changes only the fields you send. The agent stops renaming a host once you set its label.", "summary": "Update a host", "tags": [ "Hosts" ], "parameters": [ { "name": "host", "in": "path", "required": true, "description": "Host ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`UpdateHost`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateHost" } } } }, "responses": { "200": { "description": "The updated host.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Host" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "deleteHost", "description": "The host disappears from the API and the dashboard, and data its agent still sends is\nrefused (the agent stops itself). Uninstall the agent on the server too. Seven days later\nthe host is deleted permanently with all its data: metrics, alerts and metric condition\nlinks. Until then support can restore it on request. Deleting the same host again returns\n`404`.", "summary": "Delete a host", "tags": [ "Hosts" ], "parameters": [ { "name": "host", "in": "path", "required": true, "description": "Host ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/host-install-tokens": { "get": { "operationId": "listHostInstallTokens", "description": "Returns the tokens that can still register hosts, newest first. Expired tokens aren't listed.", "summary": "List install tokens", "tags": [ "Host install tokens" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Tokens per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "Paginated set of `HostInstallToken`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/HostInstallToken" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "post": { "operationId": "createHostInstallToken", "description": "The token is valid for 7 days. Give it to the agent's installer; Hosts \u2192 Add host in the\ndashboard shows the full command for each platform.", "summary": "Create an install token", "tags": [ "Host install tokens" ], "responses": { "201": { "description": "The new install token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HostInstallToken" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/host-install-tokens/{token}": { "delete": { "operationId": "deleteHostInstallToken", "description": "No new hosts can register with it. Hosts that registered with it keep reporting.", "summary": "Revoke an install token", "tags": [ "Host install tokens" ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "Install token ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/metric-conditions": { "get": { "operationId": "listMetricConditions", "description": "Returns the team's metric conditions, oldest first.", "summary": "List metric conditions", "tags": [ "Metric conditions" ], "parameters": [ { "name": "filter[host_id]", "in": "query", "description": "Only conditions attached to this host directly (not through its project).", "schema": { "type": "string", "format": "uuid" } }, { "name": "filter[project_id]", "in": "query", "description": "Only conditions attached to this project.", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Conditions per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "Paginated set of `MetricCondition`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MetricCondition" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "post": { "operationId": "createMetricCondition", "description": "Hosts and projects must belong to the team (`422` otherwise). The condition is checked on\nthe next report of each host it applies to.", "summary": "Create a metric condition", "tags": [ "Metric conditions" ], "requestBody": { "description": "`CreateMetricCondition`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMetricCondition" } } } }, "responses": { "201": { "description": "The new metric condition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricCondition" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/metric-conditions/{condition}": { "get": { "operationId": "getMetricCondition", "description": "Returns the condition with the hosts and projects it applies to.", "summary": "Get a metric condition", "tags": [ "Metric conditions" ], "parameters": [ { "name": "condition", "in": "path", "required": true, "description": "Metric condition ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The metric condition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricCondition" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "deleteMetricCondition", "description": "It's no longer checked from the hosts' next report.", "summary": "Delete a metric condition", "tags": [ "Metric conditions" ], "parameters": [ { "name": "condition", "in": "path", "required": true, "description": "Metric condition ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/domains": { "get": { "operationId": "listDomains", "description": "Returns the team's monitored domains, newest first unless you sort.", "summary": "List domains", "tags": [ "Domains" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Domains per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 }, { "name": "filter[view]", "in": "query", "description": "Only domains in this view.", "schema": { "$ref": "#/components/schemas/DomainView" }, "example": "attention" }, { "name": "filter[project_id]", "in": "query", "description": "Only domains of this project.", "schema": { "type": "string", "format": "uuid" } }, { "name": "filter[search]", "in": "query", "description": "Case-insensitive text in the name, registrar or nameservers.", "schema": { "type": "string" }, "example": "example" }, { "name": "sort", "in": "query", "description": "Sort by `name`, `expires_at` (unknown expiry last) or `created_at`. Prefix `-` for descending. Default `-created_at`.", "schema": { "type": "string" }, "example": "expires_at", "explode": false } ], "responses": { "200": { "description": "Paginated set of `Domain`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "post": { "operationId": "createDomain", "description": "Starts monitoring it and looks it up at its registry right away; the registry fields fill\nin within a minute. Without `project_id` it joins the team's default project. The plan\nlimits the number of domains (`403` `PLAN_LIMIT_REACHED`).", "summary": "Add a domain", "tags": [ "Domains" ], "requestBody": { "description": "`CreateDomain`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDomain" } } } }, "responses": { "201": { "description": "The new domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`PLAN_LIMIT_REACHED`: the plan doesn't allow another one; `details.feature` names the limit.\n\n`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/domains/{domain}": { "get": { "operationId": "getDomain", "description": "Returns the domain with what its registry reported at the last check.", "summary": "Get a domain", "tags": [ "Domains" ], "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "patch": { "operationId": "updateDomain", "description": "Changes only the fields you send. A new `name` forgets the old registration data and is\nlooked up at once. Resuming (`enabled: true`) goes through the plan's domain limit.", "summary": "Update a domain", "tags": [ "Domains" ], "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`UpdateDomain`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDomain" } } } }, "responses": { "200": { "description": "The updated domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`PLAN_LIMIT_REACHED`: the plan doesn't allow another one; `details.feature` names the limit.\n\n`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "`TEAM_MONITORING_PAUSED`: the team's monitoring is paused (no paid plan), so nothing can be resumed until it subscribes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "deleteDomain", "description": "Monitoring stops and the domain no longer appears in the API or the dashboard. Seven days\nlater the domain is deleted permanently with all its data, alerts included. Until then\nsupport can restore it on request. Nothing changes at the registrar. Deleting the same\ndomain again returns `404`.", "summary": "Delete a domain", "tags": [ "Domains" ], "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Domain ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/projects": { "get": { "operationId": "listProjects", "description": "Returns the team's projects, the default project first, then by name.", "summary": "List projects", "tags": [ "Projects" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Projects per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "Paginated set of `Project`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "post": { "operationId": "createProject", "description": "Plans limit the number of projects: over the limit the request fails with `403`\n`PLAN_LIMIT_REACHED`. Escalation paths must belong to the team (`422` otherwise).", "summary": "Create a project", "tags": [ "Projects" ], "requestBody": { "description": "`CreateProject`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProject" } } } }, "responses": { "201": { "description": "The new project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`PLAN_LIMIT_REACHED`: the plan doesn't allow another one; `details.feature` names the limit.\n\n`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/projects/{project}": { "get": { "operationId": "getProject", "description": "Returns the project with the escalation paths its monitors and hosts use by default.", "summary": "Get a project", "tags": [ "Projects" ], "parameters": [ { "name": "project", "in": "path", "required": true, "description": "Project ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "patch": { "operationId": "updateProject", "description": "Changes only the fields you send. `escalation_path_ids` replaces the project's paths;\nsend `[]` to remove them all.", "summary": "Update a project", "tags": [ "Projects" ], "parameters": [ { "name": "project", "in": "path", "required": true, "description": "Project ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`UpdateProject`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProject" } } } }, "responses": { "200": { "description": "The updated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "deleteProject", "description": "Its monitors and hosts are kept, without a project; they follow the team's default\nescalation path until you give them another. The default project can't be deleted\n(`409` `DEFAULT_PROJECT`).", "summary": "Delete a project", "tags": [ "Projects" ], "parameters": [ { "name": "project", "in": "path", "required": true, "description": "Project ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "`DEFAULT_PROJECT`: the team's default project can't be deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/channels": { "get": { "operationId": "listChannels", "description": "Returns the team's channels, by name.", "summary": "List channels", "tags": [ "Channels" ], "parameters": [ { "name": "filter[type]", "in": "query", "description": "Only channels of this type.", "schema": { "$ref": "#/components/schemas/ChannelType" }, "example": "email" }, { "name": "filter[enabled]", "in": "query", "description": "Only enabled (`true`) or disabled (`false`) channels.", "schema": { "type": "boolean" }, "example": true }, { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Channels per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "Paginated set of `Channel`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "post": { "operationId": "createChannel", "description": "Send `type` and the settings object of that type, for example `type: \"email\"` with\n`email: {address}`. Webhook URLs must be public addresses. Slack channels post through a\nSlack workspace connected under Integrations in the dashboard, Telegram channels are\nconnected there too. Create channels before the escalation paths that use them.", "summary": "Create a channel", "tags": [ "Channels" ], "requestBody": { "description": "`CreateChannel`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChannel" } } } }, "responses": { "201": { "description": "The new channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/channels/{channel}": { "get": { "operationId": "getChannel", "description": "Returns the channel with its delivery health. Secrets in its settings are never returned.", "summary": "Get a channel", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "description": "Channel ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "patch": { "operationId": "updateChannel", "description": "Changes only the fields you send. The settings object of the channel's type replaces the\ncurrent settings, including secrets: send them again. Other types' objects are refused\n(`422`); create a new channel to change the type. Enabling clears an automatic disable.", "summary": "Update a channel", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "description": "Channel ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`UpdateChannel`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChannel" } } } }, "responses": { "200": { "description": "The updated channel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Channel" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "deleteChannel", "description": "Escalation steps that sent to it stay, and are skipped until you point them at another\nchannel. Notifications already sent aren't affected.", "summary": "Delete a channel", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "description": "Channel ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/channels/{channel}/test": { "post": { "operationId": "testChannel", "description": "Delivers a test through the channel right away and returns when it was accepted. A\nsuccessful test clears the failure count and, with `enable`, turns a disabled channel back\non. A failed test (`422` `CHANNEL_TEST_FAILED`) doesn't count towards turning it off. SMS\nand voice tests use the team's notification credits (`422` `NOTIFICATION_CREDITS_EXHAUSTED`\nwithout them). Limited to 10 tests a minute per token.", "summary": "Send a test notification", "tags": [ "Channels" ], "parameters": [ { "name": "channel", "in": "path", "required": true, "description": "Channel ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`TestChannel`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestChannel" } } } }, "responses": { "200": { "description": "The test was delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelTestResult" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`CHANNEL_TEST_FAILED`: the test couldn't be delivered; the message has the delivery error, `details.permanent` whether the settings are wrong.\n\n`NOTIFICATION_CREDITS_EXHAUSTED`: the team has no SMS and voice credits left; buy more under Billing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/escalation-paths": { "get": { "operationId": "listEscalationPaths", "description": "Returns the team's paths with their steps, the default path first, then by name.", "summary": "List escalation paths", "tags": [ "Escalation paths" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Paths per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "Paginated set of `EscalationPath`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EscalationPath" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "post": { "operationId": "createEscalationPath", "description": "Channels and schedules must belong to the team; a `branch` ends its list of steps (`422`\nwith the step's position, for example `steps.1.then.0.channel_id`). Paging the person on\ncall is part of the Team plan and up, and so are paths besides the default one (`403`\n`PLAN_LIMIT_REACHED`).", "summary": "Create an escalation path", "tags": [ "Escalation paths" ], "requestBody": { "description": "`CreateEscalationPath`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEscalationPath" } } } }, "responses": { "201": { "description": "The new escalation path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EscalationPath" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`PLAN_LIMIT_REACHED`: the plan doesn't allow another one; `details.feature` names the limit.\n\n`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/escalation-paths/{path}": { "get": { "operationId": "getEscalationPath", "description": "Returns the path with its steps as a tree and the problems that keep it from delivering.", "summary": "Get an escalation path", "tags": [ "Escalation paths" ], "parameters": [ { "name": "path", "in": "path", "required": true, "description": "Escalation path ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The escalation path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EscalationPath" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "patch": { "operationId": "updateEscalationPath", "description": "Changes only the fields you send; `steps` replaces all steps. Alerts that are already\nescalating keep the steps they started with. Making a path the default takes that from the\ncurrent default path.", "summary": "Update an escalation path", "tags": [ "Escalation paths" ], "parameters": [ { "name": "path", "in": "path", "required": true, "description": "Escalation path ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`UpdateEscalationPath`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEscalationPath" } } } }, "responses": { "200": { "description": "The updated escalation path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EscalationPath" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "deleteEscalationPath", "description": "Monitors, hosts, domains, projects and alert sources that used it fall back to their\nproject's paths or the team's default path. Alerts that are escalating on it stop.", "summary": "Delete an escalation path", "tags": [ "Escalation paths" ], "parameters": [ { "name": "path", "in": "path", "required": true, "description": "Escalation path ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/alert-sources": { "get": { "operationId": "listAlertSources", "description": "Returns the team's alert sources, by name.", "summary": "List alert sources", "tags": [ "Alert sources" ], "parameters": [ { "name": "filter[type]", "in": "query", "description": "Only sources of this tool.", "schema": { "$ref": "#/components/schemas/AlertSourceProvider" }, "example": "alertmanager" }, { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Sources per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "Paginated set of `AlertSource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AlertSource" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "post": { "operationId": "createAlertSource", "description": "Returns the source with its `webhook_url` (and `email_address` for `email`) to set up in the\ntool. Email sources resolve alerts after an hour without a repeat unless\n`auto_resolve_minutes` says otherwise: mail has no \"resolved\".", "summary": "Create an alert source", "tags": [ "Alert sources" ], "requestBody": { "description": "`CreateAlertSource`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAlertSource" } } } }, "responses": { "201": { "description": "The new alert source.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertSource" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/alert-sources/{source}": { "get": { "operationId": "getAlertSource", "description": "Returns the source with its URL and how many of its alerts are firing.", "summary": "Get an alert source", "tags": [ "Alert sources" ], "parameters": [ { "name": "source", "in": "path", "required": true, "description": "Alert source ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The alert source.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertSource" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "patch": { "operationId": "updateAlertSource", "description": "Changes only the fields you send; `settings` merge into the current settings.", "summary": "Update an alert source", "tags": [ "Alert sources" ], "parameters": [ { "name": "source", "in": "path", "required": true, "description": "Alert source ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`UpdateAlertSource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAlertSource" } } } }, "responses": { "200": { "description": "The updated alert source.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertSource" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "deleteAlertSource", "description": "Its firing alerts are resolved first; its URL and address stop working at once.", "summary": "Delete an alert source", "tags": [ "Alert sources" ], "parameters": [ { "name": "source", "in": "path", "required": true, "description": "Alert source ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/alert-sources/{source}/rotate-token": { "post": { "operationId": "rotateAlertSourceToken", "description": "Gives the source a new secret `webhook_url` (and `email_address`); the old ones stop working\nat once, so update the tool right after.", "summary": "Rotate the source's URL", "tags": [ "Alert sources" ], "parameters": [ { "name": "source", "in": "path", "required": true, "description": "Alert source ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The source with its new URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertSource" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/alert-sources/{source}/test": { "post": { "operationId": "testAlertSource", "description": "Fires an alert on the source that escalates like a real one (it notifies people) and\nresolves itself after a few minutes. Returns the event it made.", "summary": "Fire a test alert", "tags": [ "Alert sources" ], "parameters": [ { "name": "source", "in": "path", "required": true, "description": "Alert source ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The test event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertSourceEvent" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/alert-sources/{source}/events": { "get": { "operationId": "listAlertSourceEvents", "description": "Returns the requests the source received in the last 7 days, newest first, with what each\ndid. Use it to check that a tool reaches Spectate.", "summary": "List a source's events", "tags": [ "Alert sources" ], "parameters": [ { "name": "source", "in": "path", "required": true, "description": "Alert source ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Events per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "Paginated set of `AlertSourceEvent`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AlertSourceEvent" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/alerts": { "get": { "operationId": "listAlerts", "description": "Returns the team's alerts, most recently fired first unless you sort.", "summary": "List alerts", "tags": [ "Alerts" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Alerts per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 }, { "name": "filter[status]", "in": "query", "description": "Only firing or resolved alerts.", "schema": { "$ref": "#/components/schemas/AlertStatus" }, "example": "firing" }, { "name": "filter[severity]", "in": "query", "description": "Only alerts of this severity.", "schema": { "$ref": "#/components/schemas/Severity" }, "example": "critical" }, { "name": "filter[source_type]", "in": "query", "description": "Only alerts raised by this kind of check or integration.", "schema": { "$ref": "#/components/schemas/AlertSourceType" }, "example": "uptime" }, { "name": "filter[resource_id]", "in": "query", "description": "Only alerts about this resource (a monitor, host, domain, status page or alert source ID).", "schema": { "type": "string", "format": "uuid" } }, { "name": "filter[acknowledged]", "in": "query", "description": "Only acknowledged (`true`) or unacknowledged (`false`) alerts.", "schema": { "type": "boolean" }, "example": false }, { "name": "sort", "in": "query", "description": "Sort by `fired_at`, `resolved_at`, `severity` or `status`. Prefix `-` for descending. Default `-fired_at`.", "schema": { "type": "string" }, "example": "-fired_at", "explode": false } ], "responses": { "200": { "description": "Paginated set of `Alert`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Alert" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/alerts/{alert}": { "get": { "operationId": "getAlert", "description": "Returns the alert with the resource it's about and who acknowledged it.", "summary": "Get an alert", "tags": [ "Alerts" ], "parameters": [ { "name": "alert", "in": "path", "required": true, "description": "Alert ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The alert.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "deleteAlert", "description": "Deletes a resolved alert for good, with its escalation history. Incidents and status page\nincidents it led to stay, without the link to it; messages already posted in Slack or Telegram\nstay in their channels. A firing alert can't be deleted: resolve it first.", "summary": "Delete an alert", "tags": [ "Alerts" ], "parameters": [ { "name": "alert", "in": "path", "required": true, "description": "Alert ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "`ALERT_FIRING`: the alert is still firing; resolve it before deleting it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/alerts/{alert}/acknowledge": { "post": { "operationId": "acknowledgeAlert", "description": "Stops its escalation: nobody else is notified. The alert keeps firing until the problem is\nover. The dashboard, Slack and Telegram show it as acknowledged by the API token.\nAcknowledging an acknowledged or resolved alert changes nothing.", "summary": "Acknowledge an alert", "tags": [ "Alerts" ], "parameters": [ { "name": "alert", "in": "path", "required": true, "description": "Alert ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The acknowledged alert.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/alerts/{alert}/resolve": { "post": { "operationId": "resolveAlert", "description": "Ends the alert by hand, as if its problem were over: its escalation stops, the channels and\non-call members it notified hear that it resolved, Slack and Telegram show it as resolved by the\nAPI token, and status pages automated from an uptime alert show the monitor as recovered. Use\nit for false alarms, or for alerts whose source can't tell they're over.\n\nIf the problem is still there, the source fires a new alert at its next check (a monitor that\nis still down, a host metric still over its limit). Resolving a resolved alert changes nothing.", "summary": "Resolve an alert", "tags": [ "Alerts" ], "parameters": [ { "name": "alert", "in": "path", "required": true, "description": "Alert ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The resolved alert.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/on-call-schedules": { "get": { "operationId": "listOnCallSchedules", "description": "Returns the team's schedules, by name, each with who is on call now and the next handoff.", "summary": "List on-call schedules", "tags": [ "On-call" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Schedules per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "Paginated set of `OnCallSchedule`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OnCallSchedule" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "post": { "operationId": "createOnCallSchedule", "description": "The schedule starts empty: nobody is on call until you add a rotation layer. Needs a plan\nwith on-call (`403` `PLAN_FEATURE_UNAVAILABLE`).", "summary": "Create an on-call schedule", "tags": [ "On-call" ], "requestBody": { "description": "`CreateOnCallSchedule`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOnCallSchedule" } } } }, "responses": { "201": { "description": "The new schedule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnCallSchedule" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`PLAN_FEATURE_UNAVAILABLE`: the plan doesn't include this feature; `details.feature` names it.\n\n`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/on-call-schedules/{schedule}": { "get": { "operationId": "getOnCallSchedule", "description": "Returns the schedule with its rotation layers, upcoming overrides, who is on call now and\nthe escalation paths that page it.", "summary": "Get an on-call schedule", "tags": [ "On-call" ], "parameters": [ { "name": "schedule", "in": "path", "required": true, "description": "Schedule ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The schedule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnCallSchedule" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "patch": { "operationId": "updateOnCallSchedule", "description": "Changes only the fields you send.", "summary": "Update an on-call schedule", "tags": [ "On-call" ], "parameters": [ { "name": "schedule", "in": "path", "required": true, "description": "Schedule ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`UpdateOnCallSchedule`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOnCallSchedule" } } } }, "responses": { "200": { "description": "The updated schedule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnCallSchedule" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "deleteOnCallSchedule", "description": "Deletes its rotations and overrides. Escalation steps that paged it stay, and are skipped\nuntil you point them at another schedule.", "summary": "Delete an on-call schedule", "tags": [ "On-call" ], "parameters": [ { "name": "schedule", "in": "path", "required": true, "description": "Schedule ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/on-call-schedules/{schedule}/timeline": { "get": { "operationId": "getOnCallTimeline", "description": "Who is on call between `from` and `to` (default: now and 14 days later; at most 62 days):\neach layer's shifts, the overrides, and the result, which is who actually gets paged.", "summary": "Get a schedule's timeline", "tags": [ "On-call" ], "parameters": [ { "name": "schedule", "in": "path", "required": true, "description": "Schedule ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "description": "Start of the window, ISO 8601. Default now.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "description": "End of the window, ISO 8601, at most 62 days after `from`. Default 14 days after `from`.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "The timeline of the window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnCallTimeline" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/on-call-schedules/{schedule}/now": { "get": { "operationId": "getOnCallNow", "description": "Who is on call at `at` (default now). `shift` is `null` during a gap.", "summary": "Get who is on call", "tags": [ "On-call" ], "parameters": [ { "name": "schedule", "in": "path", "required": true, "description": "Schedule ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "at", "in": "query", "description": "The moment, ISO 8601. Default now.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Who is on call at that moment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnCallNow" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/on-call-schedules/{schedule}/rotations": { "post": { "operationId": "createOnCallRotation", "description": "New layers go below the existing ones unless `position` is given. Participants must be\nmembers of the team (`422`).", "summary": "Add a rotation layer", "tags": [ "On-call" ], "parameters": [ { "name": "schedule", "in": "path", "required": true, "description": "Schedule ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`CreateOnCallRotation`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOnCallRotation" } } } }, "responses": { "201": { "description": "The new rotation layer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnCallRotation" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/on-call-schedules/{schedule}/rotations/{rotation}": { "patch": { "operationId": "updateOnCallRotation", "description": "Changes only the fields you send; `participant_ids` replaces the members taking turns.", "summary": "Update a rotation layer", "tags": [ "On-call" ], "parameters": [ { "name": "schedule", "in": "path", "required": true, "description": "Schedule ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "rotation", "in": "path", "required": true, "description": "Rotation ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`UpdateOnCallRotation`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOnCallRotation" } } } }, "responses": { "200": { "description": "The updated rotation layer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnCallRotation" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "deleteOnCallRotation", "description": "The layers below move up.", "summary": "Delete a rotation layer", "tags": [ "On-call" ], "parameters": [ { "name": "schedule", "in": "path", "required": true, "description": "Schedule ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "rotation", "in": "path", "required": true, "description": "Rotation ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/on-call-schedules/{schedule}/overrides": { "post": { "operationId": "createOnCallOverride", "description": "Has a team member cover the schedule from `starts_at` to `ends_at`, at most 90 days.\nOverrides win over every layer; where overrides overlap, the newest wins.", "summary": "Add an override", "tags": [ "On-call" ], "parameters": [ { "name": "schedule", "in": "path", "required": true, "description": "Schedule ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`CreateOnCallOverride`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOnCallOverride" } } } }, "responses": { "201": { "description": "The new override.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnCallOverride" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/on-call-schedules/{schedule}/overrides/{override}": { "delete": { "operationId": "deleteOnCallOverride", "description": "The rotations decide again for its time.", "summary": "Delete an override", "tags": [ "On-call" ], "parameters": [ { "name": "schedule", "in": "path", "required": true, "description": "Schedule ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "override", "in": "path", "required": true, "description": "Override ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/incidents": { "get": { "operationId": "listIncidents", "description": "Returns the team's incidents, most recently started first unless you sort.", "summary": "List incidents", "tags": [ "Incidents" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Incidents per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 }, { "name": "filter[status]", "in": "query", "description": "Only incidents with this status.", "schema": { "$ref": "#/components/schemas/IncidentStatus" }, "example": "investigating" }, { "name": "filter[severity]", "in": "query", "description": "Only incidents of this severity.", "schema": { "$ref": "#/components/schemas/Severity" }, "example": "critical" }, { "name": "filter[title]", "in": "query", "description": "Case-insensitive text in the title.", "schema": { "type": "string" }, "example": "checkout" }, { "name": "sort", "in": "query", "description": "Sort by `started_at`, `created_at`, `severity`, `status` or `title`. Prefix `-` for descending. Default `-started_at`.", "schema": { "type": "string" }, "example": "-started_at", "explode": false } ], "responses": { "200": { "description": "Paginated set of `Incident`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "post": { "operationId": "createIncident", "description": "It starts `investigating`. With Slack connected it's announced there like an incident\ndeclared in the dashboard, with its own channel when the Slack settings say so.", "summary": "Declare an incident", "tags": [ "Incidents" ], "requestBody": { "description": "`CreateIncident`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIncident" } } } }, "responses": { "201": { "description": "The new incident.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/incidents/{incident}": { "get": { "operationId": "getIncident", "description": "Returns the incident with its roles and the alert that opened it.", "summary": "Get an incident", "tags": [ "Incidents" ], "parameters": [ { "name": "incident", "in": "path", "required": true, "description": "Incident ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The incident.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "patch": { "operationId": "updateIncident", "description": "Changes only the fields you send. Status and severity changes are announced like in the\ndashboard. To share what's known, post an update instead.", "summary": "Update an incident", "tags": [ "Incidents" ], "parameters": [ { "name": "incident", "in": "path", "required": true, "description": "Incident ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`UpdateIncident`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIncident" } } } }, "responses": { "200": { "description": "The updated incident.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "deleteIncident", "description": "Deletes it for good, open or resolved, with its updates, role assignments and postmortem.\nNothing else goes with it: the alert that opened it keeps firing or stays resolved, status\npage incidents published from it stay on their pages, and its Slack channel isn't archived.", "summary": "Delete an incident", "tags": [ "Incidents" ], "parameters": [ { "name": "incident", "in": "path", "required": true, "description": "Incident ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/incidents/{incident}/acknowledge": { "post": { "operationId": "acknowledgeIncident", "description": "Moves it to `identified` and stops the escalation of the alert that opened it.", "summary": "Acknowledge an incident", "tags": [ "Incidents" ], "parameters": [ { "name": "incident", "in": "path", "required": true, "description": "Incident ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The acknowledged incident.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/incidents/{incident}/resolve": { "post": { "operationId": "resolveIncident", "description": "Ends it, with an optional closing update. Its status page incidents stay as they are:\nresolve those with a status page update.", "summary": "Resolve an incident", "tags": [ "Incidents" ], "parameters": [ { "name": "incident", "in": "path", "required": true, "description": "Incident ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`ResolveIncident`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveIncident" } } } }, "responses": { "200": { "description": "The resolved incident.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/incidents/{incident}/updates": { "get": { "operationId": "listIncidentUpdates", "description": "Returns the updates, newest first.", "summary": "List an incident's updates", "tags": [ "Incidents" ], "parameters": [ { "name": "incident", "in": "path", "required": true, "description": "Incident ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Updates per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "Paginated set of `IncidentUpdate`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/IncidentUpdate" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "post": { "operationId": "createIncidentUpdate", "description": "Adds what's known now to the timeline, optionally with a new status, and shares it like an\nupdate from the dashboard.", "summary": "Post an incident update", "tags": [ "Incidents" ], "parameters": [ { "name": "incident", "in": "path", "required": true, "description": "Incident ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`CreateIncidentUpdate`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIncidentUpdate" } } } }, "responses": { "201": { "description": "The posted update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentUpdate" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/incidents/{incident}/timeline": { "get": { "operationId": "listIncidentTimeline", "description": "Everything that happened, newest first: declaring, updates, status and severity changes,\nroles, acknowledging and resolving, with who did it.", "summary": "Get an incident's timeline", "tags": [ "Incidents" ], "parameters": [ { "name": "incident", "in": "path", "required": true, "description": "Incident ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Entries per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "Paginated set of `IncidentTimelineEntry`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/IncidentTimelineEntry" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/incidents/{incident}/roles/{role}": { "put": { "operationId": "assignIncidentRole", "description": "Gives the role to a member of the team, replacing whoever had it.", "summary": "Assign an incident role", "tags": [ "Incidents" ], "parameters": [ { "name": "incident", "in": "path", "required": true, "description": "Incident ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "role", "in": "path", "required": true, "description": "The role.", "schema": { "$ref": "#/components/schemas/IncidentRole" } } ], "requestBody": { "description": "`AssignIncidentRole`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignIncidentRole" } } } }, "responses": { "200": { "description": "The incident with its roles.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "removeIncidentRole", "description": "Nobody has the role afterwards. Removing a role nobody has changes nothing.", "summary": "Remove an incident role", "tags": [ "Incidents" ], "parameters": [ { "name": "incident", "in": "path", "required": true, "description": "Incident ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "role", "in": "path", "required": true, "description": "The role.", "schema": { "$ref": "#/components/schemas/IncidentRole" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/incidents/{incident}/postmortem": { "get": { "operationId": "getIncidentPostmortem", "description": "`postmortem` is `null` until one is written.", "summary": "Get an incident's postmortem", "tags": [ "Incidents" ], "parameters": [ { "name": "incident", "in": "path", "required": true, "description": "Incident ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The postmortem, if any.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentPostmortemResult" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "put": { "operationId": "saveIncidentPostmortem", "description": "Creates the postmortem, or replaces its content.", "summary": "Write an incident's postmortem", "tags": [ "Incidents" ], "parameters": [ { "name": "incident", "in": "path", "required": true, "description": "Incident ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`SavePostmortem`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavePostmortem" } } } }, "responses": { "200": { "description": "The saved postmortem.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentPostmortem" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/incidents/{incident}/status-page-updates": { "post": { "operationId": "publishIncidentStatusPageUpdate", "description": "Posts an update of this incident on one of the team's status pages, creating the public\nincident there the first time (`201`; later updates answer `200`). The public incident\ntakes the incident's title. `affected_components` are the impacts as of `published_at`\n(default now); leave the field out to keep them. Confirmed subscribers are emailed\nunless `notify_subscribers` is `false`. Needs both `incidents:write` and\n`status-pages:write`.", "summary": "Publish to a status page", "tags": [ "Incidents" ], "parameters": [ { "name": "incident", "in": "path", "required": true, "description": "Incident ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`PublishStatusPageUpdate`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishStatusPageUpdate" } } } }, "responses": { "200": { "description": "The public incident, updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageIncident" } } } }, "201": { "description": "The public incident, created by this update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageIncident" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/status-pages": { "get": { "operationId": "listStatusPages", "description": "Returns the team's status pages, by name unless you sort.", "summary": "List status pages", "tags": [ "Status pages" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Status pages per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 }, { "name": "filter[visibility]", "in": "query", "description": "Only pages with this visibility.", "schema": { "$ref": "#/components/schemas/StatusPageVisibility" }, "example": "public" }, { "name": "filter[search]", "in": "query", "description": "Case-insensitive text in the name, slug or custom domain.", "schema": { "type": "string" }, "example": "acme" }, { "name": "sort", "in": "query", "description": "Sort by `name` or `created_at`. Prefix `-` for descending. Default `name`.", "schema": { "type": "string" }, "example": "-created_at", "explode": false } ], "responses": { "200": { "description": "Paginated set of `StatusPage`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/StatusPage" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "post": { "operationId": "createStatusPage", "description": "Creates the page on `.spectate.page`; without a `slug` it is derived from the name.\nAdd components next (`createStatusPageComponent`). The plan limits the number of pages\n(`403` `PLAN_LIMIT_REACHED`); private pages, password protection and custom domains need a\nplan that includes them (`403` `PLAN_FEATURE_UNAVAILABLE`). Escalation paths must belong to\nthe team.", "summary": "Create a status page", "tags": [ "Status pages" ], "requestBody": { "description": "`CreateStatusPage`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStatusPage" } } } }, "responses": { "201": { "description": "The new status page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPage" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`PLAN_LIMIT_REACHED`: the plan doesn't allow another one; `details.feature` names the limit.\n\n`PLAN_FEATURE_UNAVAILABLE`: the plan doesn't include this feature; `details.feature` names it.\n\n`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/status-pages/{statusPage}": { "get": { "operationId": "getStatusPage", "description": "Returns the page with its settings and headline status. Its components, incidents and\nmaintenance have their own lists.", "summary": "Get a status page", "tags": [ "Status pages" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The status page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPage" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "patch": { "operationId": "updateStatusPage", "description": "Changes only the settings you send; inside `theme`, also only the keys you send. A new\n`slug` moves the page: the old address stops working. A new `custom_domain` needs to be\nverified again before visitors use it. Turning off issue reports or traffic alerts ends the\nalerts they fired. Private pages, password protection and custom domains need a plan that\nincludes them (`403` `PLAN_FEATURE_UNAVAILABLE`); a page that is private already stays so.", "summary": "Update a status page", "tags": [ "Status pages" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`UpdateStatusPage`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStatusPage" } } } }, "responses": { "200": { "description": "The updated status page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPage" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`PLAN_FEATURE_UNAVAILABLE`: the plan doesn't include this feature; `details.feature` names it.\n\n`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "deleteStatusPage", "description": "The page goes offline at once, with its components, incidents, maintenance, subscribers\nand uploaded logos. Subscribers aren't emailed. Its firing alerts resolve. The team's own\nincidents are kept.", "summary": "Delete a status page", "tags": [ "Status pages" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/status-pages/{statusPage}/custom-domain/verify": { "post": { "operationId": "verifyStatusPageCustomDomain", "description": "Looks up the page's custom domain in DNS. One passing record verifies it: a CNAME to the\npage's `cname_target`, or the TXT record from `custom_domain_verification`. A verified\ndomain stays verified when a later check fails. `routed` tells whether visitors reach the\npage; its certificate is issued on the first visit. The page needs a custom domain (`422`\notherwise). Safe to repeat while DNS changes propagate.", "summary": "Verify the custom domain", "tags": [ "Status pages" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "What DNS returned, and whether the domain is verified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageCustomDomainCheck" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/status-pages/{statusPage}/access-key/rotate": { "post": { "operationId": "rotateStatusPageAccessKey", "description": "Replaces the key in the page's `access_url`: the old link stops working, and every visitor\nof the private page is signed out, including those who entered the password.", "summary": "Rotate the access key", "tags": [ "Status pages" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The status page with its new access URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPage" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/status-pages/{statusPage}/components": { "get": { "operationId": "listStatusPageComponents", "description": "Returns the page's components in the order the page shows them: by group, then position,\nthen name.", "summary": "List components", "tags": [ "Status page components" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Components per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "Paginated set of `StatusPageComponent`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/StatusPageComponent" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "post": { "operationId": "createStatusPageComponent", "description": "The component starts operational and goes last in its group unless you give a\n`position`. `monitor_id` must be a monitor of the team (`422` otherwise).", "summary": "Add a component", "tags": [ "Status page components" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`CreateStatusPageComponent`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStatusPageComponent" } } } }, "responses": { "201": { "description": "The new component.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageComponent" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/status-pages/{statusPage}/components/{component}": { "get": { "operationId": "getStatusPageComponent", "description": "Returns the component with its current status.", "summary": "Get a component", "tags": [ "Status page components" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "component", "in": "path", "required": true, "description": "Component ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The component.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageComponent" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "patch": { "operationId": "updateStatusPageComponent", "description": "Changes only the fields you send. Its status can't be set: post an incident or schedule\nmaintenance instead. `monitor_id: null` unlinks the monitor.", "summary": "Update a component", "tags": [ "Status page components" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "component", "in": "path", "required": true, "description": "Component ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`UpdateStatusPageComponent`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStatusPageComponent" } } } }, "responses": { "200": { "description": "The updated component.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageComponent" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "deleteStatusPageComponent", "description": "It disappears from the page, with its impact periods; incidents and maintenance that\naffected it stay.", "summary": "Delete a component", "tags": [ "Status page components" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "component", "in": "path", "required": true, "description": "Component ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/status-pages/{statusPage}/maintenances": { "get": { "operationId": "listScheduledMaintenances", "description": "Returns the page's maintenance, the latest planned start first.", "summary": "List scheduled maintenance", "tags": [ "Scheduled maintenance" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Maintenances per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 }, { "name": "filter[status]", "in": "query", "description": "Only maintenance with this status.", "schema": { "$ref": "#/components/schemas/ScheduledMaintenanceStatus" }, "example": "scheduled" } ], "responses": { "200": { "description": "Paginated set of `ScheduledMaintenance`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledMaintenance" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "post": { "operationId": "createScheduledMaintenance", "description": "Announces it on the page and emails confirmed subscribers unless `notify_subscribers` is\n`false`. `scheduled_at` must be in the future.", "summary": "Schedule maintenance", "tags": [ "Scheduled maintenance" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`CreateScheduledMaintenance`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduledMaintenance" } } } }, "responses": { "201": { "description": "The new maintenance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledMaintenance" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/status-pages/{statusPage}/maintenances/{maintenance}": { "get": { "operationId": "getScheduledMaintenance", "description": "Returns the maintenance with the components it affects.", "summary": "Get scheduled maintenance", "tags": [ "Scheduled maintenance" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "maintenance", "in": "path", "required": true, "description": "Maintenance ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The maintenance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledMaintenance" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "patch": { "operationId": "updateScheduledMaintenance", "description": "Changes only the fields you send; `affected_components` replaces the list. Setting\n`status` to `in_progress` or `completed` (or setting `completed_at`) emails confirmed\nsubscribers unless `notify_subscribers` is `false`; other changes are silent.", "summary": "Update scheduled maintenance", "tags": [ "Scheduled maintenance" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "maintenance", "in": "path", "required": true, "description": "Maintenance ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`UpdateScheduledMaintenance`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduledMaintenance" } } } }, "responses": { "200": { "description": "The updated maintenance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledMaintenance" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "deleteScheduledMaintenance", "description": "It disappears from the page and its components go back to their other status. Silent:\nsubscribers aren't emailed.", "summary": "Delete scheduled maintenance", "tags": [ "Scheduled maintenance" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "maintenance", "in": "path", "required": true, "description": "Maintenance ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/status-pages/{statusPage}/incidents": { "get": { "operationId": "listStatusPageIncidents", "description": "Returns the page's incidents, newest first, with their updates, affected components and\nimpact periods.", "summary": "List status page incidents", "tags": [ "Status page incidents" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Incidents per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 }, { "name": "filter[status]", "in": "query", "description": "Only incidents with this status.", "schema": { "$ref": "#/components/schemas/IncidentStatus" }, "example": "resolved" }, { "name": "filter[title]", "in": "query", "description": "Case-insensitive text in the title.", "schema": { "type": "string" }, "example": "API" } ], "responses": { "200": { "description": "Paginated set of `StatusPageIncident`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/StatusPageIncident" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "post": { "operationId": "createStatusPageIncident", "description": "Opens a public incident. With a `body` it starts with a first update published at\n`published_at` (default now), and `affected_components` open impact periods from then on.\nConfirmed subscribers are emailed unless `notify_subscribers` is `false`. `incident_id`\nlinks the team's incident, so publishing from it posts here.", "summary": "Create a status page incident", "tags": [ "Status page incidents" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`CreateStatusPageIncident`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStatusPageIncident" } } } }, "responses": { "201": { "description": "The new status page incident.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageIncident" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/status-pages/{statusPage}/incidents/{incident}": { "get": { "operationId": "getStatusPageIncident", "description": "Returns the incident with its updates, affected components and impact periods.", "summary": "Get a status page incident", "tags": [ "Status page incidents" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "incident", "in": "path", "required": true, "description": "Status page incident ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The status page incident.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageIncident" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "patch": { "operationId": "updateStatusPageIncident", "description": "Edits the incident without posting an update; fields left out keep their value.\n`affected_components` set the impacts as of now. Setting `status` to `resolved` closes\nevery open impact period now and emails confirmed subscribers unless\n`notify_subscribers` is `false`; other edits are silent. Changing the status or the\ncomponents takes the incident over from monitor automation.", "summary": "Update a status page incident", "tags": [ "Status page incidents" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "incident", "in": "path", "required": true, "description": "Status page incident ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`UpdateStatusPageIncident`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStatusPageIncident" } } } }, "responses": { "200": { "description": "The updated status page incident.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageIncident" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "deleteStatusPageIncident", "description": "Removes it from the page with its updates and impact periods; component status and\nuptime history follow. Silent: subscribers aren't emailed. The team's incident it was\npublished from is kept.", "summary": "Delete a status page incident", "tags": [ "Status page incidents" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "incident", "in": "path", "required": true, "description": "Status page incident ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/status-pages/{statusPage}/incidents/{incident}/writeup": { "put": { "operationId": "saveStatusPageIncidentWriteup", "description": "Writes the incident's public write-up, in Markdown: what happened, why, and what changes.\nWith `published: true` it shows on the public incident page; with `false` it's a draft only\nthe team sees, and a published write-up is taken down. Publishing needs `content` (`422`).\n\nConfirmed subscribers are emailed the write-up when this publishes it for the first time and\n`notify_subscribers` is `true`; saving a published write-up again never emails. A write-up\nkeeps the time it was first published while you edit it.", "summary": "Save the write-up", "tags": [ "Status page incidents" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "incident", "in": "path", "required": true, "description": "Status page incident ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`SaveStatusPageIncidentWriteup`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SaveStatusPageIncidentWriteup" } } } }, "responses": { "200": { "description": "The incident with its write-up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageIncident" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "deleteStatusPageIncidentWriteup", "description": "Removes the incident's write-up, published or a draft. Silent: subscribers aren't emailed.", "summary": "Delete the write-up", "tags": [ "Status page incidents" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "incident", "in": "path", "required": true, "description": "Status page incident ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The incident without a write-up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageIncident" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/status-pages/{statusPage}/incidents/{incident}/updates": { "post": { "operationId": "createStatusPageIncidentUpdate", "description": "Posts an update at `published_at` (default now) and moves the incident to its `status`.\n`affected_components` are the impacts as of then: changed impacts close and reopen,\ncomponents left out are no longer affected; leave the field out to keep the impacts.\n`resolved` closes every open period. An update published before the incident's latest\none doesn't change the impacts. Confirmed subscribers are emailed unless\n`notify_subscribers` is `false`. Takes the incident over from monitor automation.", "summary": "Publish an update", "tags": [ "Status page incidents" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "incident", "in": "path", "required": true, "description": "Status page incident ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`CreateStatusPageIncidentUpdate`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStatusPageIncidentUpdate" } } } }, "responses": { "201": { "description": "The incident with the new update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageIncident" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/status-pages/{statusPage}/incidents/{incident}/updates/{update}": { "patch": { "operationId": "updateStatusPageIncidentUpdate", "description": "Changes an update's message, status or time; fields left out keep their value. Moving\n`published_at` moves the impact changes made at the old time with it. The incident's\nstatus follows its latest update. Silent, and takes the incident over from monitor\nautomation.", "summary": "Edit an update", "tags": [ "Status page incidents" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "incident", "in": "path", "required": true, "description": "Status page incident ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "update", "in": "path", "required": true, "description": "Update ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`UpdateStatusPageIncidentUpdate`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStatusPageIncidentUpdate" } } } }, "responses": { "200": { "description": "The incident with the edited update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageIncident" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "deleteStatusPageIncidentUpdate", "description": "Removes the update; the incident's status follows its latest remaining update. The\nimpact periods stay as they are. Silent, and takes the incident over from monitor\nautomation.", "summary": "Delete an update", "tags": [ "Status page incidents" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "incident", "in": "path", "required": true, "description": "Status page incident ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "update", "in": "path", "required": true, "description": "Update ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The incident without the update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageIncident" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/status-pages/{statusPage}/incidents/{incident}/impacts": { "post": { "operationId": "createStatusPageImpactPeriod", "description": "Records that the incident affected a component from `started_at` to `ended_at` (`null`\nwhile it goes on). Periods of one component may not overlap within the incident (`422`).\nComponent status and uptime history follow. Silent, and takes the incident over from\nmonitor automation.", "summary": "Add an impact period", "tags": [ "Status page incidents" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "incident", "in": "path", "required": true, "description": "Status page incident ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`CreateStatusPageImpactPeriod`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStatusPageImpactPeriod" } } } }, "responses": { "201": { "description": "The incident with the new period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageIncident" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/status-pages/{statusPage}/incidents/{incident}/impacts/{impact}": { "patch": { "operationId": "updateStatusPageImpactPeriod", "description": "Changes only the fields you send; `ended_at: null` reopens the period. The same rules as\nadding one apply. Silent, and takes the incident over from monitor automation.", "summary": "Update an impact period", "tags": [ "Status page incidents" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "incident", "in": "path", "required": true, "description": "Status page incident ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "impact", "in": "path", "required": true, "description": "Impact period ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`UpdateStatusPageImpactPeriod`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStatusPageImpactPeriod" } } } }, "responses": { "200": { "description": "The incident with the changed period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageIncident" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "deleteStatusPageImpactPeriod", "description": "Component status and uptime history follow. Silent, and takes the incident over from\nmonitor automation.", "summary": "Delete an impact period", "tags": [ "Status page incidents" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "incident", "in": "path", "required": true, "description": "Status page incident ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "impact", "in": "path", "required": true, "description": "Impact period ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The incident without the period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPageIncident" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/status-pages/{statusPage}/subscribers": { "get": { "operationId": "listStatusPageSubscribers", "description": "Returns the page's subscribers, newest first.", "summary": "List subscribers", "tags": [ "Status page subscribers" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Subscribers per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 }, { "name": "filter[confirmed]", "in": "query", "description": "`true` for confirmed subscribers only, `false` for those awaiting confirmation.", "schema": { "type": "boolean" }, "example": true }, { "name": "filter[search]", "in": "query", "description": "Case-insensitive text in the email address.", "schema": { "type": "string" }, "example": "example.com" } ], "responses": { "200": { "description": "Paginated set of `StatusPageSubscriber`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/StatusPageSubscriber" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/status-pages/{statusPage}/subscribers/{subscriber}": { "delete": { "operationId": "deleteStatusPageSubscriber", "description": "They get no more emails from the page and aren't told. They can subscribe again on the\npage.", "summary": "Remove a subscriber", "tags": [ "Status page subscribers" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "subscriber", "in": "path", "required": true, "description": "Subscriber ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/status-pages/{statusPage}/issue-reports": { "get": { "operationId": "listStatusPageIssueReports", "description": "Returns the problems visitors reported, newest first. The visitor's email address is only\nreturned to tokens with `status-pages:write`. Whether the page is above its threshold is\non the status page (`issue_reports_triggered_at`).", "summary": "List issue reports", "tags": [ "Status page issue reports" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Reports per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "Paginated set of `StatusPageIssueReport`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/StatusPageIssueReport" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/status-pages/{statusPage}/issue-reports/{report}": { "delete": { "operationId": "deleteStatusPageIssueReport", "description": "For example to remove a visitor's email address.", "summary": "Delete an issue report", "tags": [ "Status page issue reports" ], "parameters": [ { "name": "statusPage", "in": "path", "required": true, "description": "Status page ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "report", "in": "path", "required": true, "description": "Issue report ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/team": { "get": { "operationId": "getTeam", "description": "Returns the token's team. Works with any token.", "summary": "Get the team", "tags": [ "Team" ], "responses": { "200": { "description": "The team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "patch": { "operationId": "updateTeam", "description": "Changes only the fields you send.", "summary": "Update the team", "tags": [ "Team" ], "requestBody": { "description": "`UpdateTeam`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeam" } } } }, "responses": { "200": { "description": "The updated team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/members": { "get": { "operationId": "listMembers", "description": "Returns the team's members, by name.", "summary": "List members", "tags": [ "Members" ], "parameters": [ { "name": "filter[role]", "in": "query", "description": "Only members with this role.", "schema": { "$ref": "#/components/schemas/TeamRole" }, "example": "admin" }, { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Members per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "Paginated set of `Member`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/members/{member}": { "get": { "operationId": "getMember", "description": "Returns a member of the team by their ID.", "summary": "Get a member", "tags": [ "Members" ], "parameters": [ { "name": "member", "in": "path", "required": true, "description": "Member (user) ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The member.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "patch": { "operationId": "updateMember", "description": "The owner's role can't change, and nobody becomes owner this way (`403` `TEAM_OWNER_PROTECTED`).\nThe API can't transfer ownership: only the owner can, in the dashboard (Team \u2192 Settings),\nafter confirming their password.", "summary": "Change a member's role", "tags": [ "Members" ], "parameters": [ { "name": "member", "in": "path", "required": true, "description": "Member (user) ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "`UpdateMember`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMember" } } } }, "responses": { "200": { "description": "The member with the new role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`TEAM_OWNER_PROTECTED`: the team owner's role can't be changed and the owner can't be removed.\n\n`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "removeMember", "description": "They lose access to the team at once and leave its on-call rotations; what they did stays\nin the history. API tokens they created keep working: revoke them in the dashboard if\nneeded. The owner can't be removed (`403` `TEAM_OWNER_PROTECTED`).", "summary": "Remove a member", "tags": [ "Members" ], "parameters": [ { "name": "member", "in": "path", "required": true, "description": "Member (user) ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`TEAM_OWNER_PROTECTED`: the team owner's role can't be changed and the owner can't be removed.\n\n`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/invites": { "get": { "operationId": "listInvites", "description": "Returns the team's invites that weren't accepted or revoked, newest first, including\nexpired ones.", "summary": "List invites", "tags": [ "Invites" ], "parameters": [ { "name": "page", "in": "query", "description": "Page number, from 1.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "per_page", "in": "query", "description": "Invites per page, 1 to 100.", "schema": { "type": "integer", "default": 25 }, "example": 25 } ], "responses": { "200": { "description": "Paginated set of `Invite`", "content": { "application/json": { "schema": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invite" } }, "first_page_url": { "type": [ "string", "null" ] }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page_url": { "type": [ "string", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "next_page_url": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "prev_page_url": { "type": [ "string", "null" ] }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "data", "first_page_url", "from", "last_page_url", "last_page", "links", "next_page_url", "path", "per_page", "prev_page_url", "to", "total" ] } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "post": { "operationId": "createInvite", "description": "Emails them a link to join the team. Someone who is a member already, or has a pending\ninvite, can't be invited again (`422`); an expired invite to the address is replaced. Over\nthe plan's member limit, counting pending invites, the request fails with `403`\n`PLAN_LIMIT_REACHED`.", "summary": "Invite someone", "tags": [ "Invites" ], "requestBody": { "description": "`CreateInvite`", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvite" } } } }, "responses": { "201": { "description": "The invite.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invite" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`PLAN_LIMIT_REACHED`: the plan doesn't allow another one; `details.feature` names the limit.\n\n`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "`VALIDATION_FAILED`: the request is invalid; `details.errors` lists the fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/invites/{invite}": { "get": { "operationId": "getInvite", "description": "Returns the invite, also when it has expired.", "summary": "Get an invite", "tags": [ "Invites" ], "parameters": [ { "name": "invite", "in": "path", "required": true, "description": "Invite ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The invite.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invite" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } }, "delete": { "operationId": "revokeInvite", "description": "The link in the email stops working. The invitee isn't told.", "summary": "Revoke an invite", "tags": [ "Invites" ], "parameters": [ { "name": "invite", "in": "path", "required": true, "description": "Invite ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "`RESOURCE_NOT_FOUND`: there is no such resource in this team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/billing": { "get": { "operationId": "getBilling", "description": "Returns the plan, the subscription and the SMS and voice notification credits.", "summary": "Get billing", "tags": [ "Billing" ], "responses": { "200": { "description": "The billing state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } }, "/billing/usage": { "get": { "operationId": "getUsage", "description": "Returns, per plan limit, how much the team uses and the limit. Useful before creating\nresources in bulk.", "summary": "Get plan usage", "tags": [ "Billing" ], "responses": { "200": { "description": "Usage per plan limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "401": { "description": "`UNAUTHENTICATED`: no token was sent. `INVALID_TOKEN`: the token is unknown or revoked. `TOKEN_EXPIRED`: the token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "`FORBIDDEN`: the token lacks an ability this endpoint requires (listed in `details.required_abilities`). `TEAM_PENDING_DELETION`: the team is scheduled for deletion. `TEAM_SUSPENDED`: Spectate suspended the team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "`RATE_LIMITED`: too many requests for this token. Wait for the number of seconds in `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "required": true, "schema": { "type": "integer" } } } } } } } }, "components": { "securitySchemes": { "TeamApiToken": { "type": "http", "description": "A team API token, sent as `Authorization: Bearer spct_\u2026`. Owners and managers create tokens under Team \u2192 API tokens in the dashboard; each token has explicit abilities (for example `monitors:read`) and acts for its team only.", "scheme": "bearer" } }, "schemas": { "ActivityCauserType": { "type": "string", "description": "Who caused an activity log entry.\n| |\n|---|\n| `user`
A team member. |\n| `api_token`
A team API token. |\n| `employee`
Spectate staff. |", "enum": [ "user", "api_token", "employee" ], "title": "ActivityCauserType" }, "Alert": { "type": "object", "description": "An alert: a problem a monitor, host, domain, status page or alert source detected. It escalates\nalong its escalation path until someone acknowledges it, and resolves when the problem is over.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Alert ID" }, "title": { "type": "string", "description": "What's wrong", "examples": [ "Website is down" ] }, "description": { "type": [ "string", "null" ], "description": "More about it, as the source described it" }, "status": { "description": "Whether the problem is ongoing\n\n| |\n|---|\n| `firing`
The problem is ongoing; it escalates until acknowledged. |\n| `resolved`
The problem is over. |", "$ref": "#/components/schemas/AlertStatus" }, "severity": { "description": "How urgent it is\n\n| |\n|---|\n| `critical`
Customers are affected right now. |\n| `high`
Serious, needs attention soon. |\n| `medium`
Should be looked at. |\n| `low`
Informational. |", "$ref": "#/components/schemas/Severity" }, "source_type": { "description": "What raised it\n\n| |\n|---|\n| `uptime`
A monitor went down. |\n| `certificate`
A monitor's certificate is invalid or expires soon. |\n| `performance`
A monitor got slow. |\n| `dns`
The answer of a DNS monitor changed (when it alerts on changes). |\n| `host_metric`
A host's metric condition held, or it stopped sending data. |\n| `domain`
A domain expires soon, expired or its registration changed. |\n| `external`
An alert source (external tool) fired it. |\n| `status_page`
Visitor issue reports over the threshold or a traffic spike (`metadata.type`: `issue_reports`, `traffic_spike`). |", "$ref": "#/components/schemas/AlertSourceType" }, "resource": { "anyOf": [ { "description": "The resource it's about; `null` when that was deleted", "$ref": "#/components/schemas/AlertResource" }, { "type": "null" } ] }, "fired_at": { "type": "string", "format": "date-time", "description": "When it fired" }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was acknowledged, which stopped its escalation; `null` while unacknowledged" }, "acknowledged_by": { "type": [ "string", "null" ], "description": "Who acknowledged it: a member's name, an API token, or how (for example a phone call)", "examples": [ "Jane Doe" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it resolved; `null` while firing" }, "resolved_by": { "type": [ "string", "null" ], "description": "Who resolved it by hand: a member's name or an API token. `null` while firing, and when it\nresolved on its own because the problem was over", "examples": [ "Jane Doe" ] }, "labels": { "type": [ "object", "null" ], "description": "Labels the source sent (Prometheus, Grafana); `null` when it sent none", "additionalProperties": { "type": "string" } }, "links": { "type": "array", "description": "Links the source sent along", "items": { "$ref": "#/components/schemas/AlertLink" } } }, "required": [ "id", "title", "description", "status", "severity", "source_type", "resource", "fired_at", "acknowledged_at", "acknowledged_by", "resolved_at", "resolved_by", "labels", "links" ], "title": "Alert" }, "AlertLink": { "type": "object", "description": "A link the alert source sent along.", "properties": { "label": { "type": "string", "description": "What it opens", "examples": [ "View issue in Sentry" ] }, "url": { "type": "string", "format": "uri", "description": "Where it goes" } }, "required": [ "label", "url" ], "title": "AlertLink" }, "AlertResource": { "type": "object", "description": "The resource an alert is about.", "properties": { "type": { "description": "What kind of resource", "$ref": "#/components/schemas/AlertResourceType" }, "id": { "type": "string", "format": "uuid", "description": "The resource's ID, for example a monitor ID" }, "name": { "type": [ "string", "null" ], "description": "Its name or label", "examples": [ "Website" ] } }, "required": [ "type", "id", "name" ], "title": "AlertResource" }, "AlertResourceType": { "type": "string", "description": "What kind of resource an alert is about.\n", "enum": [ "monitor", "host", "domain", "status_page", "alert_source" ], "title": "AlertResourceType" }, "AlertSource": { "type": "object", "description": "An alert source: an external tool (Prometheus Alertmanager, Grafana, Sentry, a script\u2026) whose\nrequests to `webhook_url`, or mails to `email_address`, fire and resolve alerts. The URL and\naddress contain the source's secret token: whoever has them can fire alerts.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Alert source ID" }, "name": { "type": "string", "description": "Name shown on its alerts", "examples": [ "Production Alertmanager" ] }, "type": { "description": "The tool, which decides how requests are read\n\n| |\n|---|\n| `webhook`
Spectate's own JSON format, for scripts, CI and anything that can call a URL. |\n| `email`
Emails to the source's own address (subject becomes the alert). |\n| `alertmanager`
Prometheus Alertmanager `webhook_configs`. |\n| `grafana`
Grafana Alerting webhook contact point (Alertmanager format plus Grafana links). |\n| `sentry`
Sentry internal integration webhooks (SaaS and self-hosted), or the legacy WebHooks plugin. |", "$ref": "#/components/schemas/AlertSourceProvider" }, "enabled": { "type": "boolean", "description": "Whether requests fire alerts; a disabled source rejects them" }, "webhook_url": { "type": "string", "format": "uri", "description": "Where the tool sends its webhooks. Secret: rotate it with `rotateAlertSourceToken` if it leaks" }, "email_address": { "type": [ "string", "null" ], "format": "email", "description": "`email` sources: the address to send mails to. Secret like the URL" }, "has_secret": { "type": "boolean", "description": "Whether a signing secret is set (Sentry client secret, Grafana HMAC secret, Alertmanager bearer token); it's never returned" }, "default_severity": { "description": "Severity of alerts the tool sends without one\n\n| |\n|---|\n| `critical`
Customers are affected right now. |\n| `high`
Serious, needs attention soon. |\n| `medium`
Should be looked at. |\n| `low`
Informational. |", "$ref": "#/components/schemas/Severity" }, "auto_resolve_minutes": { "type": [ "integer", "null" ], "description": "Minutes after which an alert the tool stopped repeating resolves; `null` keeps it until the tool resolves it", "examples": [ 60 ] }, "settings": { "description": "Type-specific settings", "$ref": "#/components/schemas/AlertSourceSettings" }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The project whose escalation paths apply when the source has none of its own; `null` for none" }, "escalation_paths": { "type": "array", "description": "Escalation paths the source's alerts follow. Empty: the project's paths, else the team's default path", "items": { "$ref": "#/components/schemas/EscalationPathReference" } }, "last_event_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the source last received a request" }, "events_count": { "type": "integer", "description": "Requests the source has received in total" }, "firing_alerts_count": { "type": "integer", "description": "Alerts of the source that are firing now" }, "created_at": { "type": "string", "format": "date-time", "description": "When the source was created" } }, "required": [ "id", "name", "type", "enabled", "webhook_url", "email_address", "has_secret", "default_severity", "auto_resolve_minutes", "settings", "project_id", "escalation_paths", "last_event_at", "events_count", "firing_alerts_count", "created_at" ], "title": "AlertSource" }, "AlertSourceEvent": { "type": "object", "description": "A request an alert source received, kept for 7 days.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Event ID" }, "received_at": { "type": "string", "format": "date-time", "description": "When the request arrived" }, "outcome": { "description": "What became of it\n\n| |\n|---|\n| `fired`
It fired at least one new alert. |\n| `resolved`
It resolved at least one alert. |\n| `updated`
It repeated alerts that were already firing. |\n| `test`
A test request from the tool's own \"test\" button; no alert. |\n| `ignored`
Valid, but nothing to do (for example a resolve of an alert that isn't firing). |\n| `rejected`
Refused: bad signature, unreadable payload or a disabled source; see `error`. |", "$ref": "#/components/schemas/AlertSourceEventOutcome" }, "summary": { "type": [ "string", "null" ], "description": "What happened, in words", "examples": [ "2 alerts fired" ] }, "error": { "type": [ "string", "null" ], "description": "Why it was rejected, with `outcome` `rejected`" }, "alerts": { "type": "array", "description": "What it did per alert", "items": { "$ref": "#/components/schemas/AlertSourceEventAlert" } }, "payload": { "type": [ "object", "null" ], "description": "The request body as received: the tool's JSON, or `{body, truncated}` for mail and non-JSON bodies. Its shape is the tool's", "additionalProperties": {} } }, "required": [ "id", "received_at", "outcome", "summary", "error", "alerts", "payload" ], "title": "AlertSourceEvent" }, "AlertSourceEventAction": { "type": "string", "description": "What a request did to one alert.\n| |\n|---|\n| `fired`
A new alert fired. |\n| `updated`
The alert was already firing; it was updated. |\n| `resolved`
The alert resolved. |\n| `ignored`
A resolve for an alert that wasn't firing. |", "enum": [ "fired", "updated", "resolved", "ignored" ], "title": "AlertSourceEventAction" }, "AlertSourceEventAlert": { "type": "object", "description": "What a request did to one alert.", "properties": { "action": { "description": "What happened to the alert\n\n| |\n|---|\n| `fired`
A new alert fired. |\n| `updated`
The alert was already firing; it was updated. |\n| `resolved`
The alert resolved. |\n| `ignored`
A resolve for an alert that wasn't firing. |", "$ref": "#/components/schemas/AlertSourceEventAction" }, "title": { "type": "string", "description": "The alert's title", "examples": [ "HighErrorRate" ] }, "dedupe_key": { "type": "string", "description": "The key the tool groups repeats by; requests with the same key update one alert", "examples": [ "4c3d9a\u2026" ] }, "alert_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The alert; `null` when none was touched" } }, "required": [ "action", "title", "dedupe_key", "alert_id" ], "title": "AlertSourceEventAlert" }, "AlertSourceEventOutcome": { "type": "string", "description": "What became of a request an alert source received.\n| |\n|---|\n| `fired`
It fired at least one new alert. |\n| `resolved`
It resolved at least one alert. |\n| `updated`
It repeated alerts that were already firing. |\n| `test`
A test request from the tool's own \"test\" button; no alert. |\n| `ignored`
Valid, but nothing to do (for example a resolve of an alert that isn't firing). |\n| `rejected`
Refused: bad signature, unreadable payload or a disabled source; see `error`. |", "enum": [ "fired", "resolved", "updated", "test", "ignored", "rejected" ], "title": "AlertSourceEventOutcome" }, "AlertSourceProvider": { "type": "string", "description": "The external tool behind an alert source; decides how its requests are read.\n| |\n|---|\n| `webhook`
Spectate's own JSON format, for scripts, CI and anything that can call a URL. |\n| `email`
Emails to the source's own address (subject becomes the alert). |\n| `alertmanager`
Prometheus Alertmanager `webhook_configs`. |\n| `grafana`
Grafana Alerting webhook contact point (Alertmanager format plus Grafana links). |\n| `sentry`
Sentry internal integration webhooks (SaaS and self-hosted), or the legacy WebHooks plugin. |", "enum": [ "webhook", "email", "alertmanager", "grafana", "sentry" ], "title": "AlertSourceProvider" }, "AlertSourceSettings": { "type": "object", "description": "Settings of some source types; the others ignore them.", "properties": { "alert_on_new_issues": { "type": [ "boolean", "null" ], "description": "Sentry: also alert on every new issue (issue `created` webhooks), not only on alert rules" }, "signature_header": { "type": [ "string", "null" ], "description": "Grafana: the header carrying the HMAC signature; `null` means `X-Grafana-Alerting-Signature`", "examples": [ "X-Grafana-Alerting-Signature" ] }, "timestamp_header": { "type": [ "string", "null" ], "description": "Grafana: the timestamp header, when the contact point signs `{timestamp}:{body}`" } }, "required": [ "alert_on_new_issues", "signature_header", "timestamp_header" ], "title": "AlertSourceSettings" }, "AlertSourceSettingsInput": { "type": "object", "description": "Settings to set; settings you leave out keep their value.", "properties": { "alert_on_new_issues": { "type": "boolean", "description": "Sentry: also alert on every new issue" }, "signature_header": { "type": [ "string", "null" ], "description": "Grafana: the header carrying the HMAC signature, up to 100 characters; `null` for the default", "examples": [ "X-Grafana-Alerting-Signature" ], "maxLength": 100 }, "timestamp_header": { "type": [ "string", "null" ], "description": "Grafana: the timestamp header, when the contact point signs `{timestamp}:{body}`; `null` for none", "maxLength": 100 } }, "title": "AlertSourceSettingsInput" }, "AlertSourceType": { "type": "string", "description": "What raised an alert.\n| |\n|---|\n| `uptime`
A monitor went down. |\n| `certificate`
A monitor's certificate is invalid or expires soon. |\n| `performance`
A monitor got slow. |\n| `dns`
The answer of a DNS monitor changed (when it alerts on changes). |\n| `host_metric`
A host's metric condition held, or it stopped sending data. |\n| `domain`
A domain expires soon, expired or its registration changed. |\n| `external`
An alert source (external tool) fired it. |\n| `status_page`
Visitor issue reports over the threshold or a traffic spike (`metadata.type`: `issue_reports`, `traffic_spike`). |", "enum": [ "uptime", "certificate", "performance", "dns", "host_metric", "domain", "external", "status_page" ], "title": "AlertSourceType" }, "AlertStatus": { "type": "string", "description": "Whether an alert's problem is ongoing.\n| |\n|---|\n| `firing`
The problem is ongoing; it escalates until acknowledged. |\n| `resolved`
The problem is over. |", "enum": [ "firing", "resolved" ], "title": "AlertStatus" }, "ApiError": { "type": "object", "description": "An error. The HTTP status tells the class of problem, `error.code` the exact one.", "properties": { "error": { "type": "object", "description": "What went wrong.", "properties": { "code": { "type": "string", "description": "Machine-readable error code in `UPPER_SNAKE_CASE`, for example `RESOURCE_NOT_FOUND`. Codes are stable; branch on them, not on the message.", "examples": [ "RESOURCE_NOT_FOUND" ] }, "message": { "type": "string", "description": "Human-readable explanation. It may change; show it, but do not parse it.", "examples": [ "Monitor not found." ] }, "details": { "type": "object", "description": "Extra context for some error codes; absent for most. Its keys depend on the code.", "properties": { "required_abilities": { "type": "array", "description": "With `FORBIDDEN`: the abilities the token lacks for this endpoint.", "items": { "$ref": "#/components/schemas/ApiTokenAbility" } }, "feature": { "type": "string", "description": "With `PLAN_LIMIT_REACHED` and `PLAN_FEATURE_UNAVAILABLE`: the plan limit or feature, for example `resources` (monitors and hosts together) or `projects`.", "examples": [ "resources" ] }, "permanent": { "type": "boolean", "description": "With `CHANNEL_TEST_FAILED`: `true` when the settings are wrong (retrying won't help), `false` for a temporary failure." } } } }, "required": [ "code", "message" ] } }, "required": [ "error" ], "title": "ApiError" }, "ApiToken": { "type": "object", "description": "The API token that made the request.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Token ID" }, "name": { "type": "string", "description": "Name given to the token when it was created", "examples": [ "Terraform" ] }, "last_four": { "type": "string", "description": "Last four characters of the token, to tell tokens apart", "examples": [ "a1B2" ] }, "abilities": { "type": "array", "description": "What the token may do. Each endpoint lists the ability it requires", "items": { "$ref": "#/components/schemas/ApiTokenAbility" } }, "team": { "description": "The team the token acts for", "$ref": "#/components/schemas/ApiTokenTeam" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the token stops working; `null` if it never expires" }, "created_at": { "type": "string", "format": "date-time", "description": "When the token was created" } }, "required": [ "id", "name", "last_four", "abilities", "team", "expires_at", "created_at" ], "title": "ApiToken" }, "ApiTokenAbility": { "type": "string", "description": "An ability of a team API token: what it may do. Each endpoint requires one. Abilities are the team permissions of the same name, so a member can only give a token what their own role allows. Tokens list their abilities explicitly; there is no wildcard, so a token never gains an ability it wasn't created with.\n| |\n|---|\n| `monitors:read`
Read monitors, their checks, uptime and certificates. |\n| `monitors:write`
Create and change monitors, and pause or resume them. |\n| `monitors:delete`
Delete monitors. |\n| `hosts:read`
Read hosts, their metrics and metric conditions. |\n| `hosts:write`
Change hosts, install tokens and metric conditions. |\n| `hosts:delete`
Delete hosts. |\n| `domains:read`
Read domains and their registration and DNS state. |\n| `domains:write`
Add and change domains. |\n| `domains:delete`
Delete domains. |\n| `projects:read`
Read projects. |\n| `projects:write`
Create and change projects. |\n| `projects:delete`
Delete projects. |\n| `alerting:read`
Read alerts, channels, escalation paths, alert sources and on-call schedules. |\n| `alerting:write`
Create and change channels, escalation paths, alert sources and on-call schedules. |\n| `alerting:delete`
Delete channels, escalation paths, alert sources, on-call schedules and resolved alerts. |\n| `alerts:acknowledge`
Acknowledge alerts, which stops their escalation. |\n| `alerts:resolve`
Resolve alerts by hand, which stops their escalation and tells everyone notified that they're over. |\n| `incidents:read`
Read incidents, their updates, timeline and postmortem. |\n| `incidents:write`
Declare, update, acknowledge and resolve incidents. |\n| `incidents:delete`
Delete incidents. |\n| `status-pages:read`
Read status pages, components, status page incidents, maintenances and subscribers. |\n| `status-pages:write`
Create and change status pages, components, status page incidents and maintenances. |\n| `status-pages:delete`
Delete status pages, components, status page incidents, maintenances and subscribers. |\n| `members:read`
Read team members and pending invites. |\n| `members:write`
Invite members, change their roles and remove them. |\n| `team:update`
Change the team's name and settings. |\n| `billing:read`
Read the subscription, notification credits and plan usage. |", "enum": [ "monitors:read", "monitors:write", "monitors:delete", "hosts:read", "hosts:write", "hosts:delete", "domains:read", "domains:write", "domains:delete", "projects:read", "projects:write", "projects:delete", "alerting:read", "alerting:write", "alerting:delete", "alerts:acknowledge", "alerts:resolve", "incidents:read", "incidents:write", "incidents:delete", "status-pages:read", "status-pages:write", "status-pages:delete", "members:read", "members:write", "team:update", "billing:read" ], "title": "ApiTokenAbility" }, "ApiTokenTeam": { "type": "object", "description": "The team an API token acts for.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Team ID" }, "name": { "type": "string", "description": "Team name", "examples": [ "Acme" ] } }, "required": [ "id", "name" ], "title": "ApiTokenTeam" }, "AssignIncidentRole": { "type": "object", "description": "Who gets an incident role.", "properties": { "member_id": { "type": "string", "format": "uuid", "description": "The member who takes the role; they replace whoever had it" } }, "required": [ "member_id" ], "title": "AssignIncidentRole" }, "Billing": { "type": "object", "description": "The team's billing state. Subscriptions are changed in the dashboard.", "properties": { "plan": { "description": "The plan whose limits apply now: the trial plan during the trial, `none` without a plan\n\n| |\n|---|\n| `none`
No paid plan and no trial: monitoring is paused until the team subscribes. |\n| `starter`
Starter: up to 3 members and 1 status page, the team default escalation path only. |\n| `team`
Team: unlimited members, 5 status pages, on-call, more escalation paths and private status pages. |\n| `business`
Business: everything in Team, with unlimited status pages and more subscribers and notification credits. |", "$ref": "#/components/schemas/Plan" }, "subscribed": { "type": "boolean", "description": "Whether the team has a paid subscription" }, "on_trial": { "type": "boolean", "description": "Whether the team is on its trial" }, "trial_ends_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the trial ends; `null` without one" }, "plan_ends_at": { "type": [ "string", "null" ], "format": "date-time", "description": "End of a plan Spectate granted without a subscription; `null` without one" }, "subscription": { "anyOf": [ { "description": "The subscription; `null` without one", "$ref": "#/components/schemas/Subscription" }, { "type": "null" } ] }, "notification_credits": { "description": "SMS and voice notification credits", "$ref": "#/components/schemas/NotificationCredits" } }, "required": [ "plan", "subscribed", "on_trial", "trial_ends_at", "plan_ends_at", "subscription", "notification_credits" ], "title": "Billing" }, "BillingInterval": { "type": "string", "description": "Billing interval of a subscription; the values are Vatly's `interval` values.\n| |\n|---|\n| `month`
Billed every month. |\n| `year`
Billed every year, for the price of 10 months. |", "enum": [ "month", "year" ], "title": "BillingInterval" }, "CertificateStatus": { "type": "string", "description": "The state of a monitor's TLS certificate, from its latest certificate check.\n| |\n|---|\n| `pending`
Not checked yet. |\n| `valid`
Valid and not about to expire. |\n| `invalid`
Not trusted, for example self-signed, for another host or with a broken chain. |\n| `expires_soon`
Valid, but expires within the monitor's `certificate_expiry_threshold_days`. |\n| `expired`
Past its expiry date. |", "enum": [ "pending", "valid", "invalid", "expires_soon", "expired" ], "title": "CertificateStatus" }, "Channel": { "type": "object", "description": "A notification channel: where escalation paths send alerts. The settings of its type are in the\nobject of that name (`email`, `slack`\u2026); the others are `null`. Secrets (webhook URLs, tokens,\nheader values) are never returned.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Channel ID" }, "name": { "type": "string", "description": "Name shown in escalation paths", "examples": [ "On-call email" ] }, "type": { "description": "Where the channel delivers", "$ref": "#/components/schemas/ChannelType" }, "enabled": { "type": "boolean", "description": "Whether the channel delivers. `false` when a member turned it off or Spectate did after repeated failures (`auto_disabled`)" }, "auto_disabled": { "type": "boolean", "description": "Whether Spectate turned the channel off because deliveries kept failing. Fix the cause, then enable it or send a test with `enable`" }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the channel was turned off automatically" }, "disabled_reason": { "type": [ "string", "null" ], "description": "Why it was turned off automatically" }, "consecutive_failures": { "type": "integer", "description": "Failed deliveries since the last successful one" }, "failing_since": { "type": [ "string", "null" ], "format": "date-time", "description": "Since when deliveries fail" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a delivery last failed" }, "last_failure_reason": { "type": [ "string", "null" ], "description": "Why the last delivery failed" }, "last_delivered_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a delivery last succeeded" }, "email": { "anyOf": [ { "description": "`email` channels: where they send", "$ref": "#/components/schemas/ChannelEmail" }, { "type": "null" } ] }, "slack": { "anyOf": [ { "description": "`slack` channels: where they post", "$ref": "#/components/schemas/ChannelSlack" }, { "type": "null" } ] }, "telegram": { "anyOf": [ { "description": "`telegram` channels: the connected chat", "$ref": "#/components/schemas/ChannelTelegram" }, { "type": "null" } ] }, "webhook": { "anyOf": [ { "description": "`webhook` channels: where they post (host and header names only)", "$ref": "#/components/schemas/ChannelWebhook" }, { "type": "null" } ] }, "pushover": { "anyOf": [ { "description": "`pushover` channels: who they notify", "$ref": "#/components/schemas/ChannelPushover" }, { "type": "null" } ] }, "sms": { "anyOf": [ { "description": "`sms` channels: the number they text", "$ref": "#/components/schemas/ChannelPhone" }, { "type": "null" } ] }, "voice": { "anyOf": [ { "description": "`voice` channels: the number they call", "$ref": "#/components/schemas/ChannelPhone" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "When the channel was created" } }, "required": [ "id", "name", "type", "enabled", "auto_disabled", "disabled_at", "disabled_reason", "consecutive_failures", "failing_since", "last_failure_at", "last_failure_reason", "last_delivered_at", "email", "slack", "telegram", "webhook", "pushover", "sms", "voice", "created_at" ], "title": "Channel" }, "ChannelEmail": { "type": "object", "description": "Where an `email` channel sends.", "properties": { "address": { "type": "string", "format": "email", "description": "The address alerts go to", "examples": [ "oncall@example.com" ], "maxLength": 255 } }, "required": [ "address" ], "title": "ChannelEmail" }, "ChannelPhone": { "type": "object", "description": "The phone an `sms` or `voice` channel reaches. Each message or call uses the team's\nnotification credits.", "properties": { "phone_number": { "type": "string", "description": "The phone number in international format", "examples": [ "+31612345678" ], "maxLength": 32 } }, "required": [ "phone_number" ], "title": "ChannelPhone" }, "ChannelPushover": { "type": "object", "description": "Who a `pushover` channel notifies. The application token is write-only.", "properties": { "user_key": { "type": "string", "description": "The Pushover user or group key", "examples": [ "uQiRzpo4DXghDmr9QzzfQu27cmVRsG" ] }, "priority": { "type": [ "integer", "null" ], "description": "Pushover priority, -2 (lowest) to 2 (emergency); `null` for normal (0)", "examples": [ 1 ] } }, "required": [ "user_key", "priority" ], "title": "ChannelPushover" }, "ChannelPushoverInput": { "type": "object", "description": "Who a `pushover` channel notifies, and with which Pushover application.", "properties": { "user_key": { "type": "string", "description": "The Pushover user or group key", "examples": [ "uQiRzpo4DXghDmr9QzzfQu27cmVRsG" ], "maxLength": 255 }, "api_token": { "type": "string", "description": "Your Pushover application's API token. Write-only: never returned", "examples": [ "azGDORePK8gMaC0QOYAMyEEuzJnyUi" ], "maxLength": 255 }, "priority": { "type": "integer", "description": "Pushover priority, -2 (lowest) to 2 (emergency). Default 0", "examples": [ 1 ], "minimum": -2, "maximum": 2 } }, "required": [ "user_key", "api_token" ], "title": "ChannelPushoverInput" }, "ChannelReference": { "type": "object", "description": "A channel something sends to.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Channel ID" }, "name": { "type": "string", "description": "Channel name", "examples": [ "On-call email" ] }, "type": { "description": "Where it delivers", "$ref": "#/components/schemas/ChannelType" }, "enabled": { "type": "boolean", "description": "Whether it delivers; disabled channels are skipped" } }, "required": [ "id", "name", "type", "enabled" ], "title": "ChannelReference" }, "ChannelSlack": { "type": "object", "description": "Where a `slack` channel posts: a channel of a Slack workspace connected under Integrations.", "properties": { "installation_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The team's Slack installation (workspace) that posts. `null` for older channels with their own bot token" }, "channel": { "type": "string", "description": "The Slack channel ID", "examples": [ "C0123456789" ] }, "channel_name": { "type": [ "string", "null" ], "description": "The channel's name, for display", "examples": [ "#alerts" ] } }, "required": [ "installation_id", "channel", "channel_name" ], "title": "ChannelSlack" }, "ChannelSlackInput": { "type": "object", "description": "Where a `slack` channel posts. Connect the Slack workspace under Integrations in the dashboard\nfirst; the installation's ID is in the Slack integration.", "properties": { "installation_id": { "type": "string", "format": "uuid", "description": "The team's Slack installation (workspace) that posts" }, "channel": { "type": "string", "description": "The Slack channel ID (not its name); invite the Spectate app to private channels", "examples": [ "C0123456789" ], "maxLength": 255 }, "channel_name": { "type": [ "string", "null" ], "description": "The channel's name, for display", "examples": [ "#alerts" ], "maxLength": 255 } }, "required": [ "installation_id", "channel" ], "title": "ChannelSlackInput" }, "ChannelTelegram": { "type": "object", "description": "The chat a `telegram` channel sends to. Telegram channels are connected from the dashboard\n(Alerting \u2192 Channels), not through the API.", "properties": { "chat_id": { "type": "string", "description": "The Telegram chat ID", "examples": [ "-1001234567890" ] }, "chat_title": { "type": [ "string", "null" ], "description": "The chat's title, for display", "examples": [ "Ops alerts" ] } }, "required": [ "chat_id", "chat_title" ], "title": "ChannelTelegram" }, "ChannelTestResult": { "type": "object", "description": "A test notification that was delivered.", "properties": { "message": { "type": "string", "description": "What was sent", "examples": [ "Test notification sent" ] }, "channel": { "description": "The channel after the test: its failure count is cleared, and with `enable` it's enabled again", "$ref": "#/components/schemas/Channel" } }, "required": [ "message", "channel" ], "title": "ChannelTestResult" }, "ChannelType": { "type": "string", "enum": [ "email", "slack", "discord", "microsoft_teams", "telegram", "webhook", "pushover", "sms", "voice" ], "title": "ChannelType" }, "ChannelWebhook": { "type": "object", "description": "What a `webhook` channel sends. The URL and header values can hold credentials, so only the host\nand the header names are returned.", "properties": { "host": { "type": [ "string", "null" ], "description": "The host of the URL the channel posts to", "examples": [ "hooks.example.com" ] }, "header_names": { "type": "array", "description": "Names of the headers it sends", "items": { "type": "string" } } }, "required": [ "host", "header_names" ], "title": "ChannelWebhook" }, "ChannelWebhookHeader": { "type": "object", "description": "A header a `webhook` channel sends with every request.", "properties": { "key": { "type": "string", "description": "Header name. Hop-by-hop and connection headers are refused", "examples": [ "Authorization" ], "maxLength": 128 }, "value": { "type": "string", "description": "Header value; write-only, never returned", "examples": [ "Bearer s3cr3t" ], "maxLength": 1024 } }, "required": [ "key", "value" ], "title": "ChannelWebhookHeader" }, "ChannelWebhookInput": { "type": "object", "description": "Where a `webhook` channel posts its JSON. The URL and header values are write-only.", "properties": { "url": { "type": "string", "format": "uri", "description": "The URL to `POST` to; must be a public HTTP or HTTPS address", "examples": [ "https://hooks.example.com/spectate" ], "maxLength": 2048 }, "headers": { "type": "array", "description": "Headers to send with every request, for example for authentication", "items": { "$ref": "#/components/schemas/ChannelWebhookHeader" } } }, "required": [ "url" ], "title": "ChannelWebhookInput" }, "ChannelWebhookUrlInput": { "type": "object", "description": "The incoming webhook a `discord` or `microsoft_teams` channel posts to. It's a secret: it's never\nreturned.", "properties": { "webhook_url": { "type": "string", "format": "uri", "description": "The incoming webhook URL from Discord (Server settings \u2192 Integrations \u2192 Webhooks) or a Teams workflow. Must be a public HTTPS address", "examples": [ "https://discord.com/api/webhooks/123/abc" ], "maxLength": 2048 } }, "required": [ "webhook_url" ], "title": "ChannelWebhookUrlInput" }, "ComponentImpact": { "type": "string", "description": "How badly an incident affects a component. A component's status is the worst impact it has at the moment.\n| |\n|---|\n| `degraded_performance`
Slower or less reliable than usual. |\n| `partial_outage`
Down for some visitors or some functions. |\n| `major_outage`
Down. |", "enum": [ "degraded_performance", "partial_outage", "major_outage" ], "title": "ComponentImpact" }, "ComponentStatus": { "type": "string", "description": "A status page component's status, derived from incidents and maintenance.\n| |\n|---|\n| `operational`
Working normally. |\n| `degraded_performance`
Slower or less reliable than usual. |\n| `partial_outage`
Down for some visitors or some functions. |\n| `major_outage`
Down. |\n| `under_maintenance`
In planned maintenance. |", "enum": [ "operational", "degraded_performance", "partial_outage", "major_outage", "under_maintenance" ], "title": "ComponentStatus" }, "CreateAlertSource": { "type": "object", "description": "A new alert source. The response has the `webhook_url` (and `email_address`) to configure in\nthe tool.", "properties": { "name": { "type": "string", "description": "Name shown on its alerts, up to 255 characters", "examples": [ "Production Alertmanager" ], "maxLength": 255 }, "type": { "description": "The tool that will send requests\n\n| |\n|---|\n| `webhook`
Spectate's own JSON format, for scripts, CI and anything that can call a URL. |\n| `email`
Emails to the source's own address (subject becomes the alert). |\n| `alertmanager`
Prometheus Alertmanager `webhook_configs`. |\n| `grafana`
Grafana Alerting webhook contact point (Alertmanager format plus Grafana links). |\n| `sentry`
Sentry internal integration webhooks (SaaS and self-hosted), or the legacy WebHooks plugin. |", "$ref": "#/components/schemas/AlertSourceProvider" }, "default_severity": { "description": "Severity of alerts sent without one. Default `high`\n\n| |\n|---|\n| `critical`
Customers are affected right now. |\n| `high`
Serious, needs attention soon. |\n| `medium`
Should be looked at. |\n| `low`
Informational. |", "$ref": "#/components/schemas/Severity" }, "auto_resolve_minutes": { "type": [ "integer", "null" ], "description": "Minutes, 5 to 10080, after which an alert the tool stopped repeating resolves; `null` keeps it until resolved. Default `null`, or 60 for `email` sources", "minimum": 5, "maximum": 10080 }, "secret": { "type": [ "string", "null" ], "description": "Signing secret the tool uses: Sentry client secret, Grafana HMAC secret or Alertmanager bearer token. Write-only", "maxLength": 255 }, "settings": { "description": "Type-specific settings", "$ref": "#/components/schemas/AlertSourceSettingsInput" }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Project whose escalation paths apply when the source has none of its own" }, "escalation_path_ids": { "type": "array", "description": "Escalation paths for the source's alerts", "items": { "type": "string", "format": "uuid" }, "uniqueItems": true } }, "required": [ "name", "type" ], "title": "CreateAlertSource" }, "CreateChannel": { "type": "object", "description": "A new notification channel: a name, a type, and the settings object of that type (`email` for\n`email`, `slack` for `slack`\u2026). Send only that one object. Telegram channels are connected from\nthe dashboard.", "properties": { "name": { "type": "string", "description": "Name shown in escalation paths", "examples": [ "On-call email" ], "maxLength": 255 }, "type": { "description": "Where the channel delivers; `telegram` can't be created through the API", "$ref": "#/components/schemas/ChannelType" }, "enabled": { "type": "boolean", "description": "Whether it delivers from the start. Default `true`" }, "email": { "description": "Settings of an `email` channel", "$ref": "#/components/schemas/ChannelEmail" }, "slack": { "description": "Settings of a `slack` channel", "$ref": "#/components/schemas/ChannelSlackInput" }, "discord": { "description": "Settings of a `discord` channel", "$ref": "#/components/schemas/ChannelWebhookUrlInput" }, "microsoft_teams": { "description": "Settings of a `microsoft_teams` channel", "$ref": "#/components/schemas/ChannelWebhookUrlInput" }, "webhook": { "description": "Settings of a `webhook` channel", "$ref": "#/components/schemas/ChannelWebhookInput" }, "pushover": { "description": "Settings of a `pushover` channel", "$ref": "#/components/schemas/ChannelPushoverInput" }, "sms": { "description": "Settings of an `sms` channel", "$ref": "#/components/schemas/ChannelPhone" }, "voice": { "description": "Settings of a `voice` channel", "$ref": "#/components/schemas/ChannelPhone" } }, "required": [ "name", "type" ], "title": "CreateChannel" }, "CreateDomain": { "type": "object", "description": "A domain to monitor.", "properties": { "name": { "type": "string", "description": "The registered domain, without `www.` or a path; internationalised names may be in Unicode or punycode", "examples": [ "example.com" ], "maxLength": 255 }, "enabled": { "type": "boolean", "description": "Whether to start monitoring at once. Default `true`" }, "expiry_threshold_days": { "type": "integer", "description": "Days before expiry, 1 to 365, that the \"expires soon\" alert fires. Default 30", "examples": [ 30 ], "minimum": 1, "maximum": 365 }, "alert_on_registry_changes": { "type": "boolean", "description": "Raise an alert when the registrar, nameservers or DNSSEC keys change. Default `true`" }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Project to add the domain to; default the team's default project, `null` for none" }, "escalation_path_ids": { "type": "array", "description": "Escalation paths for the domain's alerts. Leave out or send `[]` to follow the project's paths, else the team's default path", "items": { "type": "string", "format": "uuid" } } }, "required": [ "name" ], "title": "CreateDomain" }, "CreateEscalationPath": { "type": "object", "description": "A new escalation path.", "properties": { "name": { "type": "string", "description": "Name, up to 255 characters", "examples": [ "On-call engineers" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "What the path is for, up to 1000 characters", "maxLength": 1000 }, "enabled": { "type": "boolean", "description": "Whether alerts follow the path. Default `true`" }, "is_default": { "type": "boolean", "description": "Make it the team's default path; the current default stops being one. Default `false`" }, "working_hours": { "anyOf": [ { "description": "Working hours for branch conditions and waits; leave out for Monday to Friday 09:00\u201317:00 in the team's time zone", "$ref": "#/components/schemas/WorkingHoursInput" }, { "type": "null" } ] }, "steps": { "type": "array", "description": "The steps, in order, up to 99 in total. Leave out or `[]` for a path that does nothing yet", "items": { "$ref": "#/components/schemas/EscalationStepInput" } } }, "required": [ "name" ], "title": "CreateEscalationPath" }, "CreateIncident": { "type": "object", "description": "A new incident.", "properties": { "title": { "type": "string", "description": "What's going on, up to 255 characters", "examples": [ "Checkout fails for some customers" ], "maxLength": 255 }, "severity": { "description": "How bad it is\n\n| |\n|---|\n| `critical`
Customers are affected right now. |\n| `high`
Serious, needs attention soon. |\n| `medium`
Should be looked at. |\n| `low`
Informational. |", "$ref": "#/components/schemas/Severity" }, "summary": { "type": [ "string", "null" ], "description": "More about it, in Markdown" } }, "required": [ "title", "severity" ], "title": "CreateIncident" }, "CreateIncidentUpdate": { "type": "object", "description": "An update to post to an incident.", "properties": { "body": { "type": "string", "description": "What's known now, in Markdown", "examples": [ "Rolled back the deploy; error rates are dropping." ] }, "status": { "description": "Move the incident to this status with the update; leave out to keep it\n\n| |\n|---|\n| `investigating`
Declared; the cause isn't known yet. |\n| `identified`
Acknowledged: the cause is known and someone works on it. |\n| `monitoring`
A fix is out; watching whether it holds. |\n| `resolved`
Over. |", "$ref": "#/components/schemas/IncidentStatus" } }, "required": [ "body" ], "title": "CreateIncidentUpdate" }, "CreateInvite": { "type": "object", "description": "Someone to invite to the team.", "properties": { "email": { "type": "string", "format": "email", "description": "Their email address; disposable addresses aren't accepted", "examples": [ "jane@example.com" ], "maxLength": 255 }, "role": { "description": "The role they get when they accept (default `member`); `owner` can't be given\n\n| |\n|---|\n| `owner`
Everything, including billing and deleting the team. One per team. |\n| `manager`
Everything but billing and deleting the team. |\n| `admin`
Configure monitoring, alerting, incidents and status pages; can't manage members or API tokens. |\n| `member`
Read everything; manage monitors and incidents, acknowledge alerts. |\n| `billing`
Billing and support only. |", "$ref": "#/components/schemas/TeamRole" } }, "required": [ "email" ], "title": "CreateInvite" }, "CreateMetricCondition": { "type": "object", "description": "A new metric condition. Attach it to hosts, to projects (all their hosts), or both.", "properties": { "metric": { "description": "The metric to watch", "$ref": "#/components/schemas/MetricPoint" }, "condition": { "description": "How the metric's value is compared with `threshold`", "$ref": "#/components/schemas/MetricCondition" }, "threshold": { "type": "number", "description": "Compared with the metric's value as the agent reports it, in the unit the host's charts show", "examples": [ 90 ] }, "severity": { "description": "Severity of the alert it raises\n\n| |\n|---|\n| `critical`
Customers are affected right now. |\n| `high`
Serious, needs attention soon. |\n| `medium`
Should be looked at. |\n| `low`
Informational. |", "$ref": "#/components/schemas/Severity" }, "duration_minutes": { "type": "integer", "description": "Minutes, 0 to 60, the condition must hold before the alert fires. Default 0: on the first breach", "examples": [ 5 ], "minimum": 0, "maximum": 60 }, "host_ids": { "type": "array", "description": "Hosts of the team it applies to", "items": { "type": "string", "format": "uuid" }, "uniqueItems": true }, "project_ids": { "type": "array", "description": "Projects of the team whose hosts it applies to", "items": { "type": "string", "format": "uuid" }, "uniqueItems": true } }, "required": [ "metric", "condition", "threshold", "severity" ], "title": "CreateMetricCondition" }, "CreateMonitor": { "type": "object", "description": "A new monitor. Only `label`, `protocol`, `uri` and `interval` are required; everything else has\na sensible default.", "properties": { "label": { "type": "string", "description": "Name shown in the dashboard, alerts and status pages", "examples": [ "Website" ], "maxLength": 255 }, "protocol": { "description": "What to check; decides the format of `uri`\n\n| |\n|---|\n| `https`
An HTTPS request to the URL in `uri`, with a certificate check. |\n| `http`
An HTTP request to the URL in `uri`. |\n| `icmp`
A ping (ICMP echo) to the host in `uri`. |\n| `tcp`
A TCP connect to `host:port`, optionally with a TLS handshake and a banner keyword. |\n| `dns`
A DNS query for a record of the name in `uri`, optionally compared with expected values. |\n| `smtp`
An SMTP greeting from `host:port` (port optional), with STARTTLS by default. |\n| `imap`
An IMAP greeting from `host:port` (port optional), over TLS by default. |\n| `pop3`
A POP3 greeting from `host:port` (port optional), over TLS by default. |", "$ref": "#/components/schemas/MonitorProtocol" }, "uri": { "type": "string", "description": "The target: a URL for `http` and `https`, a host for `icmp`, `host:port` for `tcp`, `host` or `host:port` for mail, a DNS name for `dns`. Private and reserved addresses are refused. For `http` and `https` the scheme is optional: `example.com/health` and `https://example.com/health` give the same monitor, stored without the scheme. A scheme that differs from `protocol` (`http://` for an `https` monitor) is refused with `422`", "examples": [ "https://example.com/health" ], "maxLength": 2048 }, "interval": { "description": "Seconds between checks. Plans set the shortest allowed interval (`422` below it)", "$ref": "#/components/schemas/MonitorInterval" }, "enabled": { "type": "boolean", "description": "Whether the monitor starts running at once. Default `true`" }, "primary_location": { "description": "Region the checks run from. Default `eu`\n\n| |\n|---|\n| `eu`
Europe. |\n| `us`
North America. |\n| `as`
Asia. |\n| `oc`
Oceania. |", "$ref": "#/components/schemas/MonitorLocation" }, "timeout": { "type": "integer", "description": "Seconds before a check times out, 1 to 60. Default 30", "examples": [ 30 ], "minimum": 1, "maximum": 60 }, "max_redirects": { "type": [ "integer", "null" ], "description": "HTTP: redirects to follow, 0 to 10; `null` follows up to 10", "minimum": 0, "maximum": 10 }, "headers": { "type": "array", "description": "HTTP: up to 25 headers to send", "items": { "$ref": "#/components/schemas/MonitorHeader" } }, "advanced_settings": { "description": "Protocol-specific settings", "$ref": "#/components/schemas/MonitorAdvancedSettingsInput" }, "allow_insecure_requests": { "type": "boolean", "description": "HTTPS: accept invalid certificates for the check itself. Default `false`" }, "expected_http_status_code": { "type": [ "string", "null" ], "description": "HTTP: status codes that count as up, comma-separated, `*` as a wildcard digit; `null` accepts 2xx and 3xx", "examples": [ "2**,301" ], "minLength": 1, "maxLength": 200 }, "certificate_check_enabled": { "type": "boolean", "description": "Check the TLS certificate for validity and expiry (HTTPS, and TCP or mail with TLS). Default `false`" }, "certificate_expiry_threshold_days": { "type": "integer", "description": "Days before the certificate expires that the \"expires soon\" alert fires, 1 to 90. Default 14", "examples": [ 14 ], "minimum": 1, "maximum": 90 }, "performance_check_enabled": { "type": "boolean", "description": "Raise alerts for slow responses. Default `false`" }, "performance_hard_threshold": { "type": [ "integer", "null" ], "description": "Milliseconds, 1 to 30000: a response slower than this raises an alert", "examples": [ 2000 ], "minimum": 1, "maximum": 30000 }, "performance_deviation_percentage": { "type": [ "integer", "null" ], "description": "Percent, 1 to 500: alert when recent response times are this much above the earlier ones (see the two timeframes)", "examples": [ 50 ], "minimum": 1, "maximum": 500 }, "performance_deviation_timeframe": { "type": [ "integer", "null" ], "description": "Minutes of recent checks to compare: 15, 30, 45, 60, 75, 90, 105 or 120. Must be shorter than `performance_deviation_before_timeframe`", "examples": [ 30 ], "minimum": 15, "maximum": 120 }, "performance_deviation_before_timeframe": { "type": [ "integer", "null" ], "description": "Minutes before those to compare with, a whole number of hours from 60 to 1440", "examples": [ 240 ], "minimum": 60, "maximum": 1440 }, "regional_performance_enabled": { "type": "boolean", "description": "Also measure response time from the regions other than `primary_location`, every minute (or at the interval, when longer). Shown with the monitor's performance; not used for uptime or alerts. Team plan and up. Default `false`" }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Project to add the monitor to; default the team's default project, `null` for none" }, "escalation_path_ids": { "type": "array", "description": "Escalation paths for the monitor's alerts. Leave out or send `[]` to follow the project's paths, else the team's default path", "items": { "type": "string", "format": "uuid" } } }, "required": [ "label", "protocol", "uri", "interval" ], "title": "CreateMonitor" }, "CreateOnCallOverride": { "type": "object", "description": "Someone to cover a schedule for a while, at most 90 days.", "properties": { "member_id": { "type": "string", "format": "uuid", "description": "The member who covers" }, "starts_at": { "type": "string", "format": "date-time", "description": "From when, as an ISO 8601 date and time" }, "ends_at": { "type": "string", "format": "date-time", "description": "Until when; after `starts_at`" }, "note": { "type": [ "string", "null" ], "description": "Why, for the team; up to 500 characters", "examples": [ "Covering for Jane's holiday" ], "maxLength": 500 } }, "required": [ "member_id", "starts_at", "ends_at" ], "title": "CreateOnCallOverride" }, "CreateOnCallRotation": { "type": "object", "description": "A new rotation layer of a schedule.", "properties": { "name": { "type": "string", "description": "Name, up to 255 characters", "examples": [ "Weekly primary" ], "maxLength": 255 }, "position": { "type": "integer", "description": "Layer order, 0 for the top. Default: below the existing layers", "minimum": 0, "maximum": 100 }, "shift_unit": { "description": "The unit of the shift length\n\n| |\n|---|\n| `hours`
Absolute hours: shifts keep their length across DST changes. |\n| `days`
Calendar days in the schedule's time zone: the handoff stays at the same wall-clock time. |\n| `weeks`
Calendar weeks in the schedule's time zone. |", "$ref": "#/components/schemas/OnCallShiftUnit" }, "shift_length": { "type": "integer", "description": "Shift length in `shift_unit`s: up to 720 hours, 90 days or 12 weeks", "examples": [ 1 ], "minimum": 1, "maximum": 720 }, "start_date": { "type": "string", "format": "date", "description": "The first handoff's date in the schedule's time zone; turns are counted from it", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "examples": [ "2026-11-02" ] }, "handoff_time": { "type": "string", "description": "Handoff time as `HH:MM` in the schedule's time zone", "examples": [ "09:00" ] }, "restrictions": { "anyOf": [ { "description": "A weekly window the layer covers; leave out for round the clock", "$ref": "#/components/schemas/OnCallRestrictionsInput" }, { "type": "null" } ] }, "participant_ids": { "type": "array", "description": "1 to 50 team members taking turns, in order", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "uniqueItems": true } }, "required": [ "name", "shift_unit", "shift_length", "start_date", "handoff_time" ], "title": "CreateOnCallRotation" }, "CreateOnCallSchedule": { "type": "object", "description": "A new on-call schedule. Add rotation layers to it afterwards.", "properties": { "name": { "type": "string", "description": "Name, up to 255 characters", "examples": [ "Primary" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "What the schedule covers, up to 1000 characters", "maxLength": 1000 }, "timezone": { "type": "string", "description": "IANA time zone the rotations' dates, handoffs and restrictions are in", "examples": [ "Europe/Amsterdam" ] } }, "required": [ "name", "timezone" ], "title": "CreateOnCallSchedule" }, "CreateProject": { "type": "object", "description": "A new project.", "properties": { "name": { "type": "string", "description": "Project name", "examples": [ "Production" ], "maxLength": 255 }, "escalation_path_ids": { "type": "array", "description": "Escalation paths for alerts of the project's monitors and hosts. Leave out for none", "items": { "type": "string", "format": "uuid" }, "uniqueItems": true } }, "required": [ "name" ], "title": "CreateProject" }, "CreateScheduledMaintenance": { "type": "object", "description": "Maintenance to announce on a status page.", "properties": { "title": { "type": "string", "description": "Title shown on the page, up to 255 characters", "examples": [ "Database upgrade" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "What happens and what visitors notice, in Markdown; `null` for none", "examples": [ "The API is read-only for about ten minutes." ] }, "scheduled_at": { "type": "string", "format": "date-time", "description": "Planned start, in the future" }, "scheduled_until": { "type": [ "string", "null" ], "format": "date-time", "description": "Planned end, after `scheduled_at`; `null` for none" }, "automatic": { "type": "boolean", "description": "`true` (default): starts at `scheduled_at` and completes at `scheduled_until` by itself (without a planned end, complete it by setting `status`). `false`: only changes when you set `status`" }, "affected_components": { "type": "array", "description": "Components it affects; components of the status page only", "items": { "$ref": "#/components/schemas/StatusPageAffectedComponentInput" } }, "notify_subscribers": { "type": "boolean", "description": "Email confirmed subscribers about it (default `true`)" } }, "required": [ "title", "scheduled_at" ], "title": "CreateScheduledMaintenance" }, "CreateStatusPage": { "type": "object", "description": "A new status page. Settings left out get their defaults.", "properties": { "name": { "type": "string", "description": "Name, shown as the page title", "examples": [ "Acme status" ], "maxLength": 255 }, "slug": { "type": "string", "description": "The page's subdomain under spectate.page: lowercase letters, digits and dashes. Leave out to derive it from the name", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$", "examples": [ "acme" ], "maxLength": 63 }, "visibility": { "description": "Who can open the page. Private pages are part of the Team plan and up (`403` `PLAN_FEATURE_UNAVAILABLE`)\n\n| |\n|---|\n| `public`
Anyone. |\n| `private`
Visitors with the access link, or the password when the page has one. Part of the Team plan and up. |", "$ref": "#/components/schemas/StatusPageVisibility" }, "custom_domain": { "type": [ "string", "null" ], "description": "Your own domain for the page, such as `status.acme.com`; `null` for none. Part of paid plans (`403` `PLAN_FEATURE_UNAVAILABLE` otherwise). A new domain needs to be verified again: see `custom_domain_verification` and `verifyStatusPageCustomDomain`", "examples": [ "status.acme.com" ], "maxLength": 253 }, "password_protected": { "type": "boolean", "description": "Let visitors of a private page also get in with a password. Part of paid plans (`403` `PLAN_FEATURE_UNAVAILABLE` otherwise); turning it on needs a `password` unless the page has one" }, "password": { "type": [ "string", "null" ], "description": "The password, 8 to 255 characters. Write-only; leave out or send `null` to keep the current one", "examples": [ "correct-horse-battery" ], "minLength": 8, "maxLength": 255 }, "language": { "description": "Language of the public page and of subscriber emails\n\n| |\n|---|\n| `en`
English. |\n| `nl`
Dutch. |\n| `de`
German. |\n| `fr`
French. |\n| `es`
Spanish. |\n| `it`
Italian. |", "$ref": "#/components/schemas/StatusPageLanguage" }, "match_browser_language": { "type": "boolean", "description": "Give visitors their browser's language when it is supported" }, "theme": { "description": "How the page looks and what it shows", "$ref": "#/components/schemas/StatusPageThemeInput" }, "collapsed_groups": { "type": "array", "description": "Component groups that start collapsed; replaces the current list", "items": { "type": "string", "maxLength": 255 }, "maxItems": 100, "uniqueItems": true }, "automation_enabled": { "type": "boolean", "description": "Monitor automation: when a monitor linked to a component goes down, open an incident \"{component} is down\" (major outage), and resolve it when the monitor recovers" }, "automation_down_message": { "type": [ "string", "null" ], "description": "Posted when a linked monitor goes down, up to 5000 characters; `{component}` and `{status_page}` are filled in. `null` for a default message", "examples": [ "We're looking into problems with {component}." ], "maxLength": 5000 }, "automation_recovered_message": { "type": [ "string", "null" ], "description": "Posted when the monitor recovers, up to 5000 characters; `null` for a default message", "examples": [ "{component} is working again." ], "maxLength": 5000 }, "issue_reports_enabled": { "type": "boolean", "description": "Let visitors report problems from the page" }, "issue_reports_show_on_page": { "type": "boolean", "description": "While reports are above the threshold, say on the page that users are reporting issues" }, "issue_reports_alerts_enabled": { "type": "boolean", "description": "Fire an alert when reports reach the threshold" }, "issue_reports_threshold": { "type": "integer", "description": "Reports within `issue_reports_window_minutes` that count as above the threshold, 1 to 1000", "minimum": 1, "maximum": 1000 }, "issue_reports_window_minutes": { "type": "integer", "description": "The window for the threshold, in minutes, 1 to 1440", "minimum": 1, "maximum": 1440 }, "traffic_alerts_enabled": { "type": "boolean", "description": "Alert when views reach `traffic_alert_multiplier` times the usual views for the time of day" }, "traffic_alert_multiplier": { "type": "integer", "description": "How many times the usual views alert, 2 to 100", "minimum": 2, "maximum": 100 }, "traffic_alert_min_views": { "type": "integer", "description": "Fewer views than this in 15 minutes never alert, 10 to 1000000", "minimum": 10, "maximum": 1000000 }, "escalation_path_ids": { "type": "array", "description": "Escalation paths for the page's alerts (issue reports and traffic spikes); replaces the current ones. Empty for the team's default path", "items": { "type": "string", "format": "uuid" } } }, "required": [ "name" ], "title": "CreateStatusPage" }, "CreateStatusPageComponent": { "type": "object", "description": "A new component of a status page. Its status follows incidents and maintenance.", "properties": { "name": { "type": "string", "description": "Name shown on the page", "examples": [ "API" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Text shown with the name; `null` for none", "examples": [ "Our public REST API." ] }, "group": { "type": [ "string", "null" ], "description": "Group to show the component in; `null` for the page's default group", "examples": [ "Backend" ], "maxLength": 255 }, "position": { "type": "integer", "description": "Order within the group, lowest first, from 0. New components go last when left out", "minimum": 0 }, "monitor_id": { "type": [ "string", "null" ], "format": "uuid", "description": "A monitor of the team whose uptime history and response times the component shows, and whose downtime opens an incident when monitor automation is on; `null` for none" }, "show_latency_chart": { "type": "boolean", "description": "Show the monitor's response time chart under the component" } }, "required": [ "name" ], "title": "CreateStatusPageComponent" }, "CreateStatusPageImpactPeriod": { "type": "object", "description": "A period during which a public incident affected a component. Periods of one component may not\noverlap within the incident.", "properties": { "component_id": { "type": "string", "format": "uuid", "description": "A component of the status page" }, "impact": { "description": "How badly\n\n| |\n|---|\n| `degraded_performance`
Slower or less reliable than usual. |\n| `partial_outage`
Down for some visitors or some functions. |\n| `major_outage`
Down. |", "$ref": "#/components/schemas/ComponentImpact" }, "started_at": { "type": "string", "format": "date-time", "description": "When it started, now or in the past" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it ended, after `started_at` and not in the future; `null` or left out while it goes on" } }, "required": [ "component_id", "impact", "started_at" ], "title": "CreateStatusPageImpactPeriod" }, "CreateStatusPageIncident": { "type": "object", "description": "A new public incident on a status page.", "properties": { "title": { "type": "string", "description": "Title shown on the page", "examples": [ "Elevated API error rates" ], "maxLength": 255 }, "status": { "description": "Where it stands\n\n| |\n|---|\n| `investigating`
Declared; the cause isn't known yet. |\n| `identified`
Acknowledged: the cause is known and someone works on it. |\n| `monitoring`
A fix is out; watching whether it holds. |\n| `resolved`
Over. |", "$ref": "#/components/schemas/IncidentStatus" }, "body": { "type": [ "string", "null" ], "description": "The first update, in Markdown. Leave out to create the incident without one", "examples": [ "We're looking into errors on the API." ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it happened, now or in the past (default now)" }, "impact": { "description": "The incident's own impact, used while it affects no components; otherwise it follows the components\n\n| |\n|---|\n| `none`
No impact (for a component: not affected). |\n| `degraded_performance`
Slower or less reliable than usual. |\n| `partial_outage`
Down for some visitors or some functions. |\n| `major_outage`
Down. |", "$ref": "#/components/schemas/ImpactLevel" }, "incident_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The team's incident this one is for; `null` for none. Publishing from that incident (`publishIncidentStatusPageUpdate`) then posts here" }, "affected_components": { "type": "array", "description": "The components it affects as of `published_at`, with their impact; components left out are no longer affected. Leave out to keep the impacts as they are; send `[]` for none. Components of the status page only", "items": { "$ref": "#/components/schemas/StatusPageAffectedComponentInput" } }, "notify_subscribers": { "type": "boolean", "description": "Email confirmed subscribers about the new incident (default `true`). `false` changes the page without emails" } }, "required": [ "title", "status" ], "title": "CreateStatusPageIncident" }, "CreateStatusPageIncidentUpdate": { "type": "object", "description": "An update to publish on a public incident.", "properties": { "status": { "description": "The incident's status with this update. `resolved` closes every open impact period\n\n| |\n|---|\n| `investigating`
Declared; the cause isn't known yet. |\n| `identified`
Acknowledged: the cause is known and someone works on it. |\n| `monitoring`
A fix is out; watching whether it holds. |\n| `resolved`
Over. |", "$ref": "#/components/schemas/IncidentStatus" }, "body": { "type": "string", "description": "The message, in Markdown", "examples": [ "We found the cause and are rolling out a fix." ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it happened, now or in the past (default now)" }, "affected_components": { "type": "array", "description": "The components it affects as of `published_at`, with their impact; components left out are no longer affected. Leave out to keep the impacts as they are; send `[]` for none. Components of the status page only", "items": { "$ref": "#/components/schemas/StatusPageAffectedComponentInput" } }, "notify_subscribers": { "type": "boolean", "description": "Email confirmed subscribers about the update (default `true`). `false` changes the page without emails" } }, "required": [ "status", "body" ], "title": "CreateStatusPageIncidentUpdate" }, "DnsMatch": { "type": "string", "description": "How a DNS monitor compares the answer with `dns_expected_values`.\n| |\n|---|\n| `contains`
Every expected value is in the answer; the answer may have more. |\n| `exact`
The answer is exactly the expected values, in any order. |", "enum": [ "contains", "exact" ], "title": "DnsMatch" }, "DnsRecordType": { "type": "string", "description": "The DNS record type a DNS monitor queries.\n", "enum": [ "A", "AAAA", "CNAME", "MX", "NS", "TXT", "CAA", "SOA" ], "title": "DnsRecordType" }, "Domain": { "type": "object", "description": "A monitored domain registration: Spectate looks it up at its registry (RDAP or WHOIS) every few hours\nand alerts before it expires and, optionally, when its registrar, nameservers or DNSSEC change.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Domain ID" }, "name": { "type": "string", "description": "The registered domain, lowercase, internationalised names in punycode", "examples": [ "example.com" ] }, "enabled": { "type": "boolean", "description": "Whether the domain is monitored. `false` when paused by a member or by the system (see `paused_reason`)" }, "paused_reason": { "anyOf": [ { "description": "Why the system paused it; `null` when a member paused it or it runs\n\n| |\n|---|\n| `plan_limit`
Over the plan limit (trial expired, downgrade); the oldest resources stay active. |\n| `team_paused`
The whole team's monitoring is paused (no paid plan, staff action or scheduled deletion). |", "$ref": "#/components/schemas/ResourcePauseReason" }, { "type": "null" } ] }, "registrar": { "type": [ "string", "null" ], "description": "The registrar, as the registry reports it", "examples": [ "Example Registrar, Inc." ] }, "registered_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the domain was registered" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the registration expires" }, "registry_changed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the registration last changed at the registry" }, "days_until_expiration": { "type": [ "integer", "null" ], "description": "Days until the registration expires; negative once expired", "examples": [ 212 ] }, "is_expired": { "type": "boolean", "description": "Whether the registration has expired" }, "is_expiring_soon": { "type": "boolean", "description": "Whether it expires within `expiry_threshold_days`" }, "nameservers": { "type": [ "array", "null" ], "description": "The domain's nameservers", "items": { "type": "string" } }, "dnssec": { "type": "boolean", "description": "Whether the registry publishes DNSSEC keys for the domain" }, "dnssec_keys": { "type": [ "array", "null" ], "description": "The DNSSEC delegation signer records", "items": { "$ref": "#/components/schemas/DomainDnssecKey" } }, "statuses": { "type": [ "array", "null" ], "description": "EPP status codes, for example `client transfer prohibited`", "items": { "type": "string" } }, "registry_source": { "anyOf": [ { "description": "Where the registry data came from; `null` before the first lookup\n\n| |\n|---|\n| `rdap`
The registry's RDAP service. |\n| `whois`
The registry's WHOIS server, for registries without RDAP. |", "$ref": "#/components/schemas/DomainRegistrySource" }, { "type": "null" } ] }, "registry_error": { "anyOf": [ { "description": "Why the last lookup gave no data; `null` when it did\n\n| |\n|---|\n| `unsupported`
The registry publishes neither RDAP nor WHOIS (e.g. .gr, .vn). |\n| `not_registered`
The registry has no such domain: not registered (or a subdomain was entered). |\n| `unavailable`
The registry didn't answer usefully, even after retries; tried again at the next check. |", "$ref": "#/components/schemas/DomainLookupError" }, { "type": "null" } ] }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the registry was last checked" }, "expiry_threshold_days": { "type": "integer", "description": "Days before expiry that the \"expires soon\" alert fires", "examples": [ 30 ] }, "alert_on_registry_changes": { "type": "boolean", "description": "Whether changes of the registrar, nameservers or DNSSEC keys raise an alert" }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The project the domain belongs to; `null` for none" }, "escalation_paths": { "type": "array", "description": "Escalation paths the domain's alerts follow. Empty: the project's paths, else the team's default path", "items": { "$ref": "#/components/schemas/EscalationPathReference" } }, "created_at": { "type": "string", "format": "date-time", "description": "When monitoring of the domain started" } }, "required": [ "id", "name", "enabled", "paused_reason", "registrar", "registered_at", "expires_at", "registry_changed_at", "days_until_expiration", "is_expired", "is_expiring_soon", "nameservers", "dnssec", "dnssec_keys", "statuses", "registry_source", "registry_error", "last_checked_at", "expiry_threshold_days", "alert_on_registry_changes", "project_id", "escalation_paths", "created_at" ], "title": "Domain" }, "DomainDnssecKey": { "type": "object", "description": "A DNSSEC delegation signer (DS) record the registry publishes for the domain.", "properties": { "key_tag": { "type": [ "integer", "null" ], "description": "Key tag of the DNSKEY the record points at", "examples": [ 2371 ] }, "algorithm": { "type": [ "integer", "null" ], "description": "DNSSEC algorithm number, for example 13 (ECDSA P-256 with SHA-256)", "examples": [ 13 ] }, "digest_type": { "type": [ "integer", "null" ], "description": "Digest type number, for example 2 (SHA-256)", "examples": [ 2 ] }, "digest": { "type": [ "string", "null" ], "description": "The digest, in hexadecimal" } }, "required": [ "key_tag", "algorithm", "digest_type", "digest" ], "title": "DomainDnssecKey" }, "DomainLookupError": { "type": "string", "description": "Why the last registry lookup of a domain gave no data.\n| |\n|---|\n| `unsupported`
The registry publishes neither RDAP nor WHOIS (e.g. .gr, .vn). |\n| `not_registered`
The registry has no such domain: not registered (or a subdomain was entered). |\n| `unavailable`
The registry didn't answer usefully, even after retries; tried again at the next check. |", "enum": [ "unsupported", "not_registered", "unavailable" ], "title": "DomainLookupError" }, "DomainRegistrySource": { "type": "string", "description": "Where a domain's registry data came from.\n| |\n|---|\n| `rdap`
The registry's RDAP service. |\n| `whois`
The registry's WHOIS server, for registries without RDAP. |", "enum": [ "rdap", "whois" ], "title": "DomainRegistrySource" }, "DomainView": { "type": "string", "description": "Domain list views; a domain can be in several.\n| |\n|---|\n| `attention`
Expired, or expiring within its `expiry_threshold_days`. |\n| `unsigned`
No DNSSEC keys. |\n| `paused`
Monitoring is paused. |", "enum": [ "attention", "unsigned", "paused" ], "title": "DomainView" }, "EscalationCondition": { "type": "object", "description": "A condition of a branch. The branch continues on its `then` side when every condition holds,\nelse on its `else` side.", "properties": { "field": { "description": "What is tested\n\n| |\n|---|\n| `severity`
|\n| `working_hours`
Whether the branch is reached inside the path's working hours. |\n| `source`
The kind of check or integration that raised the alert (uptime, certificate, external\u2026). |\n| `label`
A label sent along by an alert source (`metadata.labels`), e.g. `env=production`. |", "$ref": "#/components/schemas/EscalationConditionField" }, "operator": { "description": "How it's tested; each field allows some operators (see the operator values)\n\n| |\n|---|\n| `is_one_of`
The value is one of `values`. |\n| `is_not_one_of`
The value is none of `values`. |\n| `within`
Reached inside the path's working hours. |\n| `outside`
Reached outside the path's working hours. |\n| `exists`
The label is set. |\n| `not_exists`
The label isn't set. |", "$ref": "#/components/schemas/EscalationConditionOperator" }, "key": { "type": [ "string", "null" ], "description": "`label` conditions: the label name sent by the alert source", "examples": [ "env" ] }, "values": { "type": "array", "description": "Values to match, for `is_one_of` and `is_not_one_of`: severities (`critical`, `high`, `medium`, `low`), sources (`uptime`, `performance`, `certificate`, `dns`, `domain`, `host_metric`, `status_page`, `external`, or `external:` such as `external:grafana`) or label values", "items": { "type": "string" } }, "description": { "type": "string", "description": "The condition in words", "examples": [ "Severity is Critical or High" ] } }, "required": [ "field", "operator", "key", "values", "description" ], "title": "EscalationCondition" }, "EscalationConditionField": { "type": "string", "description": "What an escalation branch can test about an alert (incident.io-style \"if/else\" branches).\n| |\n|---|\n| `severity`
|\n| `working_hours`
Whether the branch is reached inside the path's working hours. |\n| `source`
The kind of check or integration that raised the alert (uptime, certificate, external\u2026). |\n| `label`
A label sent along by an alert source (`metadata.labels`), e.g. `env=production`. |", "enum": [ "severity", "working_hours", "source", "label" ], "title": "EscalationConditionField" }, "EscalationConditionInput": { "type": "object", "description": "A condition of a branch. `severity` and `source` take `is_one_of` and `is_not_one_of` with\n`values`; `working_hours` takes `within` and `outside`; `label` takes a `key` and any of the\nfour list and presence operators.", "properties": { "field": { "description": "What to test\n\n| |\n|---|\n| `severity`
|\n| `working_hours`
Whether the branch is reached inside the path's working hours. |\n| `source`
The kind of check or integration that raised the alert (uptime, certificate, external\u2026). |\n| `label`
A label sent along by an alert source (`metadata.labels`), e.g. `env=production`. |", "$ref": "#/components/schemas/EscalationConditionField" }, "operator": { "description": "How to test it\n\n| |\n|---|\n| `is_one_of`
The value is one of `values`. |\n| `is_not_one_of`
The value is none of `values`. |\n| `within`
Reached inside the path's working hours. |\n| `outside`
Reached outside the path's working hours. |\n| `exists`
The label is set. |\n| `not_exists`
The label isn't set. |", "$ref": "#/components/schemas/EscalationConditionOperator" }, "key": { "type": [ "string", "null" ], "description": "`label` conditions: the label name sent by the alert source, up to 100 characters", "examples": [ "env" ], "maxLength": 100 }, "values": { "type": "array", "description": "Up to 20 values to match, for `is_one_of` and `is_not_one_of`: severities, sources (`uptime`, `external:grafana`\u2026) or label values", "items": { "type": "string", "maxLength": 255 }, "maxItems": 20 } }, "required": [ "field", "operator" ], "title": "EscalationConditionInput" }, "EscalationConditionInputRequest": { "type": "object", "description": "A condition of a branch. `severity` and `source` take `is_one_of` and `is_not_one_of` with\n`values`; `working_hours` takes `within` and `outside`; `label` takes a `key` and any of the\nfour list and presence operators.", "properties": { "field": { "description": "What to test\n\n| |\n|---|\n| `severity`
|\n| `working_hours`
Whether the branch is reached inside the path's working hours. |\n| `source`
The kind of check or integration that raised the alert (uptime, certificate, external\u2026). |\n| `label`
A label sent along by an alert source (`metadata.labels`), e.g. `env=production`. |", "$ref": "#/components/schemas/EscalationConditionField" }, "operator": { "description": "How to test it\n\n| |\n|---|\n| `is_one_of`
The value is one of `values`. |\n| `is_not_one_of`
The value is none of `values`. |\n| `within`
Reached inside the path's working hours. |\n| `outside`
Reached outside the path's working hours. |\n| `exists`
The label is set. |\n| `not_exists`
The label isn't set. |", "$ref": "#/components/schemas/EscalationConditionOperator" }, "key": { "type": [ "string", "null" ], "description": "`label` conditions: the label name sent by the alert source, up to 100 characters", "examples": [ "env" ], "maxLength": 100 }, "values": { "type": "array", "description": "Up to 20 values to match, for `is_one_of` and `is_not_one_of`: severities, sources (`uptime`, `external:grafana`\u2026) or label values", "items": { "type": "string", "maxLength": 255 }, "maxItems": 20 } }, "required": [ "field", "operator" ], "title": "EscalationConditionInputRequest" }, "EscalationConditionOperator": { "type": "string", "description": "How an escalation branch condition tests its field. `severity` and `source` take `is_one_of` and `is_not_one_of`; `working_hours` takes `within` and `outside`; `label` takes all four list and presence operators.\n| |\n|---|\n| `is_one_of`
The value is one of `values`. |\n| `is_not_one_of`
The value is none of `values`. |\n| `within`
Reached inside the path's working hours. |\n| `outside`
Reached outside the path's working hours. |\n| `exists`
The label is set. |\n| `not_exists`
The label isn't set. |", "enum": [ "is_one_of", "is_not_one_of", "within", "outside", "exists", "not_exists" ], "title": "EscalationConditionOperator" }, "EscalationDelayUntil": { "type": "string", "description": "Instead of a fixed delay, an escalation step can wait for the path's working hours to begin (no wait during working hours) or to end (no wait outside them).\n| |\n|---|\n| `working_hours_start`
Wait until working hours begin; no wait during working hours. |\n| `working_hours_end`
Wait until working hours end; no wait outside them. |", "enum": [ "working_hours_start", "working_hours_end" ], "title": "EscalationDelayUntil" }, "EscalationPath": { "type": "object", "description": "An escalation path: what happens when an alert fires, step by step, until someone acknowledges\nit. Monitors, hosts, domains and alert sources use their own paths, their project's, or the\nteam's default path.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Escalation path ID" }, "name": { "type": "string", "description": "Name", "examples": [ "On-call engineers" ] }, "description": { "type": [ "string", "null" ], "description": "What the path is for" }, "enabled": { "type": "boolean", "description": "Whether alerts follow the path. Alerts of a disabled path don't escalate" }, "is_default": { "type": "boolean", "description": "Whether this is the team's default path, for resources without paths of their own or of their project. One per team" }, "working_hours": { "description": "The working hours that branch conditions and \"until working hours\" waits use", "$ref": "#/components/schemas/WorkingHours" }, "steps": { "type": "array", "description": "The steps, in order; a `branch` continues in its `then` and `else` steps", "items": { "$ref": "#/components/schemas/EscalationStep" } }, "warnings": { "type": "array", "description": "Problems that keep the path from reaching someone; empty when it can deliver", "items": { "$ref": "#/components/schemas/EscalationPathWarning" } }, "created_at": { "type": "string", "format": "date-time", "description": "When the path was created" } }, "required": [ "id", "name", "description", "enabled", "is_default", "working_hours", "steps", "warnings", "created_at" ], "title": "EscalationPath" }, "EscalationPathReference": { "type": "object", "description": "An escalation path a resource's alerts follow.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Escalation path ID" }, "name": { "type": "string", "description": "Escalation path name", "examples": [ "On-call engineers" ] } }, "required": [ "id", "name" ], "title": "EscalationPathReference" }, "EscalationPathWarning": { "type": "object", "description": "A delivery problem of an escalation path.", "properties": { "code": { "description": "What's wrong\n\n| |\n|---|\n| `no_deliverable_steps`
Every notify step targets a disabled channel or a deleted schedule: alerts reach nobody. |\n| `disabled_channels`
Some channels are disabled; their steps are skipped. |\n| `missing_schedules`
An on-call step's schedule was deleted; the step is skipped. |", "$ref": "#/components/schemas/EscalationPathWarningCode" }, "message": { "type": "string", "description": "The problem in words", "examples": [ "Channel Ops Slack is disabled and will be skipped." ] } }, "required": [ "code", "message" ], "title": "EscalationPathWarning" }, "EscalationPathWarningCode": { "type": "string", "description": "A problem that keeps an escalation path from reaching someone.\n| |\n|---|\n| `no_deliverable_steps`
Every notify step targets a disabled channel or a deleted schedule: alerts reach nobody. |\n| `disabled_channels`
Some channels are disabled; their steps are skipped. |\n| `missing_schedules`
An on-call step's schedule was deleted; the step is skipped. |", "enum": [ "no_deliverable_steps", "disabled_channels", "missing_schedules" ], "title": "EscalationPathWarningCode" }, "EscalationStep": { "type": "object", "description": "A step of an escalation path. Steps run in order, each after its wait. A `branch` is always\nthe last step of its list: alerts go on with its `then` steps when its conditions hold, else\nwith its `else` steps.", "properties": { "type": { "description": "What the step does\n\n| |\n|---|\n| `notify_channel`
Send the alert to a channel. |\n| `create_incident`
Declare an incident for the alert. |\n| `notify_on_call`
Page whoever is on call in a schedule, by email and their own phone. |\n| `branch`
If/else: alerts meeting every condition continue on its `then` side, the rest on its `else` side. |", "$ref": "#/components/schemas/EscalationStepAction" }, "delay_minutes": { "type": [ "integer", "null" ], "description": "Minutes to wait before the step runs; `null` for a branch (decided at once) or when `delay_until` applies", "examples": [ 5 ] }, "delay_until": { "anyOf": [ { "description": "Wait for the path's working hours to begin or end instead of `delay_minutes`\n\n| |\n|---|\n| `working_hours_start`
Wait until working hours begin; no wait during working hours. |\n| `working_hours_end`
Wait until working hours end; no wait outside them. |", "$ref": "#/components/schemas/EscalationDelayUntil" }, { "type": "null" } ] }, "channel": { "anyOf": [ { "description": "`notify_channel` steps: the channel; `null` when it was deleted (the step is skipped)", "$ref": "#/components/schemas/ChannelReference" }, { "type": "null" } ] }, "schedule": { "anyOf": [ { "description": "`notify_on_call` steps: the schedule whose person on call is paged; `null` when it was deleted (the step is skipped)", "$ref": "#/components/schemas/OnCallScheduleReference" }, { "type": "null" } ] }, "conditions": { "type": [ "array", "null" ], "description": "`branch` steps: the conditions; all must hold for `then`", "items": { "$ref": "#/components/schemas/EscalationCondition" } }, "then": { "type": [ "array", "null" ], "description": "`branch` steps: what happens when the conditions hold", "items": { "$ref": "#/components/schemas/EscalationStep" } }, "else": { "type": [ "array", "null" ], "description": "`branch` steps: what happens otherwise", "items": { "$ref": "#/components/schemas/EscalationStep" } } }, "required": [ "type", "delay_minutes", "delay_until", "channel", "schedule", "conditions", "then", "else" ], "title": "EscalationStep" }, "EscalationStepAction": { "type": "string", "description": "What an escalation step does.\n| |\n|---|\n| `notify_channel`
Send the alert to a channel. |\n| `create_incident`
Declare an incident for the alert. |\n| `notify_on_call`
Page whoever is on call in a schedule, by email and their own phone. |\n| `branch`
If/else: alerts meeting every condition continue on its `then` side, the rest on its `else` side. |", "enum": [ "notify_channel", "create_incident", "notify_on_call", "branch" ], "title": "EscalationStepAction" }, "EscalationStepInput": { "type": "object", "description": "A step to run. `notify_channel` needs `channel_id`, `notify_on_call` needs `schedule_id`,\n`branch` needs `conditions` and ends its list: what follows goes in its `then` and `else`.", "properties": { "type": { "description": "What the step does\n\n| |\n|---|\n| `notify_channel`
Send the alert to a channel. |\n| `create_incident`
Declare an incident for the alert. |\n| `notify_on_call`
Page whoever is on call in a schedule, by email and their own phone. |\n| `branch`
If/else: alerts meeting every condition continue on its `then` side, the rest on its `else` side. |", "$ref": "#/components/schemas/EscalationStepAction" }, "delay_minutes": { "type": "integer", "description": "Minutes, 0 to 1440, to wait before the step runs. Default 0. Not for branches", "examples": [ 5 ], "minimum": 0, "maximum": 1440 }, "delay_until": { "anyOf": [ { "description": "Wait for the path's working hours to begin or end instead of `delay_minutes`. Not for branches\n\n| |\n|---|\n| `working_hours_start`
Wait until working hours begin; no wait during working hours. |\n| `working_hours_end`
Wait until working hours end; no wait outside them. |", "$ref": "#/components/schemas/EscalationDelayUntil" }, { "type": "null" } ] }, "channel_id": { "type": "string", "format": "uuid", "description": "`notify_channel`: the channel to send to" }, "schedule_id": { "type": "string", "format": "uuid", "description": "`notify_on_call`: the schedule whose person on call is paged (on-call is part of the Team plan and up)" }, "conditions": { "type": "array", "description": "`branch`: 1 to 10 conditions; all must hold for `then`", "items": { "$ref": "#/components/schemas/EscalationConditionInput" } }, "then": { "type": "array", "description": "`branch`: the steps when the conditions hold; empty ends the escalation there", "items": { "$ref": "#/components/schemas/EscalationStepInput" } }, "else": { "type": "array", "description": "`branch`: the steps otherwise; empty ends the escalation there", "items": { "$ref": "#/components/schemas/EscalationStepInput" } } }, "required": [ "type" ], "title": "EscalationStepInput" }, "EscalationStepInputRequest": { "type": "object", "description": "A step to run. `notify_channel` needs `channel_id`, `notify_on_call` needs `schedule_id`,\n`branch` needs `conditions` and ends its list: what follows goes in its `then` and `else`.", "properties": { "type": { "description": "What the step does\n\n| |\n|---|\n| `notify_channel`
Send the alert to a channel. |\n| `create_incident`
Declare an incident for the alert. |\n| `notify_on_call`
Page whoever is on call in a schedule, by email and their own phone. |\n| `branch`
If/else: alerts meeting every condition continue on its `then` side, the rest on its `else` side. |", "$ref": "#/components/schemas/EscalationStepAction" }, "delay_minutes": { "type": "integer", "description": "Minutes, 0 to 1440, to wait before the step runs. Default 0. Not for branches", "examples": [ 5 ], "minimum": 0, "maximum": 1440 }, "delay_until": { "anyOf": [ { "description": "Wait for the path's working hours to begin or end instead of `delay_minutes`. Not for branches\n\n| |\n|---|\n| `working_hours_start`
Wait until working hours begin; no wait during working hours. |\n| `working_hours_end`
Wait until working hours end; no wait outside them. |", "$ref": "#/components/schemas/EscalationDelayUntil" }, { "type": "null" } ] }, "channel_id": { "type": "string", "format": "uuid", "description": "`notify_channel`: the channel to send to" }, "schedule_id": { "type": "string", "format": "uuid", "description": "`notify_on_call`: the schedule whose person on call is paged (on-call is part of the Team plan and up)" }, "conditions": { "type": "array", "description": "`branch`: 1 to 10 conditions; all must hold for `then`", "items": { "$ref": "#/components/schemas/EscalationConditionInput" } }, "then": { "type": "array", "description": "`branch`: the steps when the conditions hold; empty ends the escalation there", "items": { "$ref": "#/components/schemas/EscalationStepInput" } }, "else": { "type": "array", "description": "`branch`: the steps otherwise; empty ends the escalation there", "items": { "$ref": "#/components/schemas/EscalationStepInput" } } }, "required": [ "type" ], "title": "EscalationStepInputRequest" }, "HealthStatus": { "type": "string", "description": "Verdict of a host health check.\n| |\n|---|\n| `ok`
Nothing to do. |\n| `warning`
Needs attention soon: a reboot or security updates pending, the clock not synchronised. |\n| `critical`
Needs attention now: a service failed, processes were killed for lack of memory. |\n| `unknown`
The agent does not report it (yet): an older agent, or nothing to report on this host. |", "enum": [ "ok", "warning", "critical", "unknown" ], "title": "HealthStatus" }, "Host": { "type": "object", "description": "A server with the Spectate agent, which reports CPU, memory, disk and network metrics. Hosts\nare added by installing the agent with an install token, not through the API.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Host ID" }, "label": { "type": [ "string", "null" ], "description": "Name shown in the dashboard and alerts; the agent sets the hostname until you change it", "examples": [ "web-1" ] }, "state": { "description": "Whether the agent reports\n\n| |\n|---|\n| `up`
Reported in the last 15 minutes. |\n| `stale`
Reported before, but not in the last 15 minutes. |\n| `pending`
The agent never reported. |", "$ref": "#/components/schemas/HostState" }, "host_info": { "type": [ "object", "null" ], "description": "What the agent reports about the system, as key-value pairs (for example `hostname`, `os`, `platform`, `kernel_version`); the keys depend on the agent version and platform", "additionalProperties": { "type": "string" } }, "cpu_info": { "type": [ "array", "null" ], "description": "The CPUs, each as key-value pairs (for example `model_name`, `cores`, `mhz`)", "items": { "type": "object", "additionalProperties": { "type": "string" } } }, "agent_version": { "type": [ "string", "null" ], "description": "Version of the agent", "examples": [ "2.0.3" ] }, "agent_update_version": { "type": [ "string", "null" ], "description": "A newer agent release, when the host runs an older one (`sudo spectate-agent update`)" }, "clock_offset_ms": { "type": [ "integer", "null" ], "description": "Server time minus the host's clock, in milliseconds, as last measured by a v2 agent; `null` when unknown" }, "last_seen_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the agent last reported" }, "no_data_alert_minutes": { "type": [ "integer", "null" ], "description": "Minutes without data before the \"no data received\" alert fires; `null` when that alert is off", "examples": [ 10 ] }, "paused_reason": { "anyOf": [ { "description": "Why the system paused the host; `null` when it runs\n\n| |\n|---|\n| `plan_limit`
Over the plan limit (trial expired, downgrade); the oldest resources stay active. |\n| `team_paused`
The whole team's monitoring is paused (no paid plan, staff action or scheduled deletion). |", "$ref": "#/components/schemas/ResourcePauseReason" }, { "type": "null" } ] }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The project the host belongs to; `null` for none" }, "escalation_paths": { "type": "array", "description": "Escalation paths the host's alerts follow. Empty: the project's paths, else the team's default path", "items": { "$ref": "#/components/schemas/EscalationPathReference" } }, "created_at": { "type": "string", "format": "date-time", "description": "When the host registered" }, "health": { "type": "array", "description": "Health checks (agent 2.1 or later): failed services, out of memory, reboot, updates, clock, file handles and pressure. Checks of collectors that are switched off, and Linux-only checks on other systems, are left out", "items": { "$ref": "#/components/schemas/HostHealthCheckResult" } }, "health_issues": { "type": "integer", "description": "Number of health checks that need attention (`warning` or `critical`)" } }, "required": [ "id", "label", "state", "host_info", "cpu_info", "agent_version", "agent_update_version", "clock_offset_ms", "last_seen_at", "no_data_alert_minutes", "paused_reason", "project_id", "escalation_paths", "created_at", "health", "health_issues" ], "title": "Host" }, "HostHealthCheck": { "type": "string", "description": "A host health check, computed from what agent 2.1+ reports.\n| |\n|---|\n| `services`
Failed systemd services. |\n| `oom`
Processes killed for lack of memory (OOM kills) in the last 24 hours. |\n| `reboot`
The system needs a reboot (after kernel or library updates). |\n| `updates`
Pending package updates, security updates in particular. |\n| `clock`
Whether the clock is synchronised (NTP) and close to the server's. |\n| `files`
Open file handles against the system's maximum. |\n| `pressure`
Tasks stalled waiting for memory or I/O (pressure stall information). |", "enum": [ "services", "oom", "reboot", "updates", "clock", "files", "pressure" ], "title": "HostHealthCheck" }, "HostHealthCheckResult": { "type": "object", "description": "One health check of a host, computed from what agent 2.1 or later reports.", "properties": { "check": { "description": "What is checked\n\n| |\n|---|\n| `services`
Failed systemd services. |\n| `oom`
Processes killed for lack of memory (OOM kills) in the last 24 hours. |\n| `reboot`
The system needs a reboot (after kernel or library updates). |\n| `updates`
Pending package updates, security updates in particular. |\n| `clock`
Whether the clock is synchronised (NTP) and close to the server's. |\n| `files`
Open file handles against the system's maximum. |\n| `pressure`
Tasks stalled waiting for memory or I/O (pressure stall information). |", "$ref": "#/components/schemas/HostHealthCheck" }, "status": { "description": "The verdict\n\n| |\n|---|\n| `ok`
Nothing to do. |\n| `warning`
Needs attention soon: a reboot or security updates pending, the clock not synchronised. |\n| `critical`
Needs attention now: a service failed, processes were killed for lack of memory. |\n| `unknown`
The agent does not report it (yet): an older agent, or nothing to report on this host. |", "$ref": "#/components/schemas/HealthStatus" }, "detail": { "type": [ "string", "null" ], "description": "What was found, in one line", "examples": [ "nginx.service failed" ] }, "since": { "type": [ "string", "null" ], "format": "date-time", "description": "Since when the problem has lasted (for out of memory: the last kill); `null` when there is none" } }, "required": [ "check", "status", "detail", "since" ], "title": "HostHealthCheckResult" }, "HostInstallToken": { "type": "object", "description": "An install token: agents use it to register hosts with the team. Any number of hosts can use\none token until it expires or is revoked.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Install token ID" }, "token": { "type": "string", "description": "The token to give the agent's installer (`--token`)", "examples": [ "hct_0b7c\u2026" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the token stops registering new hosts. Hosts that registered keep reporting" }, "created_at": { "type": "string", "format": "date-time", "description": "When the token was created" } }, "required": [ "id", "token", "expires_at", "created_at" ], "title": "HostInstallToken" }, "HostReference": { "type": "object", "description": "A host something applies to.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Host ID" }, "label": { "type": [ "string", "null" ], "description": "Host name shown in the dashboard; `null` until set or reported", "examples": [ "web-1" ] } }, "required": [ "id", "label" ], "title": "HostReference" }, "HostState": { "type": "string", "description": "Whether a host's agent reports.\n| |\n|---|\n| `up`
Reported in the last 15 minutes. |\n| `stale`
Reported before, but not in the last 15 minutes. |\n| `pending`
The agent never reported. |", "enum": [ "up", "stale", "pending" ], "title": "HostState" }, "ImpactLevel": { "type": "string", "description": "An impact on a status page, including `none`: how an incident or maintenance affects a component, or an incident's overall impact.\n| |\n|---|\n| `none`
No impact (for a component: not affected). |\n| `degraded_performance`
Slower or less reliable than usual. |\n| `partial_outage`
Down for some visitors or some functions. |\n| `major_outage`
Down. |", "enum": [ "none", "degraded_performance", "partial_outage", "major_outage" ], "title": "ImpactLevel" }, "Incident": { "type": "object", "description": "An incident: a problem that affects customers, worked on by the team, with updates, roles and\neventually a postmortem. Incidents are declared by hand, through the API, from Slack, or by an\nescalation path's `create_incident` step.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Incident ID" }, "number": { "type": [ "integer", "null" ], "description": "The team's sequence number: `INC-42` is 42. `null` for some older incidents", "examples": [ 42 ] }, "reference": { "type": "string", "description": "The human reference", "examples": [ "INC-42" ] }, "title": { "type": "string", "description": "What's going on", "examples": [ "Checkout fails for some customers" ] }, "summary": { "type": [ "string", "null" ], "description": "More about it, in Markdown" }, "severity": { "description": "How bad it is\n\n| |\n|---|\n| `critical`
Customers are affected right now. |\n| `high`
Serious, needs attention soon. |\n| `medium`
Should be looked at. |\n| `low`
Informational. |", "$ref": "#/components/schemas/Severity" }, "status": { "description": "Where it stands\n\n| |\n|---|\n| `investigating`
Declared; the cause isn't known yet. |\n| `identified`
Acknowledged: the cause is known and someone works on it. |\n| `monitoring`
A fix is out; watching whether it holds. |\n| `resolved`
Over. |", "$ref": "#/components/schemas/IncidentStatus" }, "started_at": { "type": "string", "format": "date-time", "description": "When it started" }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When someone acknowledged it" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was resolved" }, "alert_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The alert that opened it, for incidents declared by an escalation path" }, "roles": { "type": "array", "description": "Who has which role", "items": { "$ref": "#/components/schemas/IncidentRoleAssignment" } }, "created_at": { "type": "string", "format": "date-time", "description": "When it was declared" } }, "required": [ "id", "number", "reference", "title", "summary", "severity", "status", "started_at", "acknowledged_at", "resolved_at", "alert_id", "roles", "created_at" ], "title": "Incident" }, "IncidentPostmortem": { "type": "object", "description": "An incident's postmortem: what happened, why, and what changes.", "properties": { "content": { "type": [ "string", "null" ], "description": "The postmortem, in Markdown" }, "published": { "type": "boolean", "description": "Whether it is marked as published (final). It is not shown on status pages" }, "updated_at": { "type": "string", "format": "date-time", "description": "When it last changed" } }, "required": [ "content", "published", "updated_at" ], "title": "IncidentPostmortem" }, "IncidentPostmortemResult": { "type": "object", "description": "An incident's postmortem, if it has one.", "properties": { "postmortem": { "anyOf": [ { "description": "The postmortem; `null` until one is written", "$ref": "#/components/schemas/IncidentPostmortem" }, { "type": "null" } ] } }, "required": [ "postmortem" ], "title": "IncidentPostmortemResult" }, "IncidentRole": { "type": "string", "description": "A role in handling an incident; one member each.\n| |\n|---|\n| `commander`
Leads the response and makes the calls. |\n| `communications_lead`
Keeps customers and the company informed, for example through the status page. |", "enum": [ "commander", "communications_lead" ], "title": "IncidentRole" }, "IncidentRoleAssignment": { "type": "object", "description": "Who has a role in an incident.", "properties": { "role": { "description": "The role\n\n| |\n|---|\n| `commander`
Leads the response and makes the calls. |\n| `communications_lead`
Keeps customers and the company informed, for example through the status page. |", "$ref": "#/components/schemas/IncidentRole" }, "member": { "description": "The member who has it", "$ref": "#/components/schemas/MemberReference" } }, "required": [ "role", "member" ], "title": "IncidentRoleAssignment" }, "IncidentStatus": { "type": "string", "description": "Where an incident stands.\n| |\n|---|\n| `investigating`
Declared; the cause isn't known yet. |\n| `identified`
Acknowledged: the cause is known and someone works on it. |\n| `monitoring`
A fix is out; watching whether it holds. |\n| `resolved`
Over. |", "enum": [ "investigating", "identified", "monitoring", "resolved" ], "title": "IncidentStatus" }, "IncidentTimelineEntry": { "type": "object", "description": "Something that happened in an incident.", "properties": { "description": { "type": "string", "description": "What happened", "examples": [ "Incident acknowledged" ] }, "actor": { "type": [ "string", "null" ], "description": "Who did it: a member's name, `API token \"\u2026\"`, or Spectate staff; `null` for Spectate itself", "examples": [ "Jane Doe" ] }, "actor_type": { "anyOf": [ { "description": "What kind of actor; `null` for Spectate itself\n\n| |\n|---|\n| `user`
A team member. |\n| `api_token`
A team API token. |\n| `employee`
Spectate staff. |", "$ref": "#/components/schemas/ActivityCauserType" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "When it happened" } }, "required": [ "description", "actor", "actor_type", "created_at" ], "title": "IncidentTimelineEntry" }, "IncidentUpdate": { "type": "object", "description": "An update posted to an incident: what's known now, and its status at that moment.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Update ID" }, "status": { "description": "The incident's status with this update\n\n| |\n|---|\n| `investigating`
Declared; the cause isn't known yet. |\n| `identified`
Acknowledged: the cause is known and someone works on it. |\n| `monitoring`
A fix is out; watching whether it holds. |\n| `resolved`
Over. |", "$ref": "#/components/schemas/IncidentStatus" }, "body": { "type": "string", "description": "The update, in Markdown", "examples": [ "Rolled back the deploy; error rates are dropping." ] }, "created_at": { "type": "string", "format": "date-time", "description": "When it was posted" } }, "required": [ "id", "status", "body", "created_at" ], "title": "IncidentUpdate" }, "Invite": { "type": "object", "description": "An invite to join the team, sent by email. The invitee accepts it in the dashboard with an\naccount for that address.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Invite ID" }, "email": { "type": "string", "format": "email", "description": "The invitee's email address", "examples": [ "jane@example.com" ] }, "role": { "description": "The role they get when they accept\n\n| |\n|---|\n| `owner`
Everything, including billing and deleting the team. One per team. |\n| `manager`
Everything but billing and deleting the team. |\n| `admin`
Configure monitoring, alerting, incidents and status pages; can't manage members or API tokens. |\n| `member`
Read everything; manage monitors and incidents, acknowledge alerts. |\n| `billing`
Billing and support only. |", "$ref": "#/components/schemas/TeamRole" }, "expired": { "type": "boolean", "description": "Whether it expired without being accepted. Expired invites don't count towards the member limit and can be sent again" }, "expires_at": { "type": "string", "format": "date-time", "description": "When it expires, 7 days after it was sent" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was sent" } }, "required": [ "id", "email", "role", "expired", "expires_at", "created_at" ], "title": "Invite" }, "Member": { "type": "object", "description": "A member of the team. Use member IDs for on-call rotations and incident roles.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Member (user) ID" }, "name": { "type": "string", "description": "Name", "examples": [ "Jane Doe" ] }, "email": { "type": "string", "format": "email", "description": "Email address", "examples": [ "jane@example.com" ] }, "role": { "description": "Role in the team\n\n| |\n|---|\n| `owner`
Everything, including billing and deleting the team. One per team. |\n| `manager`
Everything but billing and deleting the team. |\n| `admin`
Configure monitoring, alerting, incidents and status pages; can't manage members or API tokens. |\n| `member`
Read everything; manage monitors and incidents, acknowledge alerts. |\n| `billing`
Billing and support only. |", "$ref": "#/components/schemas/TeamRole" }, "joined_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When they joined the team" } }, "required": [ "id", "name", "email", "role", "joined_at" ], "title": "Member" }, "MemberReference": { "type": "object", "description": "A member of the team.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Member (user) ID" }, "name": { "type": "string", "description": "Name", "examples": [ "Jane Doe" ] }, "email": { "type": "string", "format": "email", "description": "Email address", "examples": [ "jane@example.com" ] } }, "required": [ "id", "name", "email" ], "title": "MemberReference" }, "MetricCondition": { "type": "object", "description": "An alert rule for host metrics, for example \"CPU usage above 90% for 5 minutes\". It applies to\nits hosts and to every host of its projects.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Metric condition ID" }, "metric": { "description": "The metric to watch", "$ref": "#/components/schemas/MetricPoint" }, "condition": { "description": "How the metric's value is compared with `threshold`\n\n| |\n|---|\n| `greater_than`
Fires when the value is above the threshold. |\n| `less_than`
Fires when the value is below the threshold. |\n| `equals`
Fires when the value equals the threshold. |", "$ref": "#/components/schemas/MetricCondition" }, "threshold": { "type": "number", "description": "Compared with the metric's value as the agent reports it, in the unit the host's charts show (percent for `cpu_usage`, `memory_usage` and `disk_usage`)", "examples": [ 90 ] }, "duration_minutes": { "type": "integer", "description": "Minutes the condition must hold before the alert fires; 0 fires on the first breach", "examples": [ 5 ] }, "severity": { "description": "Severity of the alert it raises\n\n| |\n|---|\n| `critical`
Customers are affected right now. |\n| `high`
Serious, needs attention soon. |\n| `medium`
Should be looked at. |\n| `low`
Informational. |", "$ref": "#/components/schemas/Severity" }, "hosts": { "type": "array", "description": "Hosts it applies to", "items": { "$ref": "#/components/schemas/HostReference" } }, "projects": { "type": "array", "description": "Projects whose hosts it applies to", "items": { "$ref": "#/components/schemas/ProjectReference" } } }, "required": [ "id", "metric", "condition", "threshold", "duration_minutes", "severity", "hosts", "projects" ], "title": "MetricCondition" }, "MetricPoint": { "type": "string", "description": "A host metric the agent reports. `cpu_usage`, `memory_usage`, `disk_usage`, `load_average`, `network_in` and `network_out` are the summaries the dashboard charts; the `system.*` metrics are the agent's raw values.\n", "enum": [ "cpu_usage", "system.cpu.user", "system.cpu.system", "system.cpu.iowait", "system.cpu.stolen", "system.cpu.idle", "system.cpu.guest", "system.cpu.interrupt", "memory_usage", "system.memory.total", "system.memory.used", "system.memory.free", "system.memory.available", "system.memory.available_percent", "system.swap.total", "system.swap.used", "system.swap.free", "system.swap.free_percent", "system.swap.in", "system.swap.out", "disk_usage", "system.disk_usage.total", "system.disk_usage.used", "system.disk_usage.free", "system.disk_usage.inodes_total", "system.disk_usage.inodes_used", "system.disk_usage.inodes_free", "system.disk_usage.inodes_used_percent", "load_average", "system.load.1", "system.load.5", "system.load.15", "network_in", "network_out", "system.net.packets_recv", "system.net.packets_sent", "system.net.err_in", "system.net.err_out", "system.net.drop_in", "system.net.drop_out", "system.net.fifo_in", "system.net.fifo_out", "system.uptime", "system.io.busy_percent", "system.io.await_ms", "system.pressure.cpu.some", "system.pressure.memory.some", "system.pressure.io.some", "system.net.tcp.established", "system.net.tcp.time_wait", "system.files.used_percent" ], "title": "MetricPoint" }, "Monitor": { "type": "object", "description": "A monitor: a check of a URL, host or DNS name from Spectate's regions, with its settings and\nlatest results.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Monitor ID" }, "label": { "type": "string", "description": "Name shown in the dashboard, alerts and status pages", "examples": [ "Website" ] }, "protocol": { "description": "What is checked; decides the format of `uri`\n\n| |\n|---|\n| `https`
An HTTPS request to the URL in `uri`, with a certificate check. |\n| `http`
An HTTP request to the URL in `uri`. |\n| `icmp`
A ping (ICMP echo) to the host in `uri`. |\n| `tcp`
A TCP connect to `host:port`, optionally with a TLS handshake and a banner keyword. |\n| `dns`
A DNS query for a record of the name in `uri`, optionally compared with expected values. |\n| `smtp`
An SMTP greeting from `host:port` (port optional), with STARTTLS by default. |\n| `imap`
An IMAP greeting from `host:port` (port optional), over TLS by default. |\n| `pop3`
A POP3 greeting from `host:port` (port optional), over TLS by default. |", "$ref": "#/components/schemas/MonitorProtocol" }, "uri": { "type": "string", "description": "The target as stored: a URL without the scheme for `http` and `https` (the protocol is the scheme), a host for `icmp`, `host:port` for `tcp` and mail, a DNS name for `dns`. `url` has the full URL", "examples": [ "example.com/health" ] }, "url": { "type": "string", "description": "The target as the dashboard shows it, for example `smtp://mail.example.com:587` for SMTP", "examples": [ "https://example.com/health" ] }, "interval": { "description": "Seconds between checks", "$ref": "#/components/schemas/MonitorInterval" }, "primary_location": { "description": "Region the checks run from; a failed check is repeated from the same region about 5 seconds later before the monitor goes down\n\n| |\n|---|\n| `eu`
Europe. |\n| `us`
North America. |\n| `as`
Asia. |\n| `oc`
Oceania. |", "$ref": "#/components/schemas/MonitorLocation" }, "timeout": { "type": "integer", "description": "Seconds before a check times out", "examples": [ 30 ] }, "max_redirects": { "type": [ "integer", "null" ], "description": "HTTP: redirects followed before the check fails; `null` follows up to 10" }, "headers": { "type": "array", "description": "HTTP: headers sent with every check", "items": { "$ref": "#/components/schemas/MonitorHeader" } }, "advanced_settings": { "description": "Protocol-specific settings", "$ref": "#/components/schemas/MonitorAdvancedSettings" }, "enabled": { "type": "boolean", "description": "Whether the monitor runs. `false` when paused by a member or by the system (see `paused_reason`)" }, "paused_reason": { "anyOf": [ { "description": "Why the system paused the monitor; `null` when a member paused it or it runs\n\n| |\n|---|\n| `plan_limit`
Over the plan limit (trial expired, downgrade); the oldest resources stay active. |\n| `team_paused`
The whole team's monitoring is paused (no paid plan, staff action or scheduled deletion). |", "$ref": "#/components/schemas/ResourcePauseReason" }, { "type": "null" } ] }, "allow_insecure_requests": { "type": "boolean", "description": "HTTPS: whether invalid certificates are accepted for the check itself (the certificate check still reports them)" }, "expected_http_status_code": { "type": [ "string", "null" ], "description": "HTTP: status codes that count as up, comma-separated, `*` as a wildcard digit (`2**,301`); `null` accepts 2xx and 3xx", "examples": [ "2**,301" ] }, "certificate_check_enabled": { "type": "boolean", "description": "Whether the TLS certificate is checked for validity and expiry" }, "certificate_expiry_threshold_days": { "type": "integer", "description": "Days before the certificate expires that the \"expires soon\" alert fires", "examples": [ 14 ] }, "uses_tls": { "type": "boolean", "description": "Whether a check reports a certificate: HTTPS, and TCP or mail with TLS" }, "certificate_status": { "anyOf": [ { "description": "The certificate's state from the latest certificate check; `null` when not checked\n\n| |\n|---|\n| `pending`
Not checked yet. |\n| `valid`
Valid and not about to expire. |\n| `invalid`
Not trusted, for example self-signed, for another host or with a broken chain. |\n| `expires_soon`
Valid, but expires within the monitor's `certificate_expiry_threshold_days`. |\n| `expired`
Past its expiry date. |", "$ref": "#/components/schemas/CertificateStatus" }, { "type": "null" } ] }, "certificate_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the certificate expires" }, "certificate_valid_from": { "type": [ "string", "null" ], "format": "date-time", "description": "When the certificate became valid" }, "certificate_issuer": { "type": [ "string", "null" ], "description": "Who issued the certificate", "examples": [ "R11" ] }, "certificate_error": { "type": [ "string", "null" ], "description": "Why the certificate isn't valid, with `certificate_status` `invalid` or `expired`" }, "certificate_checked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the certificate was last checked" }, "performance_check_enabled": { "type": "boolean", "description": "Whether slow responses raise alerts (`performance_hard_threshold`, `performance_deviation_percentage`)" }, "performance_hard_threshold": { "type": [ "integer", "null" ], "description": "Milliseconds: a response slower than this raises an alert", "examples": [ 2000 ] }, "performance_deviation_percentage": { "type": [ "integer", "null" ], "description": "Percent: an alert fires when the average response time of the last `performance_deviation_timeframe` minutes is this much above the average of the `performance_deviation_before_timeframe` minutes before", "examples": [ 50 ] }, "performance_deviation_timeframe": { "type": [ "integer", "null" ], "description": "Minutes of recent checks compared (15 to 120, in steps of 15)", "examples": [ 30 ] }, "performance_deviation_before_timeframe": { "type": [ "integer", "null" ], "description": "Minutes before those that they're compared with (60 to 1440, in whole hours)", "examples": [ 240 ] }, "regional_performance_enabled": { "type": "boolean", "description": "Also measure response time from the regions other than `primary_location`, every minute (or at the interval, when longer). Shown with the monitor's performance; not used for uptime or alerts. Team plan and up" }, "uptime_status": { "description": "Whether the target answers, from the latest checks\n\n| |\n|---|\n| `pending`
Not checked yet. |\n| `up`
The latest check succeeded. |\n| `down`
Checks fail: a failed check, repeated from the same region about 5 seconds later, failed again. |", "$ref": "#/components/schemas/UptimeStatus" }, "uptime_status_changed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When `uptime_status` last changed" }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the monitor was last checked" }, "response_time": { "type": [ "integer", "null" ], "description": "Milliseconds the latest check took", "examples": [ 182 ] }, "check_details": { "anyOf": [ { "description": "Protocol details of the latest check", "$ref": "#/components/schemas/MonitorCheckDetails" }, { "type": "null" } ] }, "uptime": { "description": "Uptime over rolling windows", "$ref": "#/components/schemas/MonitorUptime" }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The project the monitor belongs to; `null` for none" }, "escalation_paths": { "type": "array", "description": "Escalation paths the monitor's alerts follow. Empty: the project's paths, else the team's default path", "items": { "$ref": "#/components/schemas/EscalationPathReference" } }, "created_at": { "type": "string", "format": "date-time", "description": "When the monitor was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the monitor's settings last changed" } }, "required": [ "id", "label", "protocol", "uri", "url", "interval", "primary_location", "timeout", "max_redirects", "headers", "advanced_settings", "enabled", "paused_reason", "allow_insecure_requests", "expected_http_status_code", "certificate_check_enabled", "certificate_expiry_threshold_days", "uses_tls", "certificate_status", "certificate_expires_at", "certificate_valid_from", "certificate_issuer", "certificate_error", "certificate_checked_at", "performance_check_enabled", "performance_hard_threshold", "performance_deviation_percentage", "performance_deviation_timeframe", "performance_deviation_before_timeframe", "regional_performance_enabled", "uptime_status", "uptime_status_changed_at", "last_checked_at", "response_time", "check_details", "uptime", "project_id", "escalation_paths", "created_at", "updated_at" ], "title": "Monitor" }, "MonitorAdvancedSettings": { "type": "object", "description": "Protocol-specific settings of a monitor. Settings that don't apply to its protocol are `null`.\nThe password is never returned; `has_auth_password` says whether one is set.", "properties": { "connection_timeout": { "type": [ "integer", "null" ], "description": "Seconds to wait for the connection; `null` uses the monitor's `timeout`" }, "auth_method": { "anyOf": [ { "description": "HTTP: how the request authenticates; `null` for none\n\n| |\n|---|\n| `basic`
HTTP Basic: `auth_user` and `auth_password`. |\n| `bearer`
`Authorization: Bearer `. |\n| `digest`
HTTP Digest: `auth_user` and `auth_password`. |", "$ref": "#/components/schemas/MonitorAuthMethod" }, { "type": "null" } ] }, "auth_user": { "type": [ "string", "null" ], "description": "HTTP: user name for `basic` and `digest`" }, "has_auth_password": { "type": "boolean", "description": "HTTP: whether a password or bearer token is stored" }, "keyword": { "type": [ "string", "null" ], "description": "HTTP: text the response body must contain (or must not, with `keyword_inverted`). TCP: the same for the server's banner", "examples": [ "OK" ] }, "keyword_inverted": { "type": [ "boolean", "null" ], "description": "Whether the check fails when `keyword` is found, instead of when it's missing" }, "useragent": { "type": [ "string", "null" ], "description": "HTTP: the `User-Agent` header; `null` sends Spectate's" }, "method": { "anyOf": [ { "description": "HTTP: the request method; `null` sends `GET`", "$ref": "#/components/schemas/MonitorHttpMethod" }, { "type": "null" } ] }, "tls_mode": { "anyOf": [ { "description": "TCP and mail: how the connection uses TLS; `null` uses the protocol's default (TCP `none`, SMTP `starttls`, IMAP and POP3 `tls`)\n\n| |\n|---|\n| `none`
Plain TCP, no TLS. |\n| `tls`
TLS from the first byte (implicit TLS), as on ports 465, 993 and 995. |\n| `starttls`
Upgrade a plaintext session: STARTTLS (SMTP, IMAP) or STLS (POP3). Mail monitors only. |", "$ref": "#/components/schemas/TlsMode" }, { "type": "null" } ] }, "dns_record_type": { "anyOf": [ { "description": "DNS: the record type to query; `null` queries `A`", "$ref": "#/components/schemas/DnsRecordType" }, { "type": "null" } ] }, "dns_resolver": { "type": [ "string", "null" ], "description": "DNS: the resolver to query, as `ip` or `ip:port`; `null` uses the checker's resolver", "examples": [ "1.1.1.1" ] }, "dns_authoritative": { "type": [ "boolean", "null" ], "description": "DNS: whether to ask the zone's authoritative nameservers directly" }, "dns_expected_values": { "type": [ "array", "null" ], "description": "DNS: values the answer must contain or equal (see `dns_match`); `null` or empty accepts any answer", "items": { "type": "string" } }, "dns_match": { "anyOf": [ { "description": "DNS: how the answer is compared with `dns_expected_values`; `null` means `contains`\n\n| |\n|---|\n| `contains`
Every expected value is in the answer; the answer may have more. |\n| `exact`
The answer is exactly the expected values, in any order. |", "$ref": "#/components/schemas/DnsMatch" }, { "type": "null" } ] }, "dns_alert_on_change": { "type": [ "boolean", "null" ], "description": "DNS: whether a changed answer raises an alert" } }, "required": [ "connection_timeout", "auth_method", "auth_user", "has_auth_password", "keyword", "keyword_inverted", "useragent", "method", "tls_mode", "dns_record_type", "dns_resolver", "dns_authoritative", "dns_expected_values", "dns_match", "dns_alert_on_change" ], "title": "MonitorAdvancedSettings" }, "MonitorAdvancedSettingsInput": { "type": "object", "description": "Protocol-specific settings to set. On update, settings you leave out keep their value; send\n`null` to reset one to its default.", "properties": { "connection_timeout": { "type": [ "integer", "null" ], "description": "Seconds to wait for the connection, 1 to 60; `null` uses the monitor's `timeout`", "minimum": 1, "maximum": 60 }, "auth_method": { "anyOf": [ { "description": "HTTP: how the request authenticates; `null` removes authentication and its credentials\n\n| |\n|---|\n| `basic`
HTTP Basic: `auth_user` and `auth_password`. |\n| `bearer`
`Authorization: Bearer `. |\n| `digest`
HTTP Digest: `auth_user` and `auth_password`. |", "$ref": "#/components/schemas/MonitorAuthMethod" }, { "type": "null" } ] }, "auth_user": { "type": [ "string", "null" ], "description": "HTTP: user name for `basic` and `digest`", "maxLength": 255 }, "auth_password": { "type": [ "string", "null" ], "description": "HTTP: password, or the token for `bearer`. Write-only: never returned. Leave out or send an empty string to keep the stored one", "maxLength": 2500 }, "keyword": { "type": [ "string", "null" ], "description": "HTTP: text the response body must contain (or must not, with `keyword_inverted`). TCP: the same for the server's banner", "examples": [ "OK" ], "maxLength": 255 }, "keyword_inverted": { "type": [ "boolean", "null" ], "description": "Fail the check when `keyword` is found, instead of when it's missing" }, "useragent": { "type": [ "string", "null" ], "description": "HTTP: the `User-Agent` header; `null` sends Spectate's", "maxLength": 255 }, "method": { "anyOf": [ { "description": "HTTP: the request method; `null` sends `GET`", "$ref": "#/components/schemas/MonitorHttpMethod" }, { "type": "null" } ] }, "tls_mode": { "anyOf": [ { "description": "TCP and mail: how the connection uses TLS. `starttls` is for mail only. `null` uses the protocol's default\n\n| |\n|---|\n| `none`
Plain TCP, no TLS. |\n| `tls`
TLS from the first byte (implicit TLS), as on ports 465, 993 and 995. |\n| `starttls`
Upgrade a plaintext session: STARTTLS (SMTP, IMAP) or STLS (POP3). Mail monitors only. |", "$ref": "#/components/schemas/TlsMode" }, { "type": "null" } ] }, "dns_record_type": { "anyOf": [ { "description": "DNS: the record type to query; `null` queries `A`", "$ref": "#/components/schemas/DnsRecordType" }, { "type": "null" } ] }, "dns_resolver": { "type": [ "string", "null" ], "description": "DNS: the resolver to query, as a public `ip` or `ip:port`; `null` uses the checker's resolver", "examples": [ "1.1.1.1" ], "maxLength": 64 }, "dns_authoritative": { "type": [ "boolean", "null" ], "description": "DNS: ask the zone's authoritative nameservers directly" }, "dns_expected_values": { "type": [ "array", "null" ], "description": "DNS: up to 20 values the answer must contain or equal (see `dns_match`)", "items": { "type": "string", "maxLength": 512 }, "maxItems": 20 }, "dns_match": { "anyOf": [ { "description": "DNS: how the answer is compared with `dns_expected_values`\n\n| |\n|---|\n| `contains`
Every expected value is in the answer; the answer may have more. |\n| `exact`
The answer is exactly the expected values, in any order. |", "$ref": "#/components/schemas/DnsMatch" }, { "type": "null" } ] }, "dns_alert_on_change": { "type": [ "boolean", "null" ], "description": "DNS: raise an alert when the answer changes" } }, "title": "MonitorAdvancedSettingsInput" }, "MonitorAuthMethod": { "type": "string", "description": "How an HTTP monitor authenticates its request.\n| |\n|---|\n| `basic`
HTTP Basic: `auth_user` and `auth_password`. |\n| `bearer`
`Authorization: Bearer `. |\n| `digest`
HTTP Digest: `auth_user` and `auth_password`. |", "enum": [ "basic", "bearer", "digest" ], "title": "MonitorAuthMethod" }, "MonitorCheckDetails": { "type": "object", "description": "Protocol details of the latest check, as the checker reported them. Fields that don't apply to\nthe protocol are `null`.", "properties": { "banner": { "type": [ "string", "null" ], "description": "TCP and mail: the first line of the server's greeting or banner", "examples": [ "220 mail.example.com ESMTP" ] }, "reply_code": { "type": [ "integer", "null" ], "description": "SMTP: the greeting's reply code", "examples": [ 220 ] }, "starttls": { "type": [ "boolean", "null" ], "description": "Mail: whether the session was upgraded with STARTTLS (or STLS)" }, "tls_version": { "type": [ "string", "null" ], "description": "The negotiated TLS version", "examples": [ "TLS 1.3" ] }, "cipher_suite": { "type": [ "string", "null" ], "description": "The negotiated cipher suite", "examples": [ "TLS_AES_128_GCM_SHA256" ] }, "dns_answers": { "type": [ "array", "null" ], "description": "DNS: the answer's values of the queried record type, sorted", "items": { "type": "string" } }, "dns_server": { "type": [ "string", "null" ], "description": "DNS: the server that answered, as `ip:port`", "examples": [ "1.1.1.1:53" ] }, "dns_rcode": { "type": [ "string", "null" ], "description": "DNS: the response code", "examples": [ "NOERROR" ] } }, "required": [ "banner", "reply_code", "starttls", "tls_version", "cipher_suite", "dns_answers", "dns_server", "dns_rcode" ], "title": "MonitorCheckDetails" }, "MonitorHeader": { "type": "object", "description": "A request header an HTTP monitor sends.", "properties": { "key": { "type": "string", "description": "Header name", "examples": [ "X-Health-Check" ] }, "value": { "type": "string", "description": "Header value", "examples": [ "spectate" ] } }, "required": [ "key", "value" ], "title": "MonitorHeader" }, "MonitorHttpMethod": { "type": "string", "description": "The HTTP method an HTTP monitor sends.\n", "enum": [ "HEAD", "GET", "POST", "PUT", "PATCH", "DELETE" ], "title": "MonitorHttpMethod" }, "MonitorInterval": { "type": "integer", "description": "Seconds between checks. Plans set the shortest interval a team may use.\n", "enum": [ 30, 60, 120, 180, 300, 600, 900, 1800, 3600 ], "title": "MonitorInterval" }, "MonitorLocation": { "type": "string", "description": "A region checks run from. A monitor's primary region decides its uptime and alerts (a failed check is repeated from the same region about 5 seconds later before it is marked down); on the Team plan and up the other regions can also measure its response time.\n| |\n|---|\n| `eu`
Europe. |\n| `us`
North America. |\n| `as`
Asia. |\n| `oc`
Oceania. |", "enum": [ "eu", "us", "as", "oc" ], "title": "MonitorLocation" }, "MonitorProtocol": { "type": "string", "description": "What a monitor checks, and so the format of its `uri`.\n| |\n|---|\n| `https`
An HTTPS request to the URL in `uri`, with a certificate check. |\n| `http`
An HTTP request to the URL in `uri`. |\n| `icmp`
A ping (ICMP echo) to the host in `uri`. |\n| `tcp`
A TCP connect to `host:port`, optionally with a TLS handshake and a banner keyword. |\n| `dns`
A DNS query for a record of the name in `uri`, optionally compared with expected values. |\n| `smtp`
An SMTP greeting from `host:port` (port optional), with STARTTLS by default. |\n| `imap`
An IMAP greeting from `host:port` (port optional), over TLS by default. |\n| `pop3`
A POP3 greeting from `host:port` (port optional), over TLS by default. |", "enum": [ "https", "http", "icmp", "tcp", "dns", "smtp", "imap", "pop3" ], "title": "MonitorProtocol" }, "MonitorReference": { "type": "object", "description": "A monitor something follows.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Monitor ID" }, "label": { "type": "string", "description": "Monitor name", "examples": [ "Website" ] } }, "required": [ "id", "label" ], "title": "MonitorReference" }, "MonitorState": { "type": "string", "description": "A monitor's state as the dashboard shows it: paused when disabled, otherwise its uptime status.\n| |\n|---|\n| `down`
Checks fail: a failed check, repeated from the same region about 5 seconds later, failed again. |\n| `pending`
Not checked yet. |\n| `up`
The latest check succeeded. |\n| `paused`
Disabled by a member or the system. |", "enum": [ "down", "pending", "up", "paused" ], "title": "MonitorState" }, "MonitorUptime": { "type": "object", "description": "Share of successful checks, in percent, over rolling windows; `null` until there is data.", "properties": { "twenty_four_hours": { "type": [ "number", "null" ], "description": "Last 24 hours", "examples": [ 99.95 ] }, "seven_days": { "type": [ "number", "null" ], "description": "Last 7 days" }, "thirty_days": { "type": [ "number", "null" ], "description": "Last 30 days" }, "ninety_days": { "type": [ "number", "null" ], "description": "Last 90 days" } }, "required": [ "twenty_four_hours", "seven_days", "thirty_days", "ninety_days" ], "title": "MonitorUptime" }, "NotificationCredits": { "type": "object", "description": "Credits for SMS and voice notifications. The monthly allowance is spent first; bought credits\nnever expire.", "properties": { "balance": { "type": "integer", "description": "Credits that can be spent now: what's left of this month's allowance plus bought credits" }, "allowance": { "type": "integer", "description": "What's left of this month's allowance" }, "purchased": { "type": "integer", "description": "Bought credits left" }, "monthly": { "type": "integer", "description": "The plan's monthly allowance; 0 during the trial" }, "reset_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the allowance was last reset; `null` before the first reset" } }, "required": [ "balance", "allowance", "purchased", "monthly", "reset_at" ], "title": "NotificationCredits" }, "OnCallNow": { "type": "object", "description": "Who is on call at a moment.", "properties": { "shift": { "anyOf": [ { "description": "The shift at that moment; `null` when nobody is on call (a gap)", "$ref": "#/components/schemas/OnCallShift" }, { "type": "null" } ] } }, "required": [ "shift" ], "title": "OnCallNow" }, "OnCallOverride": { "type": "object", "description": "Someone covering a schedule for a while, whatever the rotations say.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Override ID" }, "member": { "description": "Who covers", "$ref": "#/components/schemas/MemberReference" }, "starts_at": { "type": "string", "format": "date-time", "description": "From when" }, "ends_at": { "type": "string", "format": "date-time", "description": "Until when" }, "note": { "type": [ "string", "null" ], "description": "Why, for the team", "examples": [ "Covering for Jane's holiday" ] }, "created_by": { "anyOf": [ { "description": "Who added it; `null` when an API token did, or that member left", "$ref": "#/components/schemas/MemberReference" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "When it was added" } }, "required": [ "id", "member", "starts_at", "ends_at", "note", "created_by", "created_at" ], "title": "OnCallOverride" }, "OnCallRestrictions": { "type": "object", "description": "When a rotation layer covers, each week; outside it the layers below take over.", "properties": { "days": { "type": "array", "description": "ISO weekdays the layer covers, 1 (Monday) to 7 (Sunday)", "items": { "type": "integer" } }, "start_time": { "type": [ "string", "null" ], "description": "From when on those days, as `HH:MM` in the schedule's time zone; `null` with `end_time` `null` for the whole day", "examples": [ "09:00" ] }, "end_time": { "type": [ "string", "null" ], "description": "Until when, as `HH:MM`; before `start_time` runs past midnight", "examples": [ "17:00" ] } }, "required": [ "days", "start_time", "end_time" ], "title": "OnCallRestrictions" }, "OnCallRestrictionsInput": { "type": "object", "description": "When a rotation layer covers, each week.", "properties": { "days": { "type": "array", "description": "ISO weekdays the layer covers, 1 (Monday) to 7 (Sunday), at least one", "items": { "type": "integer", "minimum": 1, "maximum": 7 }, "minItems": 1, "maxItems": 7, "uniqueItems": true }, "start_time": { "type": [ "string", "null" ], "description": "From when on those days, as `HH:MM` in the schedule's time zone; leave out with `end_time` for the whole day", "examples": [ "09:00" ] }, "end_time": { "type": [ "string", "null" ], "description": "Until when, as `HH:MM`", "examples": [ "17:00" ] } }, "required": [ "days" ], "title": "OnCallRestrictionsInput" }, "OnCallRotation": { "type": "object", "description": "A rotation layer: its participants take turns of `shift_length` `shift_unit`s, from\n`start_date` at `handoff_time`. Where layers overlap, the top layer (`position` 0) wins.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Rotation ID" }, "name": { "type": "string", "description": "Name", "examples": [ "Weekly primary" ] }, "position": { "type": "integer", "description": "Layer order; 0 is the top layer and wins where layers overlap" }, "shift_unit": { "description": "The unit of the shift length\n\n| |\n|---|\n| `hours`
Absolute hours: shifts keep their length across DST changes. |\n| `days`
Calendar days in the schedule's time zone: the handoff stays at the same wall-clock time. |\n| `weeks`
Calendar weeks in the schedule's time zone. |", "$ref": "#/components/schemas/OnCallShiftUnit" }, "shift_length": { "type": "integer", "description": "Shift length in `shift_unit`s", "examples": [ 1 ] }, "start_date": { "type": "string", "format": "date", "description": "The first handoff's date in the schedule's time zone", "examples": [ "2026-11-02" ] }, "handoff_time": { "type": "string", "description": "Handoff time as `HH:MM` in the schedule's time zone", "examples": [ "09:00" ] }, "restrictions": { "anyOf": [ { "description": "Weekly window the layer covers; `null` for round the clock", "$ref": "#/components/schemas/OnCallRestrictions" }, { "type": "null" } ] }, "participants": { "type": "array", "description": "The members taking turns, in order", "items": { "$ref": "#/components/schemas/MemberReference" } }, "created_at": { "type": "string", "format": "date-time", "description": "When the rotation was created" } }, "required": [ "id", "name", "position", "shift_unit", "shift_length", "start_date", "handoff_time", "restrictions", "participants", "created_at" ], "title": "OnCallRotation" }, "OnCallSchedule": { "type": "object", "description": "An on-call schedule: rotation layers and overrides that decide who gets paged when an\nescalation path's `notify_on_call` step runs.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Schedule ID" }, "name": { "type": "string", "description": "Name", "examples": [ "Primary" ] }, "description": { "type": [ "string", "null" ], "description": "What the schedule covers" }, "timezone": { "type": "string", "description": "IANA time zone the rotations' dates, handoffs and restrictions are in", "examples": [ "Europe/Amsterdam" ] }, "current": { "anyOf": [ { "description": "Who is on call now; `null` when nobody is (a gap: on-call steps are skipped)", "$ref": "#/components/schemas/OnCallShift" }, { "type": "null" } ] }, "next_handoff_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the person on call changes next, within 4 weeks" }, "next": { "anyOf": [ { "description": "Who takes over at `next_handoff_at`; `null` when a gap starts", "$ref": "#/components/schemas/OnCallShift" }, { "type": "null" } ] }, "rotations": { "type": "array", "description": "Rotation layers, top first", "items": { "$ref": "#/components/schemas/OnCallRotation" } }, "overrides": { "type": "array", "description": "Overrides that haven't ended", "items": { "$ref": "#/components/schemas/OnCallOverride" } }, "used_by": { "type": "array", "description": "Escalation paths with a step that pages this schedule", "items": { "$ref": "#/components/schemas/EscalationPathReference" } }, "created_at": { "type": "string", "format": "date-time", "description": "When the schedule was created" } }, "required": [ "id", "name", "description", "timezone", "current", "next_handoff_at", "next", "rotations", "overrides", "used_by", "created_at" ], "title": "OnCallSchedule" }, "OnCallScheduleReference": { "type": "object", "description": "An on-call schedule something pages.", "properties": { "id": { "type": "string", "format": "uuid", "description": "On-call schedule ID" }, "name": { "type": "string", "description": "Schedule name", "examples": [ "Primary" ] } }, "required": [ "id", "name" ], "title": "OnCallScheduleReference" }, "OnCallShift": { "type": "object", "description": "A stretch of time someone is on call.", "properties": { "member": { "anyOf": [ { "description": "Who is on call; `null` when that member left the team", "$ref": "#/components/schemas/MemberReference" }, { "type": "null" } ] }, "starts_at": { "type": "string", "format": "date-time", "description": "When the shift starts" }, "ends_at": { "type": "string", "format": "date-time", "description": "When it ends" }, "source": { "description": "Whether a rotation or an override gives the shift\n\n| |\n|---|\n| `rotation`
A rotation layer's turn. |\n| `override`
An override someone added. |", "$ref": "#/components/schemas/OnCallShiftSource" }, "rotation_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The rotation layer, for rotation shifts" }, "override_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The override, for override shifts" } }, "required": [ "member", "starts_at", "ends_at", "source", "rotation_id", "override_id" ], "title": "OnCallShift" }, "OnCallShiftSource": { "type": "string", "description": "Where an on-call shift comes from.\n| |\n|---|\n| `rotation`
A rotation layer's turn. |\n| `override`
An override someone added. |", "enum": [ "rotation", "override" ], "title": "OnCallShiftSource" }, "OnCallShiftUnit": { "type": "string", "description": "The unit of a rotation's shift length.\n| |\n|---|\n| `hours`
Absolute hours: shifts keep their length across DST changes. |\n| `days`
Calendar days in the schedule's time zone: the handoff stays at the same wall-clock time. |\n| `weeks`
Calendar weeks in the schedule's time zone. |", "enum": [ "hours", "days", "weeks" ], "title": "OnCallShiftUnit" }, "OnCallTimeline": { "type": "object", "description": "Who is on call over a window: each layer's shifts, the overrides, and the result.", "properties": { "from": { "type": "string", "format": "date-time", "description": "Start of the window" }, "to": { "type": "string", "format": "date-time", "description": "End of the window" }, "timezone": { "type": "string", "description": "The schedule's time zone", "examples": [ "Europe/Amsterdam" ] }, "layers": { "type": "array", "description": "Each layer's shifts, top layer first", "items": { "$ref": "#/components/schemas/OnCallTimelineLayer" } }, "overrides": { "type": "array", "description": "Override shifts", "items": { "$ref": "#/components/schemas/OnCallShift" } }, "final": { "type": "array", "description": "Who actually gets paged when: overrides first, then the highest layer. Gaps are absent", "items": { "$ref": "#/components/schemas/OnCallShift" } } }, "required": [ "from", "to", "timezone", "layers", "overrides", "final" ], "title": "OnCallTimeline" }, "OnCallTimelineLayer": { "type": "object", "description": "One rotation layer's shifts in a timeline.", "properties": { "rotation_id": { "type": "string", "format": "uuid", "description": "Rotation ID" }, "name": { "type": "string", "description": "Rotation name", "examples": [ "Weekly primary" ] }, "position": { "type": "integer", "description": "Layer order; 0 is the top layer" }, "shifts": { "type": "array", "description": "The layer's own shifts, before overrides and higher layers", "items": { "$ref": "#/components/schemas/OnCallShift" } } }, "required": [ "rotation_id", "name", "position", "shifts" ], "title": "OnCallTimelineLayer" }, "Plan": { "type": "string", "description": "Billing plans (docs/billing.md). The plan sets the features; the number of monitors + hosts is the subscription's quantity, priced per monitor (`config/billing.php`). `None` is a team without a paid plan: on the trial (which uses the trial plan's limits) or unpaid (paused).\n| |\n|---|\n| `none`
No paid plan and no trial: monitoring is paused until the team subscribes. |\n| `starter`
Starter: up to 3 members and 1 status page, the team default escalation path only. |\n| `team`
Team: unlimited members, 5 status pages, on-call, more escalation paths and private status pages. |\n| `business`
Business: everything in Team, with unlimited status pages and more subscribers and notification credits. |", "enum": [ "none", "starter", "team", "business" ], "title": "Plan" }, "Project": { "type": "object", "description": "A project: a group of monitors and hosts that share escalation paths. Every team has one\ndefault project, which can't be deleted.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Project ID" }, "name": { "type": "string", "description": "Project name", "examples": [ "Production" ] }, "is_default": { "type": "boolean", "description": "Whether this is the team's default project, which new monitors and hosts join when no project is given. It can't be deleted" }, "escalation_paths": { "type": "array", "description": "Escalation paths that alerts of this project's monitors and hosts follow, unless a monitor or host sets its own", "items": { "$ref": "#/components/schemas/EscalationPathReference" } }, "created_at": { "type": "string", "format": "date-time", "description": "When the project was created" } }, "required": [ "id", "name", "is_default", "escalation_paths", "created_at" ], "title": "Project" }, "ProjectReference": { "type": "object", "description": "A project a resource belongs to or applies to.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Project ID" }, "name": { "type": "string", "description": "Project name", "examples": [ "Production" ] } }, "required": [ "id", "name" ], "title": "ProjectReference" }, "PublishStatusPageUpdate": { "type": "object", "description": "An update of the team's incident to publish on a status page.", "properties": { "status_page_id": { "type": "string", "format": "uuid", "description": "The status page to publish on" }, "status": { "description": "The public incident's status with this update. `resolved` closes every open impact period\n\n| |\n|---|\n| `investigating`
Declared; the cause isn't known yet. |\n| `identified`
Acknowledged: the cause is known and someone works on it. |\n| `monitoring`
A fix is out; watching whether it holds. |\n| `resolved`
Over. |", "$ref": "#/components/schemas/IncidentStatus" }, "body": { "type": "string", "description": "The message visitors read, in Markdown", "examples": [ "We found the cause and are rolling out a fix." ] }, "impact": { "description": "The public incident's own impact, used while it affects no components; otherwise it follows the components\n\n| |\n|---|\n| `none`
No impact (for a component: not affected). |\n| `degraded_performance`
Slower or less reliable than usual. |\n| `partial_outage`
Down for some visitors or some functions. |\n| `major_outage`
Down. |", "$ref": "#/components/schemas/ImpactLevel" }, "published_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it happened, now or in the past (default now)" }, "affected_components": { "type": "array", "description": "The components it affects as of `published_at`, with their impact; components left out are no longer affected. Leave out to keep the impacts as they are; send `[]` for none. Components of the status page only", "items": { "$ref": "#/components/schemas/StatusPageAffectedComponentInput" } }, "notify_subscribers": { "type": "boolean", "description": "Email confirmed subscribers about the update (default `true`). `false` changes the page without emails" } }, "required": [ "status_page_id", "status", "body" ], "title": "PublishStatusPageUpdate" }, "ResolveIncident": { "type": "object", "description": "How an incident ends.", "properties": { "message": { "type": [ "string", "null" ], "description": "A closing update, in Markdown; leave out for none", "examples": [ "Fixed by rolling back release 412." ] } }, "title": "ResolveIncident" }, "ResourcePauseReason": { "type": "string", "description": "Why the system (not the user) paused a monitor, host, domain or status page.\n| |\n|---|\n| `plan_limit`
Over the plan limit (trial expired, downgrade); the oldest resources stay active. |\n| `team_paused`
The whole team's monitoring is paused (no paid plan, staff action or scheduled deletion). |", "enum": [ "plan_limit", "team_paused" ], "title": "ResourcePauseReason" }, "SavePostmortem": { "type": "object", "description": "An incident's postmortem.", "properties": { "content": { "type": "string", "description": "The whole postmortem, in Markdown; replaces the current one" }, "published": { "type": "boolean", "description": "Mark it as published (final), or as a draft again. Leave out to keep its state" } }, "required": [ "content" ], "title": "SavePostmortem" }, "SaveStatusPageIncidentWriteup": { "type": "object", "description": "The public write-up to save on a status page incident.", "properties": { "content": { "type": [ "string", "null" ], "description": "The write-up, in Markdown, at most 50,000 characters. Required to publish", "examples": [ "On 26 October, card payments failed for 18 minutes after a configuration change." ], "maxLength": 50000 }, "published": { "type": "boolean", "description": "`true` shows it on the public incident page; `false` keeps it as a draft, or takes a published write-up down" }, "notify_subscribers": { "type": "boolean", "description": "Email confirmed subscribers when this publishes the write-up for the first time (default `false`). Edits to a published write-up are never emailed" } }, "required": [ "published" ], "title": "SaveStatusPageIncidentWriteup" }, "ScheduledMaintenance": { "type": "object", "description": "Planned maintenance announced on a status page. While it is in progress its components show as\nunder maintenance.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Maintenance ID" }, "title": { "type": "string", "description": "Title shown on the page", "examples": [ "Database upgrade" ] }, "description": { "type": [ "string", "null" ], "description": "What happens and what visitors notice, in Markdown; `null` for none", "examples": [ "The API is read-only for about ten minutes." ] }, "status": { "description": "Where it stands\n\n| |\n|---|\n| `scheduled`
Announced, not started yet. |\n| `in_progress`
Going on: its components show as under maintenance. |\n| `completed`
Over. |", "$ref": "#/components/schemas/ScheduledMaintenanceStatus" }, "automatic": { "type": "boolean", "description": "`true`: starts at `scheduled_at` and completes at `scheduled_until` by itself (without a planned end it is completed by hand). `false`: only changes when you set `status`" }, "scheduled_at": { "type": "string", "format": "date-time", "description": "Planned start" }, "scheduled_until": { "type": [ "string", "null" ], "format": "date-time", "description": "Planned end; `null` for none" }, "started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it actually went in progress; `null` before" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it completed; `null` before" }, "affected_components": { "type": "array", "description": "Components it affects", "items": { "$ref": "#/components/schemas/StatusPageAffectedComponent" } }, "created_at": { "type": "string", "format": "date-time", "description": "When it was created" } }, "required": [ "id", "title", "description", "status", "automatic", "scheduled_at", "scheduled_until", "started_at", "completed_at", "affected_components", "created_at" ], "title": "ScheduledMaintenance" }, "ScheduledMaintenanceStatus": { "type": "string", "description": "Where a scheduled maintenance stands.\n| |\n|---|\n| `scheduled`
Announced, not started yet. |\n| `in_progress`
Going on: its components show as under maintenance. |\n| `completed`
Over. |", "enum": [ "scheduled", "in_progress", "completed" ], "title": "ScheduledMaintenanceStatus" }, "Severity": { "type": "string", "description": "How urgent an alert or incident is. Escalation paths can branch on it.\n| |\n|---|\n| `critical`
Customers are affected right now. |\n| `high`
Serious, needs attention soon. |\n| `medium`
Should be looked at. |\n| `low`
Informational. |", "enum": [ "critical", "high", "medium", "low" ], "title": "Severity" }, "StatusPage": { "type": "object", "description": "A status page: the public page that shows your components' status, incidents and maintenance.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Status page ID" }, "name": { "type": "string", "description": "Name, shown as the page title", "examples": [ "Acme status" ] }, "slug": { "type": "string", "description": "The page's subdomain under spectate.page", "examples": [ "acme" ] }, "visibility": { "description": "Who can open the page\n\n| |\n|---|\n| `public`
Anyone. |\n| `private`
Visitors with the access link, or the password when the page has one. Part of the Team plan and up. |", "$ref": "#/components/schemas/StatusPageVisibility" }, "status": { "description": "The headline status visitors see: the worst status of the components, and the impact of open incidents that affect no components\n\n| |\n|---|\n| `operational`
Working normally. |\n| `degraded_performance`
Slower or less reliable than usual. |\n| `partial_outage`
Down for some visitors or some functions. |\n| `major_outage`
Down. |\n| `under_maintenance`
In planned maintenance. |", "$ref": "#/components/schemas/ComponentStatus" }, "public_url": { "type": "string", "format": "uri", "description": "Where visitors open the page: the custom domain once it is verified, else the spectate.page address", "examples": [ "https://acme.spectate.page" ] }, "access_url": { "type": "string", "format": "uri", "description": "Opens the page while it is private. Anyone with it gets in; `rotateStatusPageAccessKey` replaces it" }, "custom_domain": { "type": [ "string", "null" ], "description": "Your own domain for the page; `null` for none. Visitors use it once it is verified", "examples": [ "status.acme.com" ] }, "custom_domain_verification": { "anyOf": [ { "description": "The DNS records that verify `custom_domain`; `null` without a custom domain", "$ref": "#/components/schemas/StatusPageCustomDomainVerification" }, { "type": "null" } ] }, "password_protected": { "type": "boolean", "description": "Whether visitors of a private page can also get in with the password" }, "has_password": { "type": "boolean", "description": "Whether the page has a password. The password itself is never returned" }, "language": { "description": "Language of the public page and of subscriber emails\n\n| |\n|---|\n| `en`
English. |\n| `nl`
Dutch. |\n| `de`
German. |\n| `fr`
French. |\n| `es`
Spanish. |\n| `it`
Italian. |", "$ref": "#/components/schemas/StatusPageLanguage" }, "match_browser_language": { "type": "boolean", "description": "Visitors get their browser's language when it is supported, and can switch languages in the footer" }, "theme": { "description": "How the page looks and what it shows", "$ref": "#/components/schemas/StatusPageTheme" }, "collapsed_groups": { "type": "array", "description": "Component groups that start collapsed", "items": { "type": "string" } }, "automation_enabled": { "type": "boolean", "description": "Monitor automation: when a monitor linked to a component goes down, an incident \"{component} is down\" (major outage) opens with `automation_down_message`, and resolves with `automation_recovered_message` when the monitor recovers" }, "automation_down_message": { "type": [ "string", "null" ], "description": "Posted when a linked monitor goes down; `{component}` and `{status_page}` are filled in. `null` for a default message", "examples": [ "We're looking into problems with {component}." ] }, "automation_recovered_message": { "type": [ "string", "null" ], "description": "Posted when the monitor recovers; `null` for a default message", "examples": [ "{component} is working again." ] }, "issue_reports_enabled": { "type": "boolean", "description": "Visitors can report problems from the page" }, "issue_reports_show_on_page": { "type": "boolean", "description": "While reports are above the threshold, the page says that users are reporting issues" }, "issue_reports_alerts_enabled": { "type": "boolean", "description": "Reaching the threshold fires an alert" }, "issue_reports_threshold": { "type": "integer", "description": "Reports within `issue_reports_window_minutes` that count as above the threshold, 1 to 1000" }, "issue_reports_window_minutes": { "type": "integer", "description": "The window for the threshold, in minutes, 1 to 1440" }, "issue_reports_triggered_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Since when reports are above the threshold; `null` when they aren't" }, "traffic_alerts_enabled": { "type": "boolean", "description": "Alert when views reach `traffic_alert_multiplier` times the usual views for the time of day" }, "traffic_alert_multiplier": { "type": "integer", "description": "How many times the usual views alert, 2 to 100" }, "traffic_alert_min_views": { "type": "integer", "description": "Fewer views than this in 15 minutes never alert, 10 to 1000000" }, "escalation_paths": { "type": "array", "description": "Escalation paths the page's alerts (issue reports and traffic spikes) follow; empty for the team's default path", "items": { "$ref": "#/components/schemas/EscalationPathReference" } }, "paused_reason": { "anyOf": [ { "description": "Why the system paused the page (over the plan limit, or the team's monitoring is paused); `null` when it isn't paused\n\n| |\n|---|\n| `plan_limit`
Over the plan limit (trial expired, downgrade); the oldest resources stay active. |\n| `team_paused`
The whole team's monitoring is paused (no paid plan, staff action or scheduled deletion). |", "$ref": "#/components/schemas/ResourcePauseReason" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "When the page was created" } }, "required": [ "id", "name", "slug", "visibility", "status", "public_url", "access_url", "custom_domain", "custom_domain_verification", "password_protected", "has_password", "language", "match_browser_language", "theme", "collapsed_groups", "automation_enabled", "automation_down_message", "automation_recovered_message", "issue_reports_enabled", "issue_reports_show_on_page", "issue_reports_alerts_enabled", "issue_reports_threshold", "issue_reports_window_minutes", "issue_reports_triggered_at", "traffic_alerts_enabled", "traffic_alert_multiplier", "traffic_alert_min_views", "escalation_paths", "paused_reason", "created_at" ], "title": "StatusPage" }, "StatusPageAffectedComponent": { "type": "object", "description": "A component an incident or maintenance affects, and how badly.", "properties": { "component": { "description": "The component", "$ref": "#/components/schemas/StatusPageComponentReference" }, "impact": { "description": "For an incident: the ongoing impact, else the worst it had. For a maintenance: the impact it announces\n\n| |\n|---|\n| `none`
No impact (for a component: not affected). |\n| `degraded_performance`
Slower or less reliable than usual. |\n| `partial_outage`
Down for some visitors or some functions. |\n| `major_outage`
Down. |", "$ref": "#/components/schemas/ImpactLevel" } }, "required": [ "component", "impact" ], "title": "StatusPageAffectedComponent" }, "StatusPageAffectedComponentInput": { "type": "object", "description": "A component an incident or maintenance affects, and how badly.", "properties": { "component_id": { "type": "string", "format": "uuid", "description": "A component of the status page" }, "impact": { "description": "How badly; `none` for not affected\n\n| |\n|---|\n| `none`
No impact (for a component: not affected). |\n| `degraded_performance`
Slower or less reliable than usual. |\n| `partial_outage`
Down for some visitors or some functions. |\n| `major_outage`
Down. |", "$ref": "#/components/schemas/ImpactLevel" } }, "required": [ "component_id", "impact" ], "title": "StatusPageAffectedComponentInput" }, "StatusPageAffectedComponentInputRequest": { "type": "object", "description": "A component an incident or maintenance affects, and how badly.", "properties": { "component_id": { "type": "string", "format": "uuid", "description": "A component of the status page" }, "impact": { "description": "How badly; `none` for not affected\n\n| |\n|---|\n| `none`
No impact (for a component: not affected). |\n| `degraded_performance`
Slower or less reliable than usual. |\n| `partial_outage`
Down for some visitors or some functions. |\n| `major_outage`
Down. |", "$ref": "#/components/schemas/ImpactLevel" } }, "required": [ "component_id", "impact" ], "title": "StatusPageAffectedComponentInputRequest" }, "StatusPageComponent": { "type": "object", "description": "A component of a status page: a part of your service visitors see the status of, optionally\nfollowing a monitor.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Component ID" }, "name": { "type": "string", "description": "Name shown on the page", "examples": [ "API" ] }, "description": { "type": [ "string", "null" ], "description": "Text shown with the name; `null` for none", "examples": [ "Our public REST API." ] }, "group": { "type": [ "string", "null" ], "description": "Group the component is shown in; `null` for the page's default group", "examples": [ "Backend" ] }, "position": { "type": "integer", "description": "Order within the group, lowest first" }, "status": { "description": "The status, derived and read-only: the worst ongoing impact of an unresolved incident, then `under_maintenance` during maintenance, else `operational`\n\n| |\n|---|\n| `operational`
Working normally. |\n| `degraded_performance`
Slower or less reliable than usual. |\n| `partial_outage`
Down for some visitors or some functions. |\n| `major_outage`
Down. |\n| `under_maintenance`
In planned maintenance. |", "$ref": "#/components/schemas/ComponentStatus" }, "monitor": { "anyOf": [ { "description": "The monitor whose uptime history and response times the component shows, and whose downtime opens an incident when monitor automation is on; `null` for none", "$ref": "#/components/schemas/MonitorReference" }, { "type": "null" } ] }, "show_latency_chart": { "type": "boolean", "description": "Whether the page shows the monitor's response time chart under the component" }, "created_at": { "type": "string", "format": "date-time", "description": "When the component was created" } }, "required": [ "id", "name", "description", "group", "position", "status", "monitor", "show_latency_chart", "created_at" ], "title": "StatusPageComponent" }, "StatusPageComponentReference": { "type": "object", "description": "A component of the status page.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Component ID" }, "name": { "type": "string", "description": "Component name", "examples": [ "API" ] } }, "required": [ "id", "name" ], "title": "StatusPageComponentReference" }, "StatusPageCustomDomainCheck": { "type": "object", "description": "The result of looking up a custom domain's DNS records.", "properties": { "domain": { "type": "string", "description": "The domain", "examples": [ "status.example.com" ] }, "verified": { "type": "boolean", "description": "Whether ownership is proven, now or earlier. A proven domain stays verified when a later check fails" }, "verified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When ownership was proven; `null` before" }, "records": { "type": "array", "description": "The records that can verify the domain; one passing record is enough", "items": { "$ref": "#/components/schemas/StatusPageDnsRecordCheck" } }, "routed": { "type": "boolean", "description": "Whether visitors reach the page: the domain points at it by CNAME or resolves to the same addresses. The page and its certificate need this; the certificate is issued on the first visit" }, "addresses": { "type": "array", "description": "Addresses the domain resolves to (A and AAAA records)", "items": { "type": "string" } }, "checked_at": { "type": "string", "format": "date-time", "description": "When DNS was checked" } }, "required": [ "domain", "verified", "verified_at", "records", "routed", "addresses", "checked_at" ], "title": "StatusPageCustomDomainCheck" }, "StatusPageCustomDomainVerification": { "type": "object", "description": "How to prove you own a status page's custom domain: create the TXT record, or point the domain\nat the CNAME target (which also routes visitors to the page). Then call\n`verifyStatusPageCustomDomain`.", "properties": { "verified": { "type": "boolean", "description": "Whether ownership is proven. A proven domain stays verified when a later check fails" }, "verified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When ownership was proven; `null` before" }, "txt_record_name": { "type": "string", "description": "Name of the TXT record to create", "examples": [ "_spectate.status.example.com" ] }, "txt_record_value": { "type": "string", "description": "Value of the TXT record", "examples": [ "spectate-verify=4f1c0c2e9b7a4d3f8e6a5b2c1d0e9f8a" ] }, "cname_target": { "type": "string", "description": "Host to point a CNAME at (subdomains), or an ALIAS (root domains); unique to the page", "examples": [ "4f1c0c2e9b7a4d3f.custom.spectate.page" ] } }, "required": [ "verified", "verified_at", "txt_record_name", "txt_record_value", "cname_target" ], "title": "StatusPageCustomDomainVerification" }, "StatusPageDisplay": { "type": "object", "description": "What a status page shows.", "properties": { "show_uptime_history": { "type": "boolean", "description": "Show each component's uptime history" }, "show_latency_charts": { "type": "boolean", "description": "Show response time charts under components that have them on" }, "show_incidents": { "type": "boolean", "description": "Show incidents" }, "show_maintenances": { "type": "boolean", "description": "Show scheduled maintenance" }, "show_subscriptions": { "type": "boolean", "description": "Let visitors subscribe to updates by email (when the plan includes subscribers)" }, "history_layout": { "description": "How the uptime history is laid out\n\n| |\n|---|\n| `calendar`
A calendar of days (default). |\n| `timeline`
One row of bars per component. |", "$ref": "#/components/schemas/StatusPageHistoryLayout" }, "uptime_bars": { "description": "How a day with problems is drawn in the uptime history\n\n| |\n|---|\n| `fill`
Colour part of the bar, by how long the problem lasted (default). |\n| `solid`
Colour the whole bar. |", "$ref": "#/components/schemas/StatusPageUptimeBars" } }, "required": [ "show_uptime_history", "show_latency_charts", "show_incidents", "show_maintenances", "show_subscriptions", "history_layout", "uptime_bars" ], "title": "StatusPageDisplay" }, "StatusPageDisplayInput": { "type": "object", "description": "What a status page shows; settings left out keep their value.", "properties": { "show_uptime_history": { "type": "boolean", "description": "Show each component's uptime history" }, "show_latency_charts": { "type": "boolean", "description": "Show response time charts under components that have them on" }, "show_incidents": { "type": "boolean", "description": "Show incidents" }, "show_maintenances": { "type": "boolean", "description": "Show scheduled maintenance" }, "show_subscriptions": { "type": "boolean", "description": "Let visitors subscribe to updates by email (when the plan includes subscribers)" }, "history_layout": { "description": "How the uptime history is laid out\n\n| |\n|---|\n| `calendar`
A calendar of days (default). |\n| `timeline`
One row of bars per component. |", "$ref": "#/components/schemas/StatusPageHistoryLayout" }, "uptime_bars": { "description": "How a day with problems is drawn in the uptime history\n\n| |\n|---|\n| `fill`
Colour part of the bar, by how long the problem lasted (default). |\n| `solid`
Colour the whole bar. |", "$ref": "#/components/schemas/StatusPageUptimeBars" } }, "title": "StatusPageDisplayInput" }, "StatusPageDnsRecordCheck": { "type": "object", "description": "One DNS record that can verify a custom domain, with what DNS returned for it.", "properties": { "type": { "description": "Record type: `CNAME` or `TXT`", "$ref": "#/components/schemas/DnsRecordType" }, "name": { "type": "string", "description": "Record name", "examples": [ "_spectate.status.example.com" ] }, "expected": { "type": "string", "description": "The value it needs", "examples": [ "spectate-verify=4f1c0c2e9b7a4d3f8e6a5b2c1d0e9f8a" ] }, "found": { "type": "array", "description": "The values DNS returned; empty when there is no such record", "items": { "type": "string" } }, "ok": { "type": "boolean", "description": "Whether this record passes" } }, "required": [ "type", "name", "expected", "found", "ok" ], "title": "StatusPageDnsRecordCheck" }, "StatusPageFont": { "type": "string", "description": "Typefaces of a status page.\n| |\n|---|\n| `geist`
Geist (default). |\n| `inter`
Inter. |\n| `ibm-plex-sans`
IBM Plex Sans. |\n| `dm-sans`
DM Sans. |\n| `manrope`
Manrope. |\n| `space-grotesk`
Space Grotesk. |\n| `source-serif`
Source Serif. |\n| `system`
The visitor's system font. |", "enum": [ "geist", "inter", "ibm-plex-sans", "dm-sans", "manrope", "space-grotesk", "source-serif", "system" ], "title": "StatusPageFont" }, "StatusPageHistoryLayout": { "type": "string", "description": "How a status page shows the uptime history of its components.\n| |\n|---|\n| `calendar`
A calendar of days (default). |\n| `timeline`
One row of bars per component. |", "enum": [ "calendar", "timeline" ], "title": "StatusPageHistoryLayout" }, "StatusPageImpactPeriod": { "type": "object", "description": "A period during which an incident affected a component. Periods drive the component's status\nand its uptime history.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Period ID" }, "component": { "description": "The affected component", "$ref": "#/components/schemas/StatusPageComponentReference" }, "impact": { "description": "How badly\n\n| |\n|---|\n| `degraded_performance`
Slower or less reliable than usual. |\n| `partial_outage`
Down for some visitors or some functions. |\n| `major_outage`
Down. |", "$ref": "#/components/schemas/ComponentImpact" }, "started_at": { "type": "string", "format": "date-time", "description": "When it started" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it ended; `null` while it goes on" }, "duration_seconds": { "type": "integer", "description": "How long it lasted so far, in seconds" } }, "required": [ "id", "component", "impact", "started_at", "ended_at", "duration_seconds" ], "title": "StatusPageImpactPeriod" }, "StatusPageIncident": { "type": "object", "description": "A public incident on a status page: what visitors read, separate from the team's own incident\n(which can publish to it). Its impact on components is a timeline of periods.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Status page incident ID" }, "title": { "type": "string", "description": "Title shown on the page", "examples": [ "Elevated API error rates" ] }, "status": { "description": "Where it stands: the status of its latest update\n\n| |\n|---|\n| `investigating`
Declared; the cause isn't known yet. |\n| `identified`
Acknowledged: the cause is known and someone works on it. |\n| `monitoring`
A fix is out; watching whether it holds. |\n| `resolved`
Over. |", "$ref": "#/components/schemas/IncidentStatus" }, "impact": { "description": "The worst ongoing impact of its periods (the peak once resolved), `none` without one. An incident that affects no components keeps the impact it was given\n\n| |\n|---|\n| `none`
No impact (for a component: not affected). |\n| `degraded_performance`
Slower or less reliable than usual. |\n| `partial_outage`
Down for some visitors or some functions. |\n| `major_outage`
Down. |", "$ref": "#/components/schemas/ImpactLevel" }, "incident_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The team's incident that publishes to it; `null` for none" }, "automated": { "type": "boolean", "description": "Opened by monitor automation and still managed by it, until someone posts an update or edits its timeline" }, "updates": { "type": "array", "description": "Updates, newest first", "items": { "$ref": "#/components/schemas/StatusPageIncidentUpdate" } }, "affected_components": { "type": "array", "description": "Components it affects or affected", "items": { "$ref": "#/components/schemas/StatusPageAffectedComponent" } }, "impacts": { "type": "array", "description": "The impact timeline, oldest first", "items": { "$ref": "#/components/schemas/StatusPageImpactPeriod" } }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was resolved; `null` while open" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was created" }, "writeup": { "anyOf": [ { "description": "Its public write-up, published or a draft; `null` when it has none", "$ref": "#/components/schemas/StatusPageIncidentWriteup" }, { "type": "null" } ] } }, "required": [ "id", "title", "status", "impact", "incident_id", "automated", "updates", "affected_components", "impacts", "resolved_at", "created_at", "writeup" ], "title": "StatusPageIncident" }, "StatusPageIncidentUpdate": { "type": "object", "description": "An update of a status page incident, as visitors read it.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Update ID" }, "status": { "description": "The incident's status with this update\n\n| |\n|---|\n| `investigating`
Declared; the cause isn't known yet. |\n| `identified`
Acknowledged: the cause is known and someone works on it. |\n| `monitoring`
A fix is out; watching whether it holds. |\n| `resolved`
Over. |", "$ref": "#/components/schemas/IncidentStatus" }, "body": { "type": "string", "description": "The message, in Markdown", "examples": [ "We found the cause and are rolling out a fix." ] }, "published_at": { "type": "string", "format": "date-time", "description": "When it happened; updates are ordered by it" }, "created_at": { "type": "string", "format": "date-time", "description": "When it was written" } }, "required": [ "id", "status", "body", "published_at", "created_at" ], "title": "StatusPageIncidentUpdate" }, "StatusPageIncidentWriteup": { "type": "object", "description": "A public write-up of a status page incident: what happened and what changes, for visitors.\nPublished, it shows on the public incident page; otherwise it's a draft only the team sees.", "properties": { "content": { "type": "string", "description": "The write-up, in Markdown", "examples": [ "On 26 October, card payments failed for 18 minutes after a configuration change." ] }, "published": { "type": "boolean", "description": "Whether visitors see it on the public incident page" }, "published_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was first published; `null` while it's a draft. Editing a published write-up keeps this time" } }, "required": [ "content", "published", "published_at" ], "title": "StatusPageIncidentWriteup" }, "StatusPageIssueReport": { "type": "object", "description": "A problem a visitor reported from the public page.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Report ID" }, "message": { "type": [ "string", "null" ], "description": "What the visitor wrote; `null` for nothing", "examples": [ "Checkout keeps timing out." ] }, "email": { "type": [ "string", "null" ], "format": "email", "description": "The address the visitor left for a reply. Only returned to tokens with `status-pages:write`; `null` for others (see `has_email`) and when they left none", "examples": [ "jane@example.com" ] }, "has_email": { "type": "boolean", "description": "Whether the visitor left an email address, also when it isn't returned" }, "components": { "type": "array", "description": "Components the visitor picked; deleted components are left out", "items": { "$ref": "#/components/schemas/StatusPageComponentReference" } }, "created_at": { "type": "string", "format": "date-time", "description": "When it was reported" } }, "required": [ "id", "message", "email", "has_email", "components", "created_at" ], "title": "StatusPageIssueReport" }, "StatusPageLanguage": { "type": "string", "description": "Languages of the public status page chrome and the subscriber emails. Customer-written content (names, incident titles and updates) is never translated.\n| |\n|---|\n| `en`
English. |\n| `nl`
Dutch. |\n| `de`
German. |\n| `fr`
French. |\n| `es`
Spanish. |\n| `it`
Italian. |", "enum": [ "en", "nl", "de", "fr", "es", "it" ], "title": "StatusPageLanguage" }, "StatusPageSubscriber": { "type": "object", "description": "Someone who subscribed to a status page's updates by email. Only confirmed subscribers (double\nopt-in) get emails.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Subscriber ID" }, "email": { "type": "string", "format": "email", "description": "Email address", "examples": [ "jane@example.com" ] }, "confirmed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When they confirmed the subscription; `null` while it awaits confirmation" }, "language": { "description": "Language of their emails: the page's language when they subscribed, or the one they read the page in\n\n| |\n|---|\n| `en`
English. |\n| `nl`
Dutch. |\n| `de`
German. |\n| `fr`
French. |\n| `es`
Spanish. |\n| `it`
Italian. |", "$ref": "#/components/schemas/StatusPageLanguage" }, "created_at": { "type": "string", "format": "date-time", "description": "When they subscribed" } }, "required": [ "id", "email", "confirmed_at", "language", "created_at" ], "title": "StatusPageSubscriber" }, "StatusPageTheme": { "type": "object", "description": "How a status page looks. `null` values use the default.", "properties": { "accent": { "type": [ "string", "null" ], "description": "Brand colour, as hex; `null` for Spectate's yellow (`#ffea00`)", "examples": [ "#0f766e" ] }, "mode": { "anyOf": [ { "description": "Colour scheme visitors get before they pick one; `null` for `light`\n\n| |\n|---|\n| `light`
Light. |\n| `dark`
Dark. |\n| `system`
The visitor's operating system setting. |", "$ref": "#/components/schemas/StatusPageThemeMode" }, { "type": "null" } ] }, "preset": { "anyOf": [ { "description": "Colour preset; `null` for `spectate`\n\n| |\n|---|\n| `spectate`
Neutral greys (default). |\n| `paper`
Warm cream and sepia ink. |\n| `graphite`
Soft charcoal, strong lines. |\n| `ocean`
Clear blues, navy in dark mode. |\n| `forest`
Sage greens, deep pine in dark mode. |\n| `lavender`
Lilac, aubergine in dark mode. |\n| `ember`
Peach and terracotta, warm in dark mode. |\n| `contrast`
High contrast: pure black and white, bold lines. |", "$ref": "#/components/schemas/StatusPageThemePreset" }, { "type": "null" } ] }, "font": { "anyOf": [ { "description": "Typeface; `null` for `geist`\n\n| |\n|---|\n| `geist`
Geist (default). |\n| `inter`
Inter. |\n| `ibm-plex-sans`
IBM Plex Sans. |\n| `dm-sans`
DM Sans. |\n| `manrope`
Manrope. |\n| `space-grotesk`
Space Grotesk. |\n| `source-serif`
Source Serif. |\n| `system`
The visitor's system font. |", "$ref": "#/components/schemas/StatusPageFont" }, { "type": "null" } ] }, "light": { "description": "Colours overriding the preset in light mode", "$ref": "#/components/schemas/StatusPageThemeColors" }, "dark": { "description": "Colours overriding the preset in dark mode", "$ref": "#/components/schemas/StatusPageThemeColors" }, "display": { "description": "What the page shows", "$ref": "#/components/schemas/StatusPageDisplay" }, "logo_url": { "type": [ "string", "null" ], "format": "uri", "description": "The logo, uploaded in the dashboard; `null` for none (the page shows its name)" }, "logo_dark_url": { "type": [ "string", "null" ], "format": "uri", "description": "The logo for dark mode; `null` shows `logo_url` in dark mode too" }, "favicon_url": { "type": [ "string", "null" ], "format": "uri", "description": "The favicon, uploaded in the dashboard; `null` for Spectate's" } }, "required": [ "accent", "mode", "preset", "font", "light", "dark", "display", "logo_url", "logo_dark_url", "favicon_url" ], "title": "StatusPageTheme" }, "StatusPageThemeColors": { "type": "object", "description": "Colours that override the preset in one colour scheme, as hex (`#0f766e`). `null` keeps the\npreset's colour.", "properties": { "background": { "type": [ "string", "null" ], "description": "Page background", "examples": [ "#ffffff" ] }, "surface": { "type": [ "string", "null" ], "description": "Background of cards and panels", "examples": [ "#f8fafc" ] }, "foreground": { "type": [ "string", "null" ], "description": "Text", "examples": [ "#0f172a" ] }, "muted": { "type": [ "string", "null" ], "description": "Secondary text", "examples": [ "#64748b" ] }, "border": { "type": [ "string", "null" ], "description": "Lines and borders", "examples": [ "#e2e8f0" ] }, "success": { "type": [ "string", "null" ], "description": "Operational", "examples": [ "#16a34a" ] }, "warning": { "type": [ "string", "null" ], "description": "Degraded performance and maintenance", "examples": [ "#ca8a04" ] }, "partial": { "type": [ "string", "null" ], "description": "Partial outage", "examples": [ "#ea580c" ] }, "danger": { "type": [ "string", "null" ], "description": "Major outage", "examples": [ "#dc2626" ] }, "info": { "type": [ "string", "null" ], "description": "Information, such as scheduled maintenance", "examples": [ "#2563eb" ] } }, "required": [ "background", "surface", "foreground", "muted", "border", "success", "warning", "partial", "danger", "info" ], "title": "StatusPageThemeColors" }, "StatusPageThemeColorsInput": { "type": "object", "description": "Colours that override the preset in one colour scheme, as hex (`#0f766e` or `#0f7`). Colours\nleft out keep their value; `null` goes back to the preset's colour.", "properties": { "background": { "type": [ "string", "null" ], "description": "Page background", "pattern": "^#(?:[0-9a-f]{3}|[0-9a-f]{6})$", "examples": [ "#ffffff" ] }, "surface": { "type": [ "string", "null" ], "description": "Background of cards and panels", "pattern": "^#(?:[0-9a-f]{3}|[0-9a-f]{6})$", "examples": [ "#f8fafc" ] }, "foreground": { "type": [ "string", "null" ], "description": "Text", "pattern": "^#(?:[0-9a-f]{3}|[0-9a-f]{6})$", "examples": [ "#0f172a" ] }, "muted": { "type": [ "string", "null" ], "description": "Secondary text", "pattern": "^#(?:[0-9a-f]{3}|[0-9a-f]{6})$", "examples": [ "#64748b" ] }, "border": { "type": [ "string", "null" ], "description": "Lines and borders", "pattern": "^#(?:[0-9a-f]{3}|[0-9a-f]{6})$", "examples": [ "#e2e8f0" ] }, "success": { "type": [ "string", "null" ], "description": "Operational", "pattern": "^#(?:[0-9a-f]{3}|[0-9a-f]{6})$", "examples": [ "#16a34a" ] }, "warning": { "type": [ "string", "null" ], "description": "Degraded performance and maintenance", "pattern": "^#(?:[0-9a-f]{3}|[0-9a-f]{6})$", "examples": [ "#ca8a04" ] }, "partial": { "type": [ "string", "null" ], "description": "Partial outage", "pattern": "^#(?:[0-9a-f]{3}|[0-9a-f]{6})$", "examples": [ "#ea580c" ] }, "danger": { "type": [ "string", "null" ], "description": "Major outage", "pattern": "^#(?:[0-9a-f]{3}|[0-9a-f]{6})$", "examples": [ "#dc2626" ] }, "info": { "type": [ "string", "null" ], "description": "Information, such as scheduled maintenance", "pattern": "^#(?:[0-9a-f]{3}|[0-9a-f]{6})$", "examples": [ "#2563eb" ] } }, "title": "StatusPageThemeColorsInput" }, "StatusPageThemeInput": { "type": "object", "description": "Changes to how a status page looks. Settings left out keep their value, also inside `light`,\n`dark` and `display`; `null` goes back to the default. Logos and the favicon are uploaded in\nthe dashboard.", "properties": { "accent": { "type": [ "string", "null" ], "description": "Brand colour, as hex; `null` for Spectate's yellow", "pattern": "^#(?:[0-9a-f]{3}|[0-9a-f]{6})$", "examples": [ "#0f766e" ] }, "mode": { "anyOf": [ { "description": "Colour scheme visitors get before they pick one; `null` for `light`\n\n| |\n|---|\n| `light`
Light. |\n| `dark`
Dark. |\n| `system`
The visitor's operating system setting. |", "$ref": "#/components/schemas/StatusPageThemeMode" }, { "type": "null" } ] }, "preset": { "anyOf": [ { "description": "Colour preset; `null` for `spectate`\n\n| |\n|---|\n| `spectate`
Neutral greys (default). |\n| `paper`
Warm cream and sepia ink. |\n| `graphite`
Soft charcoal, strong lines. |\n| `ocean`
Clear blues, navy in dark mode. |\n| `forest`
Sage greens, deep pine in dark mode. |\n| `lavender`
Lilac, aubergine in dark mode. |\n| `ember`
Peach and terracotta, warm in dark mode. |\n| `contrast`
High contrast: pure black and white, bold lines. |", "$ref": "#/components/schemas/StatusPageThemePreset" }, { "type": "null" } ] }, "font": { "anyOf": [ { "description": "Typeface; `null` for `geist`\n\n| |\n|---|\n| `geist`
Geist (default). |\n| `inter`
Inter. |\n| `ibm-plex-sans`
IBM Plex Sans. |\n| `dm-sans`
DM Sans. |\n| `manrope`
Manrope. |\n| `space-grotesk`
Space Grotesk. |\n| `source-serif`
Source Serif. |\n| `system`
The visitor's system font. |", "$ref": "#/components/schemas/StatusPageFont" }, { "type": "null" } ] }, "light": { "anyOf": [ { "description": "Colours overriding the preset in light mode; `null` removes them all", "$ref": "#/components/schemas/StatusPageThemeColorsInput" }, { "type": "null" } ] }, "dark": { "anyOf": [ { "description": "Colours overriding the preset in dark mode; `null` removes them all", "$ref": "#/components/schemas/StatusPageThemeColorsInput" }, { "type": "null" } ] }, "display": { "description": "What the page shows", "$ref": "#/components/schemas/StatusPageDisplayInput" } }, "title": "StatusPageThemeInput" }, "StatusPageThemeMode": { "type": "string", "description": "The colour scheme visitors of a status page get before they pick one.\n| |\n|---|\n| `light`
Light. |\n| `dark`
Dark. |\n| `system`
The visitor's operating system setting. |", "enum": [ "light", "dark", "system" ], "title": "StatusPageThemeMode" }, "StatusPageThemePreset": { "type": "string", "description": "Colour presets of a status page. Colours set in `light` and `dark` override the preset.\n| |\n|---|\n| `spectate`
Neutral greys (default). |\n| `paper`
Warm cream and sepia ink. |\n| `graphite`
Soft charcoal, strong lines. |\n| `ocean`
Clear blues, navy in dark mode. |\n| `forest`
Sage greens, deep pine in dark mode. |\n| `lavender`
Lilac, aubergine in dark mode. |\n| `ember`
Peach and terracotta, warm in dark mode. |\n| `contrast`
High contrast: pure black and white, bold lines. |", "enum": [ "spectate", "paper", "graphite", "ocean", "forest", "lavender", "ember", "contrast" ], "title": "StatusPageThemePreset" }, "StatusPageUptimeBars": { "type": "string", "description": "How a day with problems is drawn in a status page's uptime history.\n| |\n|---|\n| `fill`
Colour part of the bar, by how long the problem lasted (default). |\n| `solid`
Colour the whole bar. |", "enum": [ "fill", "solid" ], "title": "StatusPageUptimeBars" }, "StatusPageVisibility": { "type": "string", "description": "Who can open a status page.\n| |\n|---|\n| `public`
Anyone. |\n| `private`
Visitors with the access link, or the password when the page has one. Part of the Team plan and up. |", "enum": [ "public", "private" ], "title": "StatusPageVisibility" }, "Subscription": { "type": "object", "description": "The team's paid subscription.", "properties": { "plan": { "description": "The plan paid for\n\n| |\n|---|\n| `none`
No paid plan and no trial: monitoring is paused until the team subscribes. |\n| `starter`
Starter: up to 3 members and 1 status page, the team default escalation path only. |\n| `team`
Team: unlimited members, 5 status pages, on-call, more escalation paths and private status pages. |\n| `business`
Business: everything in Team, with unlimited status pages and more subscribers and notification credits. |", "$ref": "#/components/schemas/Plan" }, "interval": { "description": "How often it's billed\n\n| |\n|---|\n| `month`
Billed every month. |\n| `year`
Billed every year, for the price of 10 months. |", "$ref": "#/components/schemas/BillingInterval" }, "quantity": { "type": "integer", "description": "Monitors and hosts paid for: the team's limit of both together" }, "status": { "description": "Where it stands at the payment provider\n\n| |\n|---|\n| `created`
Created; the first payment hasn't gone through yet. |\n| `trial`
In a trial period. |\n| `active`
Paid and running. |\n| `on_grace_period`
Cancelled, running until the end of the paid period. |\n| `paused`
Paused. |\n| `canceled`
Ended. |", "$ref": "#/components/schemas/SubscriptionStatus" }, "cancelled": { "type": "boolean", "description": "Whether it's cancelled and runs until `current_period_ends_at`; it can be resumed in the dashboard until then" }, "renews_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it renews; `null` when it won't" }, "current_period_ends_at": { "type": [ "string", "null" ], "format": "date-time", "description": "End of the period paid for" }, "payment_method": { "type": [ "string", "null" ], "description": "How it's paid; `null` when unknown", "examples": [ "Card ending in 4242" ] } }, "required": [ "plan", "interval", "quantity", "status", "cancelled", "renews_at", "current_period_ends_at", "payment_method" ], "title": "Subscription" }, "SubscriptionStatus": { "type": "string", "description": "Where a subscription stands at the payment provider.\n| |\n|---|\n| `created`
Created; the first payment hasn't gone through yet. |\n| `trial`
In a trial period. |\n| `active`
Paid and running. |\n| `on_grace_period`
Cancelled, running until the end of the paid period. |\n| `paused`
Paused. |\n| `canceled`
Ended. |", "enum": [ "created", "trial", "active", "on_grace_period", "paused", "canceled" ], "title": "SubscriptionStatus" }, "Team": { "type": "object", "description": "The team the API token belongs to.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Team ID" }, "name": { "type": "string", "description": "Name", "examples": [ "Acme" ] }, "email": { "type": [ "string", "null" ], "format": "email", "description": "The team's billing email: Spectate gives it to Vatly, which sends the invoices and receipts, at the team's first checkout (a plan or credits). `null` to use the address of the member who starts that checkout", "examples": [ "ops@acme.com" ] }, "timezone": { "type": "string", "description": "The team's time zone; escalation path working hours without a time zone of their own use it", "examples": [ "Europe/Amsterdam" ] }, "plan": { "description": "The plan whose limits apply now: the trial plan during the trial\n\n| |\n|---|\n| `none`
No paid plan and no trial: monitoring is paused until the team subscribes. |\n| `starter`
Starter: up to 3 members and 1 status page, the team default escalation path only. |\n| `team`
Team: unlimited members, 5 status pages, on-call, more escalation paths and private status pages. |\n| `business`
Business: everything in Team, with unlimited status pages and more subscribers and notification credits. |", "$ref": "#/components/schemas/Plan" }, "on_trial": { "type": "boolean", "description": "Whether the team is on its trial, without a paid plan yet" }, "trial_ends_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the trial ends; `null` without one" }, "monitoring_paused_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Since when all monitoring is paused; `null` while it runs" }, "monitoring_paused_reason": { "anyOf": [ { "description": "Why monitoring is paused; `null` while it runs\n\n| |\n|---|\n| `unpaid`
No paid plan: the trial or the subscription ended. Resumes when the team subscribes. |\n| `deletion_scheduled`
The team is scheduled for deletion. |\n| `staff`
Paused by Spectate staff from Overwatch (abuse, payment issues, on request). |", "$ref": "#/components/schemas/TeamPauseReason" }, { "type": "null" } ] }, "deletion_scheduled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the team and all its data will be deleted; `null` when it isn't scheduled. An owner can cancel it in the dashboard" }, "deletion_reason": { "anyOf": [ { "description": "Why the team is scheduled for deletion; `null` when it isn't\n\n| |\n|---|\n| `requested`
An owner deleted the team. |\n| `unpaid`
Monitoring was paused for too long without a paid plan (`team_lifecycle.unpaid`). |", "$ref": "#/components/schemas/TeamDeletionReason" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time", "description": "When the team was created" } }, "required": [ "id", "name", "email", "timezone", "plan", "on_trial", "trial_ends_at", "monitoring_paused_at", "monitoring_paused_reason", "deletion_scheduled_at", "deletion_reason", "created_at" ], "title": "Team" }, "TeamDeletionReason": { "type": "string", "description": "| |\n|---|\n| `requested`
An owner deleted the team. |\n| `unpaid`
Monitoring was paused for too long without a paid plan (`team_lifecycle.unpaid`). |", "enum": [ "requested", "unpaid" ], "title": "TeamDeletionReason" }, "TeamPauseReason": { "type": "string", "description": "| |\n|---|\n| `unpaid`
No paid plan: the trial or the subscription ended. Resumes when the team subscribes. |\n| `deletion_scheduled`
The team is scheduled for deletion. |\n| `staff`
Paused by Spectate staff from Overwatch (abuse, payment issues, on request). |", "enum": [ "unpaid", "deletion_scheduled", "staff" ], "title": "TeamPauseReason" }, "TeamRole": { "type": "string", "description": "A member's role in the team: what they may do.\n| |\n|---|\n| `owner`
Everything, including billing and deleting the team. One per team. |\n| `manager`
Everything but billing and deleting the team. |\n| `admin`
Configure monitoring, alerting, incidents and status pages; can't manage members or API tokens. |\n| `member`
Read everything; manage monitors and incidents, acknowledge alerts. |\n| `billing`
Billing and support only. |", "enum": [ "owner", "manager", "admin", "member", "billing" ], "title": "TeamRole" }, "TestChannel": { "type": "object", "description": "Options of a channel test.", "properties": { "enable": { "type": "boolean", "description": "Enable the channel again when the test succeeds, also after Spectate turned it off. Default `false`" } }, "title": "TestChannel" }, "TlsMode": { "type": "string", "description": "How TCP and mail monitors use TLS: not at all, from the first byte (implicit TLS, e.g. 465/993/995), or by upgrading a plaintext session with STARTTLS (SMTP), STARTTLS (IMAP) or STLS (POP3).\n| |\n|---|\n| `none`
Plain TCP, no TLS. |\n| `tls`
TLS from the first byte (implicit TLS), as on ports 465, 993 and 995. |\n| `starttls`
Upgrade a plaintext session: STARTTLS (SMTP, IMAP) or STLS (POP3). Mail monitors only. |", "enum": [ "none", "tls", "starttls" ], "title": "TlsMode" }, "UpdateAlertSource": { "type": "object", "description": "Changes to an alert source; fields you leave out keep their value. Its type can't change.", "properties": { "name": { "type": "string", "description": "Name shown on its alerts", "examples": [ "Production Alertmanager" ], "maxLength": 255 }, "enabled": { "type": "boolean", "description": "Whether requests fire alerts" }, "default_severity": { "description": "Severity of alerts sent without one\n\n| |\n|---|\n| `critical`
Customers are affected right now. |\n| `high`
Serious, needs attention soon. |\n| `medium`
Should be looked at. |\n| `low`
Informational. |", "$ref": "#/components/schemas/Severity" }, "auto_resolve_minutes": { "type": [ "integer", "null" ], "description": "Minutes, 5 to 10080, after which an alert the tool stopped repeating resolves; `null` keeps it until resolved", "minimum": 5, "maximum": 10080 }, "secret": { "type": [ "string", "null" ], "description": "Signing secret; an empty string or `null` removes it. Write-only", "maxLength": 255 }, "settings": { "description": "Type-specific settings; settings you leave out keep their value", "$ref": "#/components/schemas/AlertSourceSettingsInput" }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Project whose escalation paths apply; `null` for none" }, "escalation_path_ids": { "type": "array", "description": "Escalation paths for the source's alerts; replaces the current ones", "items": { "type": "string", "format": "uuid" }, "uniqueItems": true } }, "title": "UpdateAlertSource" }, "UpdateChannel": { "type": "object", "description": "Changes to a channel; fields you leave out keep their value. A channel's type can't change. Its\nsettings object, when you send it, replaces the current settings, secrets included.", "properties": { "name": { "type": "string", "description": "Name shown in escalation paths", "examples": [ "On-call email" ], "maxLength": 255 }, "enabled": { "type": "boolean", "description": "Turn delivery on or off. Turning it on clears an automatic disable and its failure count" }, "email": { "description": "New settings of an `email` channel", "$ref": "#/components/schemas/ChannelEmail" }, "slack": { "description": "New settings of a `slack` channel", "$ref": "#/components/schemas/ChannelSlackInput" }, "discord": { "description": "New settings of a `discord` channel", "$ref": "#/components/schemas/ChannelWebhookUrlInput" }, "microsoft_teams": { "description": "New settings of a `microsoft_teams` channel", "$ref": "#/components/schemas/ChannelWebhookUrlInput" }, "webhook": { "description": "New settings of a `webhook` channel", "$ref": "#/components/schemas/ChannelWebhookInput" }, "pushover": { "description": "New settings of a `pushover` channel", "$ref": "#/components/schemas/ChannelPushoverInput" }, "sms": { "description": "New settings of an `sms` channel", "$ref": "#/components/schemas/ChannelPhone" }, "voice": { "description": "New settings of a `voice` channel", "$ref": "#/components/schemas/ChannelPhone" } }, "title": "UpdateChannel" }, "UpdateDomain": { "type": "object", "description": "Changes to a monitored domain; fields you leave out keep their value.", "properties": { "name": { "type": "string", "description": "Another domain to monitor instead; its registry data is looked up again", "examples": [ "example.org" ], "maxLength": 255 }, "enabled": { "type": "boolean", "description": "Pause (`false`) or resume (`true`) monitoring. Resuming goes through the plan's domain limit" }, "expiry_threshold_days": { "type": "integer", "description": "Days before expiry, 1 to 365, that the \"expires soon\" alert fires", "minimum": 1, "maximum": 365 }, "alert_on_registry_changes": { "type": "boolean", "description": "Raise an alert when the registrar, nameservers or DNSSEC keys change" }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Project of the domain; `null` for none" }, "escalation_path_ids": { "type": "array", "description": "Escalation paths for the domain's alerts; replaces the current ones", "items": { "type": "string", "format": "uuid" } } }, "title": "UpdateDomain" }, "UpdateEscalationPath": { "type": "object", "description": "Changes to an escalation path; fields you leave out keep their value. `steps` replaces all\nsteps. Alerts already escalating keep the steps they started with.", "properties": { "name": { "type": "string", "description": "Name, up to 255 characters", "examples": [ "On-call engineers" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "What the path is for, up to 1000 characters", "maxLength": 1000 }, "enabled": { "type": "boolean", "description": "Whether alerts follow the path" }, "is_default": { "type": "boolean", "description": "Make it the team's default path (the current default stops being one), or not" }, "working_hours": { "anyOf": [ { "description": "Working hours; `null` for Monday to Friday 09:00\u201317:00 in the team's time zone", "$ref": "#/components/schemas/WorkingHoursInput" }, { "type": "null" } ] }, "steps": { "type": "array", "description": "All steps, in order, up to 99 in total; replaces the current steps", "items": { "$ref": "#/components/schemas/EscalationStepInput" } } }, "title": "UpdateEscalationPath" }, "UpdateHost": { "type": "object", "description": "Changes to a host; fields you leave out keep their value.", "properties": { "label": { "type": "string", "description": "Name shown in the dashboard and alerts", "examples": [ "web-1" ], "maxLength": 255 }, "no_data_alert_minutes": { "type": [ "integer", "null" ], "description": "Minutes without data, 2 to 1440, before the \"no data received\" alert fires; `null` turns it off. A firing alert ends at once when the host is within the new window", "examples": [ 10 ], "minimum": 2, "maximum": 1440 }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Project of the host; `null` for none" }, "escalation_path_ids": { "type": "array", "description": "Escalation paths for the host's alerts; replaces the current ones. `[]` follows the project's paths, else the team's default path", "items": { "type": "string", "format": "uuid" } } }, "title": "UpdateHost" }, "UpdateIncident": { "type": "object", "description": "Changes to an incident; fields you leave out keep their value. To post what's known, use\n`createIncidentUpdate`; to close it, `resolveIncident`.", "properties": { "title": { "type": "string", "description": "What's going on", "examples": [ "Checkout fails for some customers" ], "maxLength": 255 }, "summary": { "type": [ "string", "null" ], "description": "More about it, in Markdown" }, "severity": { "description": "How bad it is. Changing it is announced in the incident's Slack channel\n\n| |\n|---|\n| `critical`
Customers are affected right now. |\n| `high`
Serious, needs attention soon. |\n| `medium`
Should be looked at. |\n| `low`
Informational. |", "$ref": "#/components/schemas/Severity" }, "status": { "description": "Where it stands, without posting an update\n\n| |\n|---|\n| `investigating`
Declared; the cause isn't known yet. |\n| `identified`
Acknowledged: the cause is known and someone works on it. |\n| `monitoring`
A fix is out; watching whether it holds. |\n| `resolved`
Over. |", "$ref": "#/components/schemas/IncidentStatus" } }, "title": "UpdateIncident" }, "UpdateMember": { "type": "object", "description": "A member's new role.", "properties": { "role": { "description": "The role; `owner` can't be given (`422`)\n\n| |\n|---|\n| `owner`
Everything, including billing and deleting the team. One per team. |\n| `manager`
Everything but billing and deleting the team. |\n| `admin`
Configure monitoring, alerting, incidents and status pages; can't manage members or API tokens. |\n| `member`
Read everything; manage monitors and incidents, acknowledge alerts. |\n| `billing`
Billing and support only. |", "$ref": "#/components/schemas/TeamRole" } }, "required": [ "role" ], "title": "UpdateMember" }, "UpdateMonitor": { "type": "object", "description": "Changes to a monitor; fields you leave out keep their value. To pause or resume it, use\n`pauseMonitor` and `resumeMonitor`.", "properties": { "label": { "type": "string", "description": "Name shown in the dashboard, alerts and status pages", "examples": [ "Website" ], "maxLength": 255 }, "protocol": { "description": "What to check. Changing it requires `uri` in the new protocol's format\n\n| |\n|---|\n| `https`
An HTTPS request to the URL in `uri`, with a certificate check. |\n| `http`
An HTTP request to the URL in `uri`. |\n| `icmp`
A ping (ICMP echo) to the host in `uri`. |\n| `tcp`
A TCP connect to `host:port`, optionally with a TLS handshake and a banner keyword. |\n| `dns`
A DNS query for a record of the name in `uri`, optionally compared with expected values. |\n| `smtp`
An SMTP greeting from `host:port` (port optional), with STARTTLS by default. |\n| `imap`
An IMAP greeting from `host:port` (port optional), over TLS by default. |\n| `pop3`
A POP3 greeting from `host:port` (port optional), over TLS by default. |", "$ref": "#/components/schemas/MonitorProtocol" }, "uri": { "type": "string", "description": "The target, in the format of the (new) protocol; see `createMonitor`. For `http` and `https` the scheme is optional and must match the protocol; it is stored without the scheme", "examples": [ "https://example.com/health" ], "maxLength": 2048 }, "interval": { "description": "Seconds between checks. Plans set the shortest allowed interval", "$ref": "#/components/schemas/MonitorInterval" }, "primary_location": { "description": "Region the checks run from\n\n| |\n|---|\n| `eu`
Europe. |\n| `us`
North America. |\n| `as`
Asia. |\n| `oc`
Oceania. |", "$ref": "#/components/schemas/MonitorLocation" }, "timeout": { "type": "integer", "description": "Seconds before a check times out, 1 to 60", "minimum": 1, "maximum": 60 }, "max_redirects": { "type": [ "integer", "null" ], "description": "HTTP: redirects to follow, 0 to 10; `null` follows up to 10", "minimum": 0, "maximum": 10 }, "headers": { "type": "array", "description": "HTTP: up to 25 headers to send; replaces the current headers", "items": { "$ref": "#/components/schemas/MonitorHeader" } }, "advanced_settings": { "description": "Protocol-specific settings; settings you leave out keep their value", "$ref": "#/components/schemas/MonitorAdvancedSettingsInput" }, "allow_insecure_requests": { "type": "boolean", "description": "HTTPS: accept invalid certificates for the check itself" }, "expected_http_status_code": { "type": [ "string", "null" ], "description": "HTTP: status codes that count as up; `null` accepts 2xx and 3xx", "minLength": 1, "maxLength": 200 }, "certificate_check_enabled": { "type": "boolean", "description": "Check the TLS certificate for validity and expiry" }, "certificate_expiry_threshold_days": { "type": "integer", "description": "Days before the certificate expires that the \"expires soon\" alert fires, 1 to 90", "minimum": 1, "maximum": 90 }, "performance_check_enabled": { "type": "boolean", "description": "Raise alerts for slow responses" }, "performance_hard_threshold": { "type": [ "integer", "null" ], "description": "Milliseconds, 1 to 30000: a response slower than this raises an alert", "minimum": 1, "maximum": 30000 }, "performance_deviation_percentage": { "type": [ "integer", "null" ], "description": "Percent, 1 to 500: alert when recent response times are this much above the earlier ones", "minimum": 1, "maximum": 500 }, "performance_deviation_timeframe": { "type": [ "integer", "null" ], "description": "Minutes of recent checks to compare: 15 to 120 in steps of 15", "minimum": 15, "maximum": 120 }, "performance_deviation_before_timeframe": { "type": [ "integer", "null" ], "description": "Minutes before those to compare with: 60 to 1440 in whole hours", "minimum": 60, "maximum": 1440 }, "regional_performance_enabled": { "type": "boolean", "description": "Also measure response time from the regions other than `primary_location`, every minute (or at the interval, when longer). Shown with the monitor's performance; not used for uptime or alerts. Team plan and up" }, "project_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Project of the monitor; `null` for none" }, "escalation_path_ids": { "type": "array", "description": "Escalation paths for the monitor's alerts; replaces the current ones. `[]` follows the project's paths, else the team's default path", "items": { "type": "string", "format": "uuid" } } }, "title": "UpdateMonitor" }, "UpdateOnCallRotation": { "type": "object", "description": "Changes to a rotation layer; fields you leave out keep their value.", "properties": { "name": { "type": "string", "description": "Name", "examples": [ "Weekly primary" ], "maxLength": 255 }, "position": { "type": "integer", "description": "Move the layer to this position, 0 for the top; the others shift", "minimum": 0, "maximum": 100 }, "shift_unit": { "description": "The unit of the shift length\n\n| |\n|---|\n| `hours`
Absolute hours: shifts keep their length across DST changes. |\n| `days`
Calendar days in the schedule's time zone: the handoff stays at the same wall-clock time. |\n| `weeks`
Calendar weeks in the schedule's time zone. |", "$ref": "#/components/schemas/OnCallShiftUnit" }, "shift_length": { "type": "integer", "description": "Shift length in `shift_unit`s", "minimum": 1, "maximum": 720 }, "start_date": { "type": "string", "format": "date", "description": "The first handoff's date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "handoff_time": { "type": "string", "description": "Handoff time as `HH:MM`", "examples": [ "09:00" ] }, "restrictions": { "anyOf": [ { "description": "The weekly window; `null` for round the clock", "$ref": "#/components/schemas/OnCallRestrictionsInput" }, { "type": "null" } ] }, "participant_ids": { "type": "array", "description": "Members taking turns, in order; replaces the current ones", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "uniqueItems": true } }, "title": "UpdateOnCallRotation" }, "UpdateOnCallSchedule": { "type": "object", "description": "Changes to an on-call schedule; fields you leave out keep their value.", "properties": { "name": { "type": "string", "description": "Name", "examples": [ "Primary" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "What the schedule covers", "maxLength": 1000 }, "timezone": { "type": "string", "description": "IANA time zone. Rotations keep their dates and wall-clock handoff times in the new zone", "examples": [ "Europe/Amsterdam" ] } }, "title": "UpdateOnCallSchedule" }, "UpdateProject": { "type": "object", "description": "Changes to a project; fields left out keep their value.", "properties": { "name": { "type": "string", "description": "Project name", "examples": [ "Production" ], "maxLength": 255 }, "escalation_path_ids": { "type": "array", "description": "Escalation paths for alerts of the project's monitors and hosts; replaces the current list. Send `[]` for none", "items": { "type": "string", "format": "uuid" }, "uniqueItems": true } }, "title": "UpdateProject" }, "UpdateScheduledMaintenance": { "type": "object", "description": "Changes to a maintenance; fields left out keep their value.", "properties": { "title": { "type": "string", "description": "Title shown on the page, up to 255 characters", "examples": [ "Database upgrade" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "What happens and what visitors notice, in Markdown; `null` for none", "examples": [ "The API is read-only for about ten minutes." ] }, "status": { "description": "Move it along by hand: `in_progress` starts it, `completed` completes it (stamping `completed_at`), `scheduled` puts it back\n\n| |\n|---|\n| `scheduled`
Announced, not started yet. |\n| `in_progress`
Going on: its components show as under maintenance. |\n| `completed`
Over. |", "$ref": "#/components/schemas/ScheduledMaintenanceStatus" }, "automatic": { "type": "boolean", "description": "`true`: starts and completes on schedule. `false`: only changes when you set `status`" }, "scheduled_at": { "type": "string", "format": "date-time", "description": "Planned start" }, "scheduled_until": { "type": [ "string", "null" ], "format": "date-time", "description": "Planned end; `null` for none" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it completed. Setting it completes the maintenance" }, "affected_components": { "type": "array", "description": "Components it affects; replaces the current list. Components of the status page only", "items": { "$ref": "#/components/schemas/StatusPageAffectedComponentInput" } }, "notify_subscribers": { "type": "boolean", "description": "Email confirmed subscribers when this starts or completes the maintenance (default `true`)" } }, "title": "UpdateScheduledMaintenance" }, "UpdateStatusPage": { "type": "object", "description": "Changes to a status page; settings left out keep their value.", "properties": { "name": { "type": "string", "description": "Name, shown as the page title", "examples": [ "Acme status" ], "maxLength": 255 }, "slug": { "type": "string", "description": "The page's subdomain under spectate.page: lowercase letters, digits and dashes. The old address stops working", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$", "examples": [ "acme" ], "maxLength": 63 }, "visibility": { "description": "Who can open the page. Private pages are part of the Team plan and up (`403` `PLAN_FEATURE_UNAVAILABLE`)\n\n| |\n|---|\n| `public`
Anyone. |\n| `private`
Visitors with the access link, or the password when the page has one. Part of the Team plan and up. |", "$ref": "#/components/schemas/StatusPageVisibility" }, "custom_domain": { "type": [ "string", "null" ], "description": "Your own domain for the page, such as `status.acme.com`; `null` for none. Part of paid plans (`403` `PLAN_FEATURE_UNAVAILABLE` otherwise). A new domain needs to be verified again: see `custom_domain_verification` and `verifyStatusPageCustomDomain`", "examples": [ "status.acme.com" ], "maxLength": 253 }, "password_protected": { "type": "boolean", "description": "Let visitors of a private page also get in with a password. Part of paid plans (`403` `PLAN_FEATURE_UNAVAILABLE` otherwise); turning it on needs a `password` unless the page has one" }, "password": { "type": [ "string", "null" ], "description": "The password, 8 to 255 characters. Write-only; leave out or send `null` to keep the current one", "examples": [ "correct-horse-battery" ], "minLength": 8, "maxLength": 255 }, "language": { "description": "Language of the public page and of subscriber emails\n\n| |\n|---|\n| `en`
English. |\n| `nl`
Dutch. |\n| `de`
German. |\n| `fr`
French. |\n| `es`
Spanish. |\n| `it`
Italian. |", "$ref": "#/components/schemas/StatusPageLanguage" }, "match_browser_language": { "type": "boolean", "description": "Give visitors their browser's language when it is supported" }, "theme": { "description": "How the page looks and what it shows", "$ref": "#/components/schemas/StatusPageThemeInput" }, "collapsed_groups": { "type": "array", "description": "Component groups that start collapsed; replaces the current list", "items": { "type": "string", "maxLength": 255 }, "maxItems": 100, "uniqueItems": true }, "automation_enabled": { "type": "boolean", "description": "Monitor automation: when a monitor linked to a component goes down, open an incident \"{component} is down\" (major outage), and resolve it when the monitor recovers" }, "automation_down_message": { "type": [ "string", "null" ], "description": "Posted when a linked monitor goes down, up to 5000 characters; `{component}` and `{status_page}` are filled in. `null` for a default message", "examples": [ "We're looking into problems with {component}." ], "maxLength": 5000 }, "automation_recovered_message": { "type": [ "string", "null" ], "description": "Posted when the monitor recovers, up to 5000 characters; `null` for a default message", "examples": [ "{component} is working again." ], "maxLength": 5000 }, "issue_reports_enabled": { "type": "boolean", "description": "Let visitors report problems from the page" }, "issue_reports_show_on_page": { "type": "boolean", "description": "While reports are above the threshold, say on the page that users are reporting issues" }, "issue_reports_alerts_enabled": { "type": "boolean", "description": "Fire an alert when reports reach the threshold" }, "issue_reports_threshold": { "type": "integer", "description": "Reports within `issue_reports_window_minutes` that count as above the threshold, 1 to 1000", "minimum": 1, "maximum": 1000 }, "issue_reports_window_minutes": { "type": "integer", "description": "The window for the threshold, in minutes, 1 to 1440", "minimum": 1, "maximum": 1440 }, "traffic_alerts_enabled": { "type": "boolean", "description": "Alert when views reach `traffic_alert_multiplier` times the usual views for the time of day" }, "traffic_alert_multiplier": { "type": "integer", "description": "How many times the usual views alert, 2 to 100", "minimum": 2, "maximum": 100 }, "traffic_alert_min_views": { "type": "integer", "description": "Fewer views than this in 15 minutes never alert, 10 to 1000000", "minimum": 10, "maximum": 1000000 }, "escalation_path_ids": { "type": "array", "description": "Escalation paths for the page's alerts (issue reports and traffic spikes); replaces the current ones. Empty for the team's default path", "items": { "type": "string", "format": "uuid" } } }, "title": "UpdateStatusPage" }, "UpdateStatusPageComponent": { "type": "object", "description": "Changes to a component; fields left out keep their value. Its status follows incidents and maintenance and can't be set.", "properties": { "name": { "type": "string", "description": "Name shown on the page", "examples": [ "API" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Text shown with the name; `null` for none", "examples": [ "Our public REST API." ] }, "group": { "type": [ "string", "null" ], "description": "Group to show the component in; `null` for the page's default group", "examples": [ "Backend" ], "maxLength": 255 }, "position": { "type": "integer", "description": "Order within the group, lowest first, from 0. New components go last when left out", "minimum": 0 }, "monitor_id": { "type": [ "string", "null" ], "format": "uuid", "description": "A monitor of the team whose uptime history and response times the component shows, and whose downtime opens an incident when monitor automation is on; `null` for none" }, "show_latency_chart": { "type": "boolean", "description": "Show the monitor's response time chart under the component" } }, "title": "UpdateStatusPageComponent" }, "UpdateStatusPageImpactPeriod": { "type": "object", "description": "Changes to an impact period; fields left out keep their value.", "properties": { "component_id": { "type": "string", "format": "uuid", "description": "A component of the status page" }, "impact": { "description": "How badly\n\n| |\n|---|\n| `degraded_performance`
Slower or less reliable than usual. |\n| `partial_outage`
Down for some visitors or some functions. |\n| `major_outage`
Down. |", "$ref": "#/components/schemas/ComponentImpact" }, "started_at": { "type": "string", "format": "date-time", "description": "When it started, now or in the past" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it ended, after `started_at` and not in the future; `null` reopens the period" } }, "title": "UpdateStatusPageImpactPeriod" }, "UpdateStatusPageIncident": { "type": "object", "description": "Changes to a public incident without posting an update; fields left out keep their value.", "properties": { "title": { "type": "string", "description": "Title shown on the page", "examples": [ "Elevated API error rates" ], "maxLength": 255 }, "status": { "description": "Where it stands. Changing it posts no update; `resolved` closes every open impact period now\n\n| |\n|---|\n| `investigating`
Declared; the cause isn't known yet. |\n| `identified`
Acknowledged: the cause is known and someone works on it. |\n| `monitoring`
A fix is out; watching whether it holds. |\n| `resolved`
Over. |", "$ref": "#/components/schemas/IncidentStatus" }, "impact": { "description": "The incident's own impact, used while it affects no components\n\n| |\n|---|\n| `none`
No impact (for a component: not affected). |\n| `degraded_performance`
Slower or less reliable than usual. |\n| `partial_outage`
Down for some visitors or some functions. |\n| `major_outage`
Down. |", "$ref": "#/components/schemas/ImpactLevel" }, "affected_components": { "type": "array", "description": "The components it affects as of now, with their impact; components left out are no longer affected. Leave out to keep the impacts as they are; send `[]` for none. Components of the status page only", "items": { "$ref": "#/components/schemas/StatusPageAffectedComponentInput" } }, "notify_subscribers": { "type": "boolean", "description": "Email confirmed subscribers when this resolves the incident (default `true`). `false` changes the page without emails" } }, "title": "UpdateStatusPageIncident" }, "UpdateStatusPageIncidentUpdate": { "type": "object", "description": "Changes to an update of a public incident; fields left out keep their value.", "properties": { "status": { "description": "The incident's status with this update. The incident follows its latest update\n\n| |\n|---|\n| `investigating`
Declared; the cause isn't known yet. |\n| `identified`
Acknowledged: the cause is known and someone works on it. |\n| `monitoring`
A fix is out; watching whether it holds. |\n| `resolved`
Over. |", "$ref": "#/components/schemas/IncidentStatus" }, "body": { "type": "string", "description": "The message, in Markdown", "examples": [ "We found the cause and are rolling out a fix." ] }, "published_at": { "type": "string", "format": "date-time", "description": "When it happened, now or in the past. Impact periods that started or ended at the old time move with it" } }, "title": "UpdateStatusPageIncidentUpdate" }, "UpdateTeam": { "type": "object", "description": "Changes to the team; fields left out keep their value.", "properties": { "name": { "type": "string", "description": "Name, up to 255 characters", "examples": [ "Acme" ], "maxLength": 255 }, "email": { "type": [ "string", "null" ], "format": "email", "description": "The team's billing email: Spectate gives it to Vatly, which sends the invoices and receipts, at the team's first checkout (a plan or credits). `null` to use the address of the member who starts that checkout", "examples": [ "ops@acme.com" ], "maxLength": 255 }, "timezone": { "type": "string", "description": "The team's time zone, as an IANA name; escalation path working hours without a time zone of their own use it", "examples": [ "Europe/Amsterdam" ] } }, "title": "UpdateTeam" }, "UptimeStatus": { "type": "string", "description": "Whether a monitor's target answers, from its latest checks.\n| |\n|---|\n| `pending`
Not checked yet. |\n| `up`
The latest check succeeded. |\n| `down`
Checks fail: a failed check, repeated from the same region about 5 seconds later, failed again. |", "enum": [ "pending", "up", "down" ], "title": "UptimeStatus" }, "Usage": { "type": "object", "description": "How much of the plan's limits the team uses.", "properties": { "monitors_and_hosts": { "description": "Monitors and hosts together; on paid plans the limit is the quantity paid for", "$ref": "#/components/schemas/UsageLimit" }, "domains": { "description": "Monitored domains", "$ref": "#/components/schemas/UsageLimit" }, "projects": { "description": "Projects", "$ref": "#/components/schemas/UsageLimit" }, "status_pages": { "description": "Status pages", "$ref": "#/components/schemas/UsageLimit" }, "status_page_subscribers": { "description": "Confirmed subscribers of all status pages together; at the limit the pages take no new subscribers", "$ref": "#/components/schemas/UsageLimit" }, "escalation_paths": { "description": "Escalation paths, including the team default path", "$ref": "#/components/schemas/UsageLimit" }, "members": { "description": "Members plus pending invites", "$ref": "#/components/schemas/UsageLimit" } }, "required": [ "monitors_and_hosts", "domains", "projects", "status_pages", "status_page_subscribers", "escalation_paths", "members" ], "title": "Usage" }, "UsageLimit": { "type": "object", "description": "How much of a plan limit is used.", "properties": { "used": { "type": "integer", "description": "In use now" }, "limit": { "type": [ "integer", "null" ], "description": "The limit; `null` for unlimited, `0` when the plan doesn't include it. At the limit, creating more through the API answers `403` `PLAN_LIMIT_REACHED`" } }, "required": [ "used", "limit" ], "title": "UsageLimit" }, "ValidationError": { "type": "object", "description": "The request body or query failed validation.", "properties": { "error": { "type": "object", "description": "What went wrong.", "properties": { "code": { "type": "string", "description": "Always `VALIDATION_FAILED`.", "enum": [ "VALIDATION_FAILED" ] }, "message": { "type": "string", "description": "The first validation message, followed by how many more there are.", "examples": [ "The name field is required. (and 1 more error)" ] }, "details": { "type": "object", "description": "The fields that failed validation.", "properties": { "errors": { "type": "object", "description": "Messages per invalid field. Keys are field paths in dot notation, for example `headers.0.key`.", "examples": [ { "name": [ "The name field is required." ] } ], "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "errors" ] } }, "required": [ "code", "message", "details" ] } }, "required": [ "error" ], "title": "ValidationError" }, "WorkingHours": { "type": "object", "description": "Weekly working hours, for branch conditions and \"until working hours\" waits.", "properties": { "timezone": { "type": "string", "description": "IANA time zone the hours are in", "examples": [ "Europe/Amsterdam" ] }, "days": { "type": "array", "description": "ISO weekdays, 1 (Monday) to 7 (Sunday)", "items": { "type": "integer" } }, "start_time": { "type": "string", "description": "When working hours begin, as `HH:MM`", "examples": [ "09:00" ] }, "end_time": { "type": "string", "description": "When they end, as `HH:MM`; before `start_time` runs past midnight", "examples": [ "17:00" ] }, "description": { "type": "string", "description": "The hours in words", "examples": [ "Mon\u2013Fri 09:00\u201317:00 (Europe/Amsterdam)" ] } }, "required": [ "timezone", "days", "start_time", "end_time", "description" ], "title": "WorkingHours" }, "WorkingHoursInput": { "type": "object", "description": "Weekly working hours of a path.", "properties": { "timezone": { "type": "string", "description": "IANA time zone the hours are in", "examples": [ "Europe/Amsterdam" ] }, "days": { "type": "array", "description": "ISO weekdays, 1 (Monday) to 7 (Sunday), at least one", "items": { "type": "integer", "minimum": 1, "maximum": 7 }, "minItems": 1, "maxItems": 7, "uniqueItems": true }, "start_time": { "type": "string", "description": "When working hours begin, as `HH:MM`", "examples": [ "09:00" ] }, "end_time": { "type": "string", "description": "When they end, as `HH:MM`; before `start_time` runs past midnight", "examples": [ "17:00" ] } }, "required": [ "timezone", "days", "start_time", "end_time" ], "title": "WorkingHoursInput" } } } }