API and tokens

Updated 2026-10-22 · Pharos 1.0.1

Create tokens under Integrations & API → API tokens, or from the shell. A token is 40 characters and only its SHA-256 hash is stored, so it is shown exactly once.

php artisan pharos:token "n8n" [email protected] --page=1 --scope=write

The command needs an owner (--user, the email of an account with access to the page) and a page (--page, the id of the status page). The first page is normally 1. For every other page it is the number in the admin address, as in /admin/pages/2/overview. Without --scope it makes a Write token.

A token belongs to one status page and one owner, and it has one of two kinds of access:

Access	What it may do
Read	See components and incidents, including the ones that are not public. It cannot change anything. In the admin, Read is the choice that is already selected.
Write	Also change component status, post incidents and use the other writing endpoints. It only works while its owner may edit the page: lower or remove the owner's role and the token loses its rights at once.

Endpoints that take a token accept either header; the second exists so Cachet scripts need no editing:

Authorization: Bearer <token>
X-Cachet-Token: <token>

The addresses under /api/v1/ serve the first status page. Every other page has the same endpoints under /api/v1/pages/{slug}/, with a token of that page. The API answers on the main address of the installation only, not on a custom domain of a page.

Reading, without a token

curl -s https://status.example.com/api/v1/components
curl -s https://status.example.com/api/v1/incidents

/components returns the Cachet envelope with the same field names and status integers. /incidents returns the 50 most recent public incidents with their updates and components.

Setting one component

curl -sX PUT https://status.example.com/api/v1/components/1 \
  -H "Authorization: Bearer $PHAROS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": 4}'

This does not open an incident. If a built-in check also watches that component, the next check run overwrites whatever you set, so pick one owner per component.

Opening an incident across several components

curl -sX POST https://status.example.com/api/v1/incidents \
  -H "Authorization: Bearer $PHAROS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template":     "server-unreachable",
    "vars":         { "server": "web-06.example.net", "started_at": "16:50" },
    "status":       "investigating",
    "impact":       "major",
    "components":   { "7": "major_outage", "8": "degraded" },
    "auto_resolve": true
  }'

Status is a name, not an integer: investigating, identified, watching or resolved. Component keys may be an id or a name. An unrecognised component status silently becomes operational, so check your spelling.

Adding an update

curl -sX POST https://status.example.com/api/v1/incidents/12/updates \
  -H "Authorization: Bearer $PHAROS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved", "message": "Back up at 17:22."}'

Services, maintenance and subscribers

1.0 adds endpoints for the things you could only manage in the admin. Paths are relative to /api/v1, or to /api/v1/pages/{slug} for another page.

Endpoint	What it does	Token
`GET /ping`	Answers `{"data":"Pong!"}`, as Cachet did.	None
`GET /groups`, `GET /groups/{id}`	Lists the services, or returns one.	Read
`POST /groups`, `PUT` and `DELETE /groups/{id}`	Creates, changes or deletes a service. Fields: `name`, `visible`, `collapsed`, `position`.	Write
`POST /components`	Creates a component. Fields: `name`, and optionally `description`, `status` (1 to 5), `group_id`, `enabled`, `show_uptime`, `position`.	Write
`DELETE /components/{id}`	Deletes a component. An incident that its check opened is closed with a reason.	Write
`DELETE /incidents/{id}`	Deletes an incident.	Write
`GET /maintenance`, `GET /maintenance/{id}`	Lists the 100 most recent maintenance windows, or returns one.	Read
`POST /maintenance`, `PUT` and `DELETE /maintenance/{id}`	Schedules, changes or removes a window. Fields: `title`, `message`, `starts_at`, `ends_at`, `announce_minutes`, `components` (a list of ids).	Write
`GET /subscribers`, `GET /subscribers/{id}`	Lists subscribers, 50 per page (`per_page` up to 100, `page`), or returns one.	Read, owner administers the page
`POST /subscribers`, `PUT` and `DELETE /subscribers/{id}`	Adds a pending address, changes the chosen services (`all_services`, `component_ids`) or deletes the address.	Write, owner administers the page
`GET /metrics`	Status and uptime for Prometheus. See Prometheus metrics.	Read

curl -sX POST https://status.example.com/api/v1/maintenance \
  -H "Authorization: Bearer $PHAROS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title":            "Storage upgrade on web-01",
    "starts_at":        "2026-10-20T20:00:00+02:00",
    "ends_at":          "2026-10-20T22:00:00+02:00",
    "announce_minutes": 1440,
    "components":       [7, 8]
  }'

Times need the full form with seconds and an offset, as in the example. The end must be after the start and in the future.
announce_minutes is one of 0 (do not announce), 60, 360, 1440, 2880, 4320 or 10080.
PUT only changes a window that has not started yet. Deleting a running window first puts its components back.
An address added through POST /subscribers is pending and gets no mail from the call itself. The API never returns the private link token of a subscriber or the IP address they signed up from.
A component made with POST /components is marked as set from outside, so its uptime is counted from the status you report.
A request body may be 256 KiB at most on these endpoints, and they are limited to 60 requests per minute per calling address.
With a valid token these endpoints also work for a page that is not published yet. An archived page is not available, and /ping only answers for a published page.