# Status API

Version 1.0 · OpenAPI 3.1.0

The Status API: status pages, their components, incidents, scheduled maintenance,
subscribers, custom domains, branding and visitor analytics. It is the API the
EvoHub console itself uses.

**Authentication.** Send an API key as `Authorization: Bearer evohub_…` or
`X-API-Key: evohub_…`. A key works in one organization. See *API keys and
scopes* and *Errors* in these docs. The public page reads (tag *Public pages*)
need no key at all.

**Permissions.** Each operation names the permission it needs
(`x-evohub-permission`); an API key needs it among its scopes. A key is always
held to its scopes, even one made by an administrator. A refusal is
**403 `FORBIDDEN`**, never 401.

**Teams.** A page belongs to the whole organization (`team_id` is `""`) or to
one team. A key sees the organization-wide pages; an organization key scoped
to a team also sees that team's. A page the caller cannot
see, and everything under it (components, incidents, maintenance, subscribers,
domain, analytics), answers **404 `NOT_FOUND`**, exactly like one that does not
exist.

**Ids.** Pages, components, incidents, maintenance windows, their updates and
subscribers have UUID ids. A path id that is not a UUID answers 404
`NOT_FOUND` before anything is read.

**Responses.** Success is `{"data": …, "success": true}`. Errors are
`{"error": {"code", "message", "request_id"}}`; this service's codes are
`VALIDATION_ERROR` (400, the message names the field), `INVALID_BODY` (400, not JSON
or an unknown field: bodies are decoded strictly), `NOT_FOUND`, and
`INTERNAL_ERROR` (500). The analytics endpoints answer a bad range with
`VALIDATION_FAILED` and `details`. Times are RFC 3339 in UTC.

**Incidents and maintenance are On-Call's.** On the console, incidents and
maintenance windows are published and run from On-Call, which calls these same
endpoints. Through this API you can run them on the page directly; set
`managed_in: status_page` so the console shows them as the page's own.

**Every write reaches the public page.** A successful write under a page drops
the page's cached copy at the edge, so visitors see it on their next poll.

**Not here.** The subscribe form, its confirm and unsubscribe links, and the
visitor-analytics beacon are served to visitors by the status page itself
(`x-route-check.not-public`).

## Servers

- `https://evohub.io`

## Authentication

- `bearerAuth`: HTTP Bearer — An EvoHub API key (`evohub_…`) as a bearer token.
- `apiKeyHeader`: API key in the header `X-API-Key` — An EvoHub API key (`evohub_…`).

## Pages

Status pages and their settings.

- [GET /api/v1/pages](https://docs-dev.evohub.io/status/list-pages.md): List pages
- [POST /api/v1/pages](https://docs-dev.evohub.io/status/create-page.md): Create a page
- [GET /api/v1/pages/{pageID}](https://docs-dev.evohub.io/status/get-page.md): Get a page
- [PUT /api/v1/pages/{pageID}](https://docs-dev.evohub.io/status/update-page.md): Update a page
- [DELETE /api/v1/pages/{pageID}](https://docs-dev.evohub.io/status/delete-page.md): Delete a page
- [PATCH /api/v1/pages/{pageID}/content-settings](https://docs-dev.evohub.io/status/update-page-content.md): Update content and SEO settings

## Page appearance

Theme, header links, layout of groups, logos and favicon.

- [PATCH /api/v1/pages/{pageID}/theme](https://docs-dev.evohub.io/status/update-page-theme.md): Update the theme
- [PATCH /api/v1/pages/{pageID}/links](https://docs-dev.evohub.io/status/update-page-links.md): Update the header
- [PATCH /api/v1/pages/{pageID}/product-groups](https://docs-dev.evohub.io/status/update-page-layout.md): Set how groups are laid out
- [POST /api/v1/pages/{pageID}/logo](https://docs-dev.evohub.io/status/upload-page-logo.md): Upload the logo
- [DELETE /api/v1/pages/{pageID}/logo](https://docs-dev.evohub.io/status/remove-page-logo.md): Remove the logo
- [POST /api/v1/pages/{pageID}/favicon](https://docs-dev.evohub.io/status/upload-page-favicon.md): Upload the favicon
- [DELETE /api/v1/pages/{pageID}/favicon](https://docs-dev.evohub.io/status/remove-page-favicon.md): Remove the favicon
- [GET /api/v1/pages/{pageID}/groups/logos](https://docs-dev.evohub.io/status/list-group-logos.md): List group logos
- [POST /api/v1/pages/{pageID}/groups/logo](https://docs-dev.evohub.io/status/upload-group-logo.md): Upload a group's logo
- [DELETE /api/v1/pages/{pageID}/groups/logo](https://docs-dev.evohub.io/status/remove-group-logo.md): Remove a group's logo

## Components

The services a page shows, and their status.

- [GET /api/v1/pages/{pageID}/components](https://docs-dev.evohub.io/status/list-components.md): List a page's components
- [POST /api/v1/pages/{pageID}/components](https://docs-dev.evohub.io/status/create-component.md): Add a component
- [PUT /api/v1/pages/{pageID}/components/order](https://docs-dev.evohub.io/status/reorder-components.md): Reorder components
- [PUT /api/v1/pages/{pageID}/groups/rename](https://docs-dev.evohub.io/status/rename-group.md): Rename a group
- [GET /api/v1/components/{componentID}](https://docs-dev.evohub.io/status/get-component.md): Get a component
- [PUT /api/v1/components/{componentID}](https://docs-dev.evohub.io/status/update-component.md): Update a component
- [DELETE /api/v1/components/{componentID}](https://docs-dev.evohub.io/status/delete-component.md): Delete a component
- [PATCH /api/v1/components/{componentID}/status](https://docs-dev.evohub.io/status/set-component-status.md): Set a component's status

## Incidents

Incidents on a page and their timeline.

- [GET /api/v1/pages/{pageID}/incidents](https://docs-dev.evohub.io/status/list-incidents.md): List a page's incidents
- [POST /api/v1/pages/{pageID}/incidents](https://docs-dev.evohub.io/status/create-incident.md): Create an incident
- [DELETE /api/v1/pages/{pageID}/incidents/{id}](https://docs-dev.evohub.io/status/delete-incident.md): Delete an incident
- [PATCH /api/v1/pages/{pageID}/incidents/{id}](https://docs-dev.evohub.io/status/update-incident.md): Edit an incident
- [POST /api/v1/pages/{pageID}/incidents/{id}/updates](https://docs-dev.evohub.io/status/add-incident-update.md): Post an update
- [DELETE /api/v1/pages/{pageID}/incidents/{id}/updates/{updateID}](https://docs-dev.evohub.io/status/delete-incident-update.md): Delete an update
- [PATCH /api/v1/pages/{pageID}/incidents/{id}/updates/{updateID}](https://docs-dev.evohub.io/status/edit-incident-update.md): Edit an update's text
- [PUT /api/v1/pages/{pageID}/incidents/{id}/postmortem](https://docs-dev.evohub.io/status/set-incident-postmortem.md): Save the postmortem

## Maintenance

Scheduled maintenance on a page and its timeline.

- [GET /api/v1/pages/{pageID}/maintenances](https://docs-dev.evohub.io/status/list-maintenances.md): List a page's maintenance
- [POST /api/v1/pages/{pageID}/maintenances](https://docs-dev.evohub.io/status/create-maintenance.md): Schedule maintenance
- [DELETE /api/v1/pages/{pageID}/maintenances/{id}](https://docs-dev.evohub.io/status/delete-maintenance.md): Delete maintenance
- [PATCH /api/v1/pages/{pageID}/maintenances/{id}](https://docs-dev.evohub.io/status/update-maintenance.md): Edit maintenance
- [POST /api/v1/pages/{pageID}/maintenances/{id}/updates](https://docs-dev.evohub.io/status/add-maintenance-update.md): Post a maintenance update
- [DELETE /api/v1/pages/{pageID}/maintenances/{id}/updates/{updateID}](https://docs-dev.evohub.io/status/delete-maintenance-update.md): Delete a maintenance update
- [PATCH /api/v1/pages/{pageID}/maintenances/{id}/updates/{updateID}](https://docs-dev.evohub.io/status/edit-maintenance-update.md): Edit a maintenance update's text

## Subscribers

People who follow a page by email.

- [GET /api/v1/pages/{pageID}/subscribers](https://docs-dev.evohub.io/status/list-subscribers.md): List subscribers
- [DELETE /api/v1/pages/{pageID}/subscribers/{id}](https://docs-dev.evohub.io/status/delete-subscriber.md): Remove a subscriber
- [PATCH /api/v1/pages/{pageID}/subscription-settings](https://docs-dev.evohub.io/status/update-subscription-settings.md): Update subscription settings

## Custom domain

Serve a page on your own subdomain.

- [GET /api/v1/pages/{pageID}/domain](https://docs-dev.evohub.io/status/get-domain.md): Get the custom domain
- [POST /api/v1/pages/{pageID}/domain](https://docs-dev.evohub.io/status/set-domain.md): Set the custom domain
- [DELETE /api/v1/pages/{pageID}/domain](https://docs-dev.evohub.io/status/delete-domain.md): Remove the custom domain

## Analytics

Cookieless visitor analytics, incidents published and subscriber growth.

- [GET /api/v1/pages/{pageID}/analytics](https://docs-dev.evohub.io/status/get-page-analytics.md): Get a page's visitor analytics
- [GET /api/v1/pages/{pageID}/analytics/hourly](https://docs-dev.evohub.io/status/get-page-hourly-views.md): Get a page's views by the hour
- [GET /api/v1/pages/{pageID}/analytics/export.csv](https://docs-dev.evohub.io/status/export-page-analytics.md): Export analytics as CSV
- [PATCH /api/v1/pages/{pageID}/analytics/settings](https://docs-dev.evohub.io/status/update-analytics-settings.md): Update analytics settings
- [GET /api/v1/pages/analytics](https://docs-dev.evohub.io/status/get-status-analytics.md): Get analytics across pages

## Overview

Every page's state in one read.

- [GET /api/v1/pages/summary](https://docs-dev.evohub.io/status/get-pages-summary.md): Summarize every page
- [GET /api/v1/pages/overview](https://docs-dev.evohub.io/status/get-pages-overview.md): Get every page's state

## Audit log

Who changed what in Status.

- [GET /api/v1/status-audit-logs](https://docs-dev.evohub.io/status/list-status-audit-logs.md): List the Status audit log

## Public pages

What visitors of a public page read. No API key.

- [GET /api/v1/public/pages/{pageID}](https://docs-dev.evohub.io/status/get-public-page.md): Read a public page
- [GET /api/v1/public/pages/by-domain/{domain}](https://docs-dev.evohub.io/status/get-public-page-by-domain.md): Read a public page by domain
- [GET /api/v1/public/pages/{pageID}/feed.rss](https://docs-dev.evohub.io/status/get-public-rss-feed.md): RSS feed
- [GET /api/v1/public/pages/by-domain/{domain}/feed.rss](https://docs-dev.evohub.io/status/get-public-rss-feed-by-domain.md): RSS feed by domain
- [GET /api/v1/public/pages/{pageID}/feed.atom](https://docs-dev.evohub.io/status/get-public-atom-feed.md): Atom feed
- [GET /api/v1/public/pages/by-domain/{domain}/feed.atom](https://docs-dev.evohub.io/status/get-public-atom-feed-by-domain.md): Atom feed by domain