cachethq · jbrooksuk · Jul 24, 2026 · Jul 24, 2026
diff --git a/api-reference/filtering.mdx b/api-reference/filtering.mdx
@@ -15,6 +15,28 @@ GET /api/incidents?filter[status]=1
 Each endpoint may support different fields for filtering. Check the documentation for the specific endpoint you are working with.
 </Note>
 
+## Including related resources
+
+Many endpoints can embed related resources in the response using the `include` parameter. Pass a comma-separated list
+of the relationships you want to include:
+
+```http
+GET /api/incidents?include=components,updates
+```
+
+<Note>
+    Each endpoint supports a different set of includes. Check the documentation for the specific endpoint you are
+    working with.
+</Note>
+
+## Filtering by metadata
+
+Resources that support metadata can be filtered by their metadata keys using the `filter[meta][key]` syntax:
+
+```http
+GET /api/incidents?filter[meta][region]=us-east-1
+```
+
 ## Sorting
 
 You can sort the results of an endpoint by passing the `sort` parameter. The `sort` parameter should be a comma-separated list of fields to sort by. You can also specify the sort order by appending `asc` or `desc` to the field name.

diff --git a/docs.json b/docs.json
@@ -46,6 +46,7 @@
                 "group": "Configuration",
                 "pages": [
                   "v3.x/configuration/cachet",
+                  "v3.x/configuration/environment",
                   "v3.x/configuration/customization",
                   "v3.x/configuration/theme",
                   "v3.x/configuration/beacon",
@@ -223,4 +224,4 @@
       "vscode"
     ]
   }
-}
+}
diff --git a/v3.x/configuration/api-keys.mdx b/v3.x/configuration/api-keys.mdx
@@ -33,11 +33,33 @@ To create an API key, follow these steps:
     </Step>
 </Steps>
 
+## Permissions
+
+Each API key is granted a set of abilities. Leaving the permissions empty when creating a key grants full access.
+Otherwise, you can grant the `manage` and/or `delete` ability for each resource type:
+
+| Resource | Abilities |
+| --- | --- |
+| Components | `manage`, `delete` |
+| Component groups | `manage`, `delete` |
+| Incidents | `manage`, `delete` |
+| Incident updates | `manage`, `delete` |
+| Incident templates | `manage`, `delete` |
+| Metrics | `manage`, `delete` |
+| Metric points | `manage`, `delete` |
+| Schedules | `manage`, `delete` |
+| Schedule updates | `manage`, `delete` |
+| Subscribers | `manage`, `delete` |
+
+The `manage` ability allows creating and updating the resource, while `delete` allows deleting it. Read-only endpoints
+are available to any valid API key and, depending on your [API settings](/v3.x/configuration/cachet#api-access), may be
+public.
+
 ## Revoking tokens
 
 If you no longer need an API key, you can revoke it. To revoke an API key, click the "Revoke" button next to the key.
 
 <Warning>
     Revoking an API key is irreversible. Once you revoke a key, you can no longer use it to authenticate requests to
     the Cachet API.
-</Warning>
+</Warning>
diff --git a/v3.x/configuration/beacon.mdx b/v3.x/configuration/beacon.mdx
@@ -9,14 +9,15 @@ This data helps us understand how you use Cachet and how we can improve it.
 
 ## Configuration
 
-By default, Cachet's beacon is turned off. You can opt in by setting the `CACHET_BEACON` environment variable to `true`.
+Cachet's beacon is **enabled by default**. If you'd prefer not to send any usage data, you can opt out by setting the
+`CACHET_BEACON` environment variable to `false`.
 
 ```ini .env
-CACHET_BEACON=true
+CACHET_BEACON=false
 ```
 
 <Tip>
-    If you're limiting outbound requests on your server and you'd like to opt into the beacon, you'll need to allow outbound requests to `https://cachethq.io`.
+    If you're limiting outbound requests on your server and you'd like to keep the beacon enabled, you'll need to allow outbound requests to `https://cachethq.io`.
 </Tip>
 
 ### Configuring the scheduler
@@ -40,4 +41,4 @@ The beacon collects the following data:
 - **Cachet Version**: The version of Cachet you're running.
 - **Docker**: Whether you're running Cachet in a Docker container.
 - **Database**: The type of database you're using.
-- **Usage Data**: How you're using Cachet, such as the number of incidents, components, subscribers, etc.
+- **Usage Data**: How you're using Cachet, such as the number of incidents, components, subscribers, etc.
diff --git a/v3.x/configuration/cachet.mdx b/v3.x/configuration/cachet.mdx
@@ -26,6 +26,14 @@ information about your organization, services, or status page.
 The "Timezone" setting allows you to set the timezone for your status page. Cachet uses it to display the correct time
 for incidents and scheduled maintenance. The status page will always display timestamps in the user's local time.
 
+## Language
+
+Cachet can display your status page in a number of languages. The "Language" selector, along with the
+[Timezone](#timezone) settings, can be found on the "Manage Localization" page under the "Settings" navigation group.
+
+Cachet currently ships with the following locales: Deutsch (DE), Deutsch (AT), Deutsch (CH), English, English (UK),
+Spanish (ES), 한국어, Nederlands, Filipino, Português (BR), 简体中文, and 繁體中文.
+
 ## Incident days
 
 This setting allows you to specify the number of days to display incidents on your status page. Cachet pushes incidents
@@ -90,12 +98,13 @@ We’d really appreciate it if you could leave this enabled to help spread the w
 
 ### Display graphs
 
-Enable the "Display Graphs" setting to display graphs for metrics, such as uptime and response time, on your status
-page.
+Enable the "Display Graphs" setting to display [metric](/v3.x/guide/metrics) graphs, such as uptime and response time,
+on your status page. This setting is enabled by default.
 
-<Warning>
-    Metrics are not fully supported in Cachet v3.x. This setting will have no effect until metrics are implemented.
-</Warning>
+### Recent incidents only
+
+Enable the "Recent Incidents Only" setting to show only recent incidents on your status page. When enabled, you can
+set the number of days to include, and Cachet hides any incidents older than that window.
 
 ### Show timezone
 
@@ -106,6 +115,11 @@ When enabled, the "Show Timezone" setting displays your status page's timezone i
 Enable the "Only Show Disrupted Days" setting to show only the days with incidents on your status page. By default,
 the status page displays all days.
 
+### Dynamic favicon
+
+When the "Dynamic Favicon" setting is enabled, your status page's favicon reflects the current system status, so a
+browser tab shows at a glance whether everything is operational or there's an ongoing issue.
+
 ### Show dashboard link
 
-The "Show Dashboard Link" setting controls the "Dashboard" link in the header of your status page. When enabled, the status page displays a link to the Cachet dashboard.
+The "Show Dashboard Link" setting controls the "Dashboard" link in the header of your status page. When enabled, the status page displays a link to the Cachet dashboard.
diff --git a/v3.x/configuration/environment.mdx b/v3.x/configuration/environment.mdx
@@ -0,0 +1,71 @@
+---
+title: 'Environment variables'
+description: 'Configure Cachet using environment variables.'
+icon: 'sliders'
+---
+
+Cachet reads a number of settings from your environment, defined in your `.env` file (or your server's environment).
+These sit alongside the dashboard [settings](/v3.x/configuration/cachet) and generally control how Cachet is installed
+and served, rather than the content of your status page.
+
+<Note>
+    Every variable has a sensible default, so you only need to set the ones you want to change.
+</Note>
+
+## Application
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `CACHET_PATH` | `/` | The URI path Cachet is served from. |
+| `CACHET_DOMAIN` | _(none)_ | The domain Cachet is served from. Leave unset to serve from the application's default domain. |
+| `CACHET_TITLE` | `"${APP_NAME} - Status"` | The title of your status page. |
+| `CACHET_TRUSTED_PROXIES` | _(empty)_ | Comma-separated list of trusted proxy IPs. See [Theme](/v3.x/configuration/theme) for details. |
+| `CACHET_DOCKER` | `false` | Whether Cachet is running inside a Docker container. Set automatically by the official Docker image. |
+| `CACHET_DEMO_MODE` | `false` | Runs Cachet in [demo](/v3.x/demo) mode, adjusting some defaults for a demo environment. |
+
+## API & MCP
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `CACHET_API_RATE_LIMIT` | `300` | Requests per minute allowed against the [API](/api-reference/rate-limiting). |
+| `CACHET_MCP_RATE_LIMIT` | `300` | Requests per minute allowed against the [MCP server](/v3.x/guide/mcp). |
+
+## Telemetry & performance
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `CACHET_BEACON` | `true` | Whether Cachet sends anonymous [telemetry](/v3.x/configuration/beacon). Set to `false` to opt out. |
+| `CACHET_SETTINGS_CACHE` | `true` | Cache Cachet's settings instead of reading them from the database on every request. |
+
+## Maintenance & retention
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `CACHET_PRUNE_CHECKS_AFTER_DAYS` | `30` | Number of days to keep component check results before they are pruned. |
+
+## Webhooks
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `CACHET_WEBHOOK_QUEUE_CONNECTION` | _(app default)_ | The queue connection used to dispatch [webhooks](/v3.x/guide/webhooks). |
+| `CACHET_WEBHOOK_QUEUE_NAME` | _(app default)_ | The queue name used to dispatch webhooks. |
+
+## Blog feed
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `CACHET_FEED_URI` | `https://blog.cachethq.io/rss` | The RSS feed used to display blog posts on your status page. |
+| `CACHET_FEED_CACHE` | `3600` | How long, in seconds, to cache the blog feed. |
+
+## Package integration
+
+When running Cachet as a package inside an existing Laravel application, the following variables control how it
+integrates with your host application:
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `CACHET_GUARD` | _(default guard)_ | The authentication guard Cachet uses. |
+| `CACHET_USER_MODEL` | `App\Models\User` | The user model Cachet authenticates against. |
+| `CACHET_USER_MIGRATIONS` | `true` | Whether Cachet loads the default user migrations. |
+| `CACHET_RUN_MIGRATIONS` | `true` | Whether Cachet loads its migrations. Disable if your application manages them itself. |
+| `CACHET_REGISTER_SCHEDULES` | `true` | Whether Cachet registers its scheduled tasks. Disable if your application schedules them itself. |
diff --git a/v3.x/guide/components.mdx b/v3.x/guide/components.mdx
@@ -31,13 +31,14 @@ Cachet also provides a simple way of updating your component statuses directly f
 
 ### Component statuses
 
-Components can have one of five statuses:
+Components can have one of six statuses:
 
 - <Tooltip tip="Status ID: 1"><Icon icon="square-1"/></Tooltip> **Operational**: The component is working as expected.
 - <Tooltip tip="Status ID: 2"><Icon icon="square-2"/></Tooltip> **Performance Issues**: The component is experiencing performance issues.
 - <Tooltip tip="Status ID: 3"><Icon icon="square-3"/></Tooltip> **Partial Outage**: The component is experiencing partial outage.
 - <Tooltip tip="Status ID: 4"><Icon icon="square-4"/></Tooltip> **Major Outage**: The component is experiencing a major outage.
 - <Tooltip tip="Status ID: 5"><Icon icon="square-5"/></Tooltip> **Unknown**: The component status is unknown.
+- <Tooltip tip="Status ID: 6"><Icon icon="square-6"/></Tooltip> **Under Maintenance**: The component is undergoing maintenance. [Schedules](/v3.x/guide/schedules) can set this status automatically.
 
 ## Component groups
 
@@ -47,6 +48,29 @@ To help organize your components, you can group them together into component gro
 Cachet will automatically group any ungrouped components together. Cachet displays ungrouped components beneath any
 component groups on your status page.
 
+A component group has the following properties:
+
+- **Name**: The name of the group.
+- **Visibility**: Whether the group is visible to users, guests, or always hidden.
+- **Collapsed**: How the group behaves on the status page (see [Collapse behavior](#collapse-behavior)).
+- **Order by**: How components within the group are ordered (see [Ordering strategies](#ordering-strategies)).
+
+### Group visibility
+
+Like other resources, each component group has a visibility setting that controls who can see it:
+
+- **Authenticated**: Only visible to authenticated dashboard users.
+- **Guest**: Visible to everyone, including guests.
+- **Hidden**: Never displayed on the status page.
+
+### Collapse behavior
+
+You can control whether a group appears expanded or collapsed on your status page. Each group can be set to one of:
+
+- **Expanded**: The group is always expanded, showing all of its components.
+- **Collapsed**: The group is always collapsed.
+- **Collapsed unless a component is in an incident**: The group stays collapsed until one of its components is not operational, at which point Cachet expands it automatically. This keeps large status pages tidy while still drawing attention to problems.
+
 ## Reordering components
 
 You may reorder components via the dashboard by dragging and dropping them into the desired order. To do this,
@@ -59,4 +83,17 @@ You can also reorder components when editing a component group. The order will r
 <Frame>
     <img className="block dark:hidden" src="/v3.x/images/component-reordering-light.gif" alt="Reorder Components" />
     <img className="hidden dark:block" src="/v3.x/images/component-reordering-dark.gif" alt="Reorder Components" />
-</Frame>
+</Frame>
+
+### Ordering strategies
+
+By default, components follow the manual drag-and-drop order described above. Component groups can also order their
+components automatically. When editing a group, set "Order by" to one of:
+
+- **Manual**: Respect the manual drag-and-drop order.
+- **Name**: Order alphabetically by name.
+- **Status**: Order by component status.
+- **Last updated**: Order by when the component was last updated.
+- **ID**: Order by the component's ID.
+
+For every strategy except manual, you can also choose the direction (ascending or descending).
diff --git a/v3.x/guide/dashboard.mdx b/v3.x/guide/dashboard.mdx
@@ -10,7 +10,8 @@ including managing incidents, components, and subscribers.
 
 ## User management
 
-Cachet currently does not support user management from the dashboard.
+You can manage the users who have access to your Cachet dashboard directly from the dashboard. See the
+[Users](/v3.x/guide/users) guide for more information.
 
 ## Markdown
 
@@ -22,4 +23,4 @@ using a tool by the same name.
 # Incident Title
 
 This is my **first incident**. It's _really_ [serious](https://www.youtube.com/shorts/1LOQOKXTDLY).
-```
+```
diff --git a/v3.x/guide/incidents.mdx b/v3.x/guide/incidents.mdx
@@ -12,6 +12,7 @@ the dashboard. Incidents consist of:
 - **Message**: A detailed description of the incident.
 - **Occurred At**: The time the incident occurred. This can be left empty if the incident happened at the time of reporting.
 - **Visibility**: Whether the incident should be visible to users, guests or always be hidden.
+- **Stickied**: Whether the incident is pinned to the top of your status page. Stickied incidents remain prominently displayed until you unsticky them.
 
 The Cachet dashboard provides a simple interface to manage incidents. You can quickly record a new incident by clicking the
 "New Incident" link in the top navigation bar. You can also view and manage existing incidents by clicking the "Incidents"
@@ -67,4 +68,4 @@ templates with two templating languages:
 </CardGroup>
 
 Incident templates are particularly powerful when combined with the API as they allow you to create a new incident by passing
-a template and variables. Cachet creates the incident from the template, filled in with the variables you provide.
+a template and variables. Cachet creates the incident from the template, filled in with the variables you provide.
diff --git a/v3.x/guide/metrics.mdx b/v3.x/guide/metrics.mdx
@@ -19,6 +19,7 @@ A metric consists of:
 - **Places**: The number of decimal places to display.
 - **Metric Type**: The type of calculation to perform on the metric, e.g. sum or average.
 - **Threshold**: The threshold determines when a new point should be created or the last point updated.
+- **Show when empty**: Whether Cachet displays the metric on your status page when it has no points. When disabled, the metric is hidden until it has data.
 - **Visible**: Whether the metric is visible to users, guests or always hidden.
 
 ## Metric points
@@ -28,4 +29,9 @@ A metric is made up of multiple points that you add over time. Each point consis
 - **Value**: The value of the metric at this point in time.
 - **Timestamp**: The time the metric was recorded.
 
-For performance, if you create a metric point within the threshold of an existing point, Cachet updates the existing point with the new value.
+For performance, if you create a metric point within the threshold of an existing point, Cachet updates the existing point with the new value.
+
+## Reordering metrics
+
+You can reorder metrics to control the order they appear in on your status page, in the same way you
+[reorder components](/v3.x/guide/components#reordering-components).
diff --git a/v3.x/guide/schedules.mdx b/v3.x/guide/schedules.mdx
@@ -13,6 +13,8 @@ A scheduled maintenance event consists of:
 - **Message**: A detailed description of the maintenance.
 - **Scheduled At**: The date and time when the maintenance will start.
 - **Completed At**: The date and time when the maintenance was completed.
+- **Components**: The [components](/v3.x/guide/components) affected by the maintenance, along with the status each should display while it's underway (typically **Under Maintenance**).
+- **Notify subscribers**: Whether to notify your [subscribers](/v3.x/guide/subscribers) about this maintenance, for example when it's rescheduled or completed.
 
 ### Schedule statuses
 
@@ -36,4 +38,4 @@ To update a schedule, head to the "Schedules" panel in the dashboard and click "
 
 <Note>
     You cannot add updates to "Completed" schedules.
-</Note>
+</Note>