---
title: "Create a new status override"
method: POST
path: "/v1/status-overrides"
---

# Create a new status override

`POST /v1/status-overrides`

## Request

- Base URL: `https://statusstack.com/api`
- URL: `https://statusstack.com/api/v1/status-overrides`
- Auth: HTTP bearer

## Request body

- object
  - `component_id` string, uuid, required
  - `stack_id` string, uuid, nullable: Stack to scope the override to. Only stack-scoped overrides are honoured on public surfaces (status page, embed, badge, public API); omitting this creates a dashboard-only override that is never displayed. Must belong to the API key's team, and the component must be attached to it.
  - `status` 'operational' | 'degraded_performance' | 'under_maintenance' | 'major_outage' | 'ok' | 'up' | 'online' | 'clear' | 'degraded' | 'warning' | 'partial' | 'minor' | 'partial_outage' | 'outage' | 'down' | 'offline' | 'alert' | 'critical' | 'major' | 'maintenance' | 'info', required: The four canonical values — operational, degraded_performance, under_maintenance, major_outage — are what the override is stored and returned as. Every other value listed is a legacy spelling, accepted on the wire and normalised onto one of those four.
  - `reason` string, nullable
  - `expires_at` string, date-time

## Response `200`

An override already existed for this component/stack pair and was updated in place rather than duplicated.

- StatusOverride
  - `id` string, uuid
  - `component_id` string, uuid
  - `stack_id` string, uuid, nullable: Stack the override is scoped to. Null means dashboard-only; such an override is not shown on any public surface.
  - `status` 'operational' | 'degraded_performance' | 'under_maintenance' | 'major_outage'
  - `reason` string, nullable
  - `expires_at` string, date-time, nullable: When the override lapses; null for one that stays until deleted.
  - `created_at` string, date-time
  - `updated_at` string, date-time

## Other responses

- `201`: Status override created
- `401`: No bearer credentials, or credentials that do not resolve to an API key or Sanctum token. Produced by `ApiAuthentication` ahead of the route, so every operation in the v1 group can return it.
- `403`: The API key lacks `write` permission or is not team-scoped, or the caller is not authorised to create status overrides.
- `422`: Validation failed — unknown or out-of-team component_id/stack_id, a component that is not attached to the given stack, an invalid status, or an expires_at that is not in the future.
- `429`: The `v1-api` rate limit (120 requests per minute) was exceeded. Applies to every operation in the v1 group.

---

[API](https://skmtc.dev/statusstack/apis/statusstack-api.md) - [All operations](https://skmtc.dev/statusstack/apis/statusstack-api/llms.txt) - [OpenAPI document](https://skmtc.dev/statusstack/apis/statusstack-api/revisions/a5fabf6ac5e4?raw)