> For the complete documentation index, see [llms.txt](https://docs.statuspal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.statuspal.io/next/platform/api-reference/notices.md).
# Notices
Manage incidents, maintenance events, and info notices
## GET /status\_pages/{subdomain}/notices
> List notices
```json
{"openapi":"3.1.0","info":{"title":"StatusPal Public API","version":"1"},"tags":[{"name":"Notices","description":"Manage incidents, maintenance events, and info notices"}],"servers":[{"url":"https://next.statuspal.io/api/v1","description":"Production"},{"url":"http://spage.test:7070/api/v1","description":"Local development"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Organization API key — issue one via the Rails console (management UI coming soon)"}},"parameters":{"Page":{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1}},"PerPage":{"in":"query","name":"per_page","schema":{"type":"integer","default":20,"maximum":100,"minimum":1}}},"schemas":{"Notice":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"notice_type":{"type":"string","enum":["incident","maintenance","info"]},"title":{"type":"string"},"status":{"type":"string","description":"Valid values by `notice_type`:\n- **incident**: `investigating` · `identified` · `monitoring` · `resolved`\n- **maintenance**: `scheduled` · `in_progress` · `verifying` · `completed`\n- **info**: `info`\n"},"severity":{"type":"string","enum":["major","minor"],"nullable":true},"lifecycle":{"type":"string","enum":["pending","active","completed"],"readOnly":true},"published":{"type":"boolean"},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"latest_update":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/NoticeUpdateObject"}]},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}}},"NoticeUpdateObject":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"status":{"type":"string","description":"The notice status at the time of this update"},"body":{"type":"string","description":"HTML content of the update"},"posted_at":{"type":"string","format":"date-time"},"service_statuses":{"type":"array","description":"The service statuses that were set as part of this timeline entry.","items":{"type":"object","properties":{"service_slug":{"type":"string"},"service_name":{"type":"string"},"container_slug":{"type":"string"},"container_name":{"type":"string"},"status":{"type":"string","enum":["ok","minor","major","critical","maintenance"]}}}}}},"PaginationMeta":{"type":"object","properties":{"current_page":{"type":"integer"},"per_page":{"type":"integer"},"total_count":{"type":"integer"},"total_pages":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"AccountPendingActivation":{"description":"The account is pending activation. A newly created account must be activated by an administrator before its API key can be used.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/status_pages/{subdomain}/notices":{"get":{"summary":"List notices","operationId":"listNotices","tags":["Notices"],"parameters":[{"in":"query","name":"notice_type","schema":{"type":"string","enum":["incident","maintenance","info"]},"description":"Filter by notice type"},{"in":"query","name":"status","schema":{"type":"string"},"description":"Filter by status (e.g. `investigating`, `resolved`, `scheduled`)"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Notice"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AccountPendingActivation"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## Create a notice
> Creates a notice. Optionally include \`initial\_update\` to attach the first timeline\
> entry in the same request — this is the recommended approach for opening an incident\
> or scheduling a maintenance window.
```json
{"openapi":"3.1.0","info":{"title":"StatusPal Public API","version":"1"},"tags":[{"name":"Notices","description":"Manage incidents, maintenance events, and info notices"}],"servers":[{"url":"https://next.statuspal.io/api/v1","description":"Production"},{"url":"http://spage.test:7070/api/v1","description":"Local development"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Organization API key — issue one via the Rails console (management UI coming soon)"}},"schemas":{"NoticeCreate":{"type":"object","required":["notice_type","title"],"properties":{"notice_type":{"type":"string","enum":["incident","maintenance","info"]},"title":{"type":"string","maxLength":255},"severity":{"type":"string","enum":["major","minor"],"nullable":true},"published":{"type":"boolean","default":false},"starts_at":{"type":"string","format":"date-time","description":"Required for `incident` and `maintenance` types."},"ends_at":{"type":"string","format":"date-time","nullable":true},"initial_update":{"description":"Optional first timeline entry created atomically with the notice.\nRecommended for incidents and maintenance windows.\n","allOf":[{"$ref":"#/components/schemas/NoticeUpdateCreate"}]}}},"NoticeUpdateCreate":{"type":"object","required":["body"],"properties":{"status":{"type":"string","description":"Transitions the notice to this status. Defaults to the current notice status\n(i.e. adds an update without changing status).\n"},"body":{"type":"string","description":"HTML or plain-text content for the update.","maxLength":10000},"posted_at":{"type":"string","format":"date-time","description":"Defaults to current time."},"notify":{"type":"boolean","default":true,"description":"Whether to send email/Slack notifications for this update."},"service_statuses":{"type":"array","items":{"$ref":"#/components/schemas/ServiceStatus"},"description":"Sets the live status of one or more services on the status page. Omit to leave\nall service statuses unchanged.\n"}}},"ServiceStatus":{"type":"object","required":["service_slug","status"],"description":"Sets the status of a service (optionally scoped to a specific container).","properties":{"service_slug":{"type":"string"},"container_slug":{"type":"string","description":"Only needed if you have configured multiple containers and want to target a specific\none (e.g. \"API in EU Region\" vs \"API in US Region\"). Omit to target the default container.\n"},"status":{"type":"string","enum":["ok","minor","major","critical","maintenance"]}}},"NoticeDetail":{"allOf":[{"$ref":"#/components/schemas/Notice"},{"type":"object","properties":{"updates":{"type":"array","items":{"$ref":"#/components/schemas/NoticeUpdateObject"},"description":"Full timeline, ordered newest-first"}}}]},"Notice":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"notice_type":{"type":"string","enum":["incident","maintenance","info"]},"title":{"type":"string"},"status":{"type":"string","description":"Valid values by `notice_type`:\n- **incident**: `investigating` · `identified` · `monitoring` · `resolved`\n- **maintenance**: `scheduled` · `in_progress` · `verifying` · `completed`\n- **info**: `info`\n"},"severity":{"type":"string","enum":["major","minor"],"nullable":true},"lifecycle":{"type":"string","enum":["pending","active","completed"],"readOnly":true},"published":{"type":"boolean"},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"latest_update":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/NoticeUpdateObject"}]},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}}},"NoticeUpdateObject":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"status":{"type":"string","description":"The notice status at the time of this update"},"body":{"type":"string","description":"HTML content of the update"},"posted_at":{"type":"string","format":"date-time"},"service_statuses":{"type":"array","description":"The service statuses that were set as part of this timeline entry.","items":{"type":"object","properties":{"service_slug":{"type":"string"},"service_name":{"type":"string"},"container_slug":{"type":"string"},"container_name":{"type":"string"},"status":{"type":"string","enum":["ok","minor","major","critical","maintenance"]}}}}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"AccountPendingActivation":{"description":"The account is pending activation. A newly created account must be activated by an administrator before its API key can be used.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/status_pages/{subdomain}/notices":{"post":{"summary":"Create a notice","operationId":"createNotice","tags":["Notices"],"description":"Creates a notice. Optionally include `initial_update` to attach the first timeline\nentry in the same request — this is the recommended approach for opening an incident\nor scheduling a maintenance window.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoticeCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NoticeDetail"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AccountPendingActivation"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}}}}
```
## GET /status\_pages/{subdomain}/notices/{notice\_id}
> Get a notice
```json
{"openapi":"3.1.0","info":{"title":"StatusPal Public API","version":"1"},"tags":[{"name":"Notices","description":"Manage incidents, maintenance events, and info notices"}],"servers":[{"url":"https://next.statuspal.io/api/v1","description":"Production"},{"url":"http://spage.test:7070/api/v1","description":"Local development"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Organization API key — issue one via the Rails console (management UI coming soon)"}},"schemas":{"NoticeDetail":{"allOf":[{"$ref":"#/components/schemas/Notice"},{"type":"object","properties":{"updates":{"type":"array","items":{"$ref":"#/components/schemas/NoticeUpdateObject"},"description":"Full timeline, ordered newest-first"}}}]},"Notice":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"notice_type":{"type":"string","enum":["incident","maintenance","info"]},"title":{"type":"string"},"status":{"type":"string","description":"Valid values by `notice_type`:\n- **incident**: `investigating` · `identified` · `monitoring` · `resolved`\n- **maintenance**: `scheduled` · `in_progress` · `verifying` · `completed`\n- **info**: `info`\n"},"severity":{"type":"string","enum":["major","minor"],"nullable":true},"lifecycle":{"type":"string","enum":["pending","active","completed"],"readOnly":true},"published":{"type":"boolean"},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"latest_update":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/NoticeUpdateObject"}]},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}}},"NoticeUpdateObject":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"status":{"type":"string","description":"The notice status at the time of this update"},"body":{"type":"string","description":"HTML content of the update"},"posted_at":{"type":"string","format":"date-time"},"service_statuses":{"type":"array","description":"The service statuses that were set as part of this timeline entry.","items":{"type":"object","properties":{"service_slug":{"type":"string"},"service_name":{"type":"string"},"container_slug":{"type":"string"},"container_name":{"type":"string"},"status":{"type":"string","enum":["ok","minor","major","critical","maintenance"]}}}}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"AccountPendingActivation":{"description":"The account is pending activation. A newly created account must be activated by an administrator before its API key can be used.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/status_pages/{subdomain}/notices/{notice_id}":{"get":{"summary":"Get a notice","operationId":"getNotice","tags":["Notices"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NoticeDetail"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AccountPendingActivation"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## DELETE /status\_pages/{subdomain}/notices/{notice\_id}
> Delete a notice
```json
{"openapi":"3.1.0","info":{"title":"StatusPal Public API","version":"1"},"tags":[{"name":"Notices","description":"Manage incidents, maintenance events, and info notices"}],"servers":[{"url":"https://next.statuspal.io/api/v1","description":"Production"},{"url":"http://spage.test:7070/api/v1","description":"Local development"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Organization API key — issue one via the Rails console (management UI coming soon)"}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"AccountPendingActivation":{"description":"The account is pending activation. A newly created account must be activated by an administrator before its API key can be used.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/status_pages/{subdomain}/notices/{notice_id}":{"delete":{"summary":"Delete a notice","operationId":"deleteNotice","tags":["Notices"],"responses":{"204":{"description":"Deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AccountPendingActivation"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```
## Update a notice
> Updates notice metadata (title, severity, scheduled times, published flag).\
> To move the status forward and add a timeline entry, use the Notice Updates resource.
```json
{"openapi":"3.1.0","info":{"title":"StatusPal Public API","version":"1"},"tags":[{"name":"Notices","description":"Manage incidents, maintenance events, and info notices"}],"servers":[{"url":"https://next.statuspal.io/api/v1","description":"Production"},{"url":"http://spage.test:7070/api/v1","description":"Local development"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Organization API key — issue one via the Rails console (management UI coming soon)"}},"schemas":{"NoticePatch":{"type":"object","description":"Edits notice metadata only. Use the Notice Updates resource to change status.","properties":{"title":{"type":"string","maxLength":255},"severity":{"type":"string","enum":["major","minor"],"nullable":true},"published":{"type":"boolean"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time","nullable":true}}},"NoticeDetail":{"allOf":[{"$ref":"#/components/schemas/Notice"},{"type":"object","properties":{"updates":{"type":"array","items":{"$ref":"#/components/schemas/NoticeUpdateObject"},"description":"Full timeline, ordered newest-first"}}}]},"Notice":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"notice_type":{"type":"string","enum":["incident","maintenance","info"]},"title":{"type":"string"},"status":{"type":"string","description":"Valid values by `notice_type`:\n- **incident**: `investigating` · `identified` · `monitoring` · `resolved`\n- **maintenance**: `scheduled` · `in_progress` · `verifying` · `completed`\n- **info**: `info`\n"},"severity":{"type":"string","enum":["major","minor"],"nullable":true},"lifecycle":{"type":"string","enum":["pending","active","completed"],"readOnly":true},"published":{"type":"boolean"},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"latest_update":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/NoticeUpdateObject"}]},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}}},"NoticeUpdateObject":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"status":{"type":"string","description":"The notice status at the time of this update"},"body":{"type":"string","description":"HTML content of the update"},"posted_at":{"type":"string","format":"date-time"},"service_statuses":{"type":"array","description":"The service statuses that were set as part of this timeline entry.","items":{"type":"object","properties":{"service_slug":{"type":"string"},"service_name":{"type":"string"},"container_slug":{"type":"string"},"container_name":{"type":"string"},"status":{"type":"string","enum":["ok","minor","major","critical","maintenance"]}}}}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"AccountPendingActivation":{"description":"The account is pending activation. A newly created account must be activated by an administrator before its API key can be used.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnprocessableEntity":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/status_pages/{subdomain}/notices/{notice_id}":{"patch":{"summary":"Update a notice","operationId":"updateNotice","tags":["Notices"],"description":"Updates notice metadata (title, severity, scheduled times, published flag).\nTo move the status forward and add a timeline entry, use the Notice Updates resource.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoticePatch"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NoticeDetail"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/AccountPendingActivation"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}}}}
```