openapi: 3.2.0
info:
  title: Sorry Status Page Notices API
  description: The Sorry™ REST API provides programmatic access to manage status pages, components, notices, notice updates, and subscribers. Build automated incident communication workflows that keep your customers informed during outages and maintenance windows.
  version: v1
  contact:
    name: Sorry App Support
    url: https://docs.sorryapp.com/v1
  license:
    name: Proprietary
    url: https://www.sorryapp.com/
servers:
- url: https://api.sorryapp.com/v1
  description: Sorry App REST API v1
security:
- BearerAuth: []
tags:
- name: Notices
  description: Manage incident and maintenance notices
paths:
  /pages/{page_id}/notices:
    get:
      operationId: listNotices
      summary: List Notices
      description: Displays a list of all notices for a single status page.
      tags:
      - Notices
      parameters:
      - name: page_id
        in: path
        required: true
        schema:
          type: string
      - name: include
        in: query
        description: Comma-separated related resources to include (e.g., components,updates)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response with list of notices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoticesResponse'
        '401':
          description: Unauthorized
        '404':
          description: Status page not found
    post:
      operationId: createNotice
      summary: Create Notice
      description: Create a new incident, maintenance, or general notice on a status page.
      tags:
      - Notices
      parameters:
      - name: page_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNoticeRequest'
      responses:
        '201':
          description: Notice created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoticeResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /pages/{page_id}/notices/{notice_id}:
    get:
      operationId: getNotice
      summary: Get Notice
      description: Retrieve details for a single notice.
      tags:
      - Notices
      parameters:
      - name: page_id
        in: path
        required: true
        schema:
          type: string
      - name: notice_id
        in: path
        required: true
        schema:
          type: string
      - name: include
        in: query
        description: Related resources to include (e.g., components,updates)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful response with notice details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoticeResponse'
        '401':
          description: Unauthorized
        '404':
          description: Notice not found
    patch:
      operationId: updateNotice
      summary: Update Notice
      description: Update a notice's details such as subject, state, or affected components.
      tags:
      - Notices
      parameters:
      - name: page_id
        in: path
        required: true
        schema:
          type: string
      - name: notice_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNoticeRequest'
      responses:
        '200':
          description: Notice updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoticeResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Notice not found
    delete:
      operationId: deleteNotice
      summary: Delete Notice
      description: Delete a notice from the status page.
      tags:
      - Notices
      parameters:
      - name: page_id
        in: path
        required: true
        schema:
          type: string
      - name: notice_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Notice deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Notice not found
components:
  schemas:
    Notice:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - unplanned
          - planned
          - general
        state:
          type: string
          description: Current state of the notice
        timeline_state:
          type: string
        subject:
          type: string
          description: Title of the notice
        synopsis:
          type: string
        link:
          type: string
          format: uri
        tag_list:
          type: array
          items:
            type: string
        began_at:
          type: string
          format: date-time
        ended_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    NoticesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Notice'
        count:
          type: integer
    UpdateNoticeRequest:
      type: object
      properties:
        subject:
          type: string
        state:
          type: string
        additional_comment:
          type: string
        component_ids:
          type: array
          items:
            type: integer
        should_publish:
          type: boolean
    NoticeResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Notice'
    CreateNoticeRequest:
      type: object
      required:
      - type
      - subject
      properties:
        type:
          type: string
          enum:
          - unplanned
          - planned
          - general
        subject:
          type: string
        initial_comment:
          type: string
        state:
          type: string
        component_ids:
          type: array
          items:
            type: integer
        should_publish:
          type: boolean
        begins_at_date:
          type: string
          format: date
        begins_at_time:
          type: string
        duration_in_minutes:
          type: integer
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: User-specific OAuth2 bearer token obtained from the Sorry app dashboard