Brix Alert Rules API

openapi: 3.2.0
info:
  title: Brix Alert Rules API
  version: '1'
  summary: 'Control plane for Brix digital signage: screens, content, playlists, schedules, casts and emergencies.'
  description: 'Generated from the route table the API actually mounts

    (`apps/api/routes.snapshot.json`), the description each route is required to

    carry (`tests/contracts/route-registry.json`), and request/response schemas

    (`apps/api/src/openapi/`). CI enforces all three, so this document cannot list a

    route that does not exist or omit one that does.


    **Schemas.** 447 operations carry request and response schemas

    (`x-brix-schema: verified`). Each is checked in CI against the response the

    real handler returns — a missing, mistyped or undeclared field fails the build.

    The remaining operations are route-level only (`x-brix-schema: none`): their

    path, method, permission and purpose are exact, but the shape of `data` is not

    yet modelled, and we would rather say so than publish a schema that validates

    against nothing. Objects are open: a new field is not a breaking change.


    **Envelope.** Success bodies are `{ "data": … }`. Failures are

    `{ "error": "", "message": "…" }`, plus `requestId` on a 5xx.

    Many list routes page opt-in (see each operation): pass `?limit=` and

    follow `nextCursor` via `?cursor=` until it is null.


    **Authentication.** `Authorization: Bearer ` with an API key

    (`ak_…`, created in the console under Settings → API & MCP) or a user session. An

    API key carries a creator-chosen set of `resource.verb` permissions and may be

    pinned to one location''s subtree; a key can never be granted a permission its

    creator does not hold. The permission an operation needs is in

    `x-brix-permission` and in its security requirement.


    **Tenancy.** Every request resolves to one workspace. A resource belonging to

    another tenant returns 404, never 403, so a response never confirms that an

    account exists.


    **Rate limits.** A 429 carries `Retry-After`; a 503 `database_busy` means retry

    after the `Retry-After` interval.'
servers:
- url: https://api.brixsignage.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Alert Rules
paths:
  /v1/alert-rules:
    get:
      operationId: listAlertRules
      tags:
      - Alert Rules
      summary: List alert rules
      description: 'List the alert rules configured for your workspace. Each rule includes its name, trigger, scope configuration, and whether it is enabled. Results are limited to the organization nodes you have access to. Microsoft Teams workflow URLs in `config.teamsUrls` and web addresses in `config.recipients` are credentials, so the response shows them masked: the host and the last four characters, for example `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`.'
      x-brix-permission: alert-rule.view
      x-brix-schema: verified
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
        description: Page size. Omit to get every row; pass it to page by `cursor`.
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: The `nextCursor` of the previous page.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AlertRule'
                  nextCursor:
                    description: Present when `?limit` was passed. Send it back as `?cursor=` for the next page; null on the last page.
                    anyOf:
                    - type: string
                    - type: 'null'
                  total:
                    description: Total matching rows, when the route computes it.
                    type: integer
                required:
                - data
        '401':
          description: Missing, expired or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The token lacks the permission this operation needs (see `x-brix-permission`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth:
        - alert-rule.view
    post:
      operationId: createAlertRule
      tags:
      - Alert Rules
      summary: Create an alert rule
      description: 'Create an alert rule with a `name`, `trigger`, optional `config`, optional `enabled` flag, and optional `nodeId`. If the scope named in `config` does not resolve to an existing target, the request is refused rather than saved. A Microsoft Teams channel is also refused unless `config.teamsUrls` contains at least one valid Microsoft Teams Workflow HTTPS URL. The response shows each URL masked.


        **Notes.**

        - The 201 body is the row as written, not re-read: `nodeId` is absent when the create did not set one.'
      x-brix-permission: alert-rule.create
      x-brix-schema: verified
      x-brix-notes:
      - 'The 201 body is the row as written, not re-read: `nodeId` is absent when the create did not set one.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                trigger:
                  type: string
                config:
                  $ref: '#/components/schemas/AlertRuleConfig'
                enabled:
                  type: boolean
                nodeId:
                  anyOf:
                  - type: string
                  - type: 'null'
              required:
              - name
              - trigger
      responses:
        '201':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: Alert rule id.
                        examples:
                        - alr_4d5e6f7a8b9c0d1e
                      spaceId:
                        type: string
                      name:
                        type: string
                      trigger:
                        type: string
                        description: The first trigger code, e.g. `connection-lost`.
                      config:
                        $ref: '#/components/schemas/AlertRuleConfig'
                      enabled:
                        type: boolean
                      nodeId:
                        anyOf:
                        - type: string
                        - type: 'null'
                      createdAt:
                        type: string
                        description: ISO-8601 timestamp (UTC).
                      updatedAt:
                        type: string
                        description: ISO-8601 timestamp (UTC).
                      deletedAt:
                        anyOf:
                        - type: string
                          description: ISO-8601 timestamp (UTC).
                        - type: 'null'
                    required:
                    - id
                    - spaceId
                    - name
                    - trigger
                    - config
                    - enabled
                    - createdAt
                    - updatedAt
                    - deletedAt
                required:
                - data
        '401':
          description: Missing, expired or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The token lacks the permission this operation needs (see `x-brix-permission`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The location does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: '`name` or `trigger` is missing, the scope target does not exist, or a Microsoft Teams URL is not a workflow URL.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth:
        - alert-rule.create
  /v1/alert-rules/{id}:
    delete:
      operationId: deleteAlertRule
      tags:
      - Alert Rules
      summary: Delete an alert rule
      description: Delete an alert rule. It moves to the recycle bin and stops firing immediately.
      x-brix-permission: alert-rule.delete
      x-brix-schema: verified
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Alert rule id.
        example: alr_4d5e6f7a8b9c0d1e
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      deleted:
                        type: boolean
                        const: true
                    required:
                    - id
                    - deleted
                required:
                - data
        '401':
          description: Missing, expired or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The token lacks the permission this operation needs (see `x-brix-permission`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such alert rule in this workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth:
        - alert-rule.delete
    get:
      operationId: getAlertRule
      tags:
      - Alert Rules
      summary: Get an alert rule
      description: 'Get one alert rule, including its full trigger configuration. Access is limited to the organization nodes you can see. Microsoft Teams workflow URLs in `config.teamsUrls` and web addresses in `config.recipients` are credentials, so the response shows them masked: the host and the last four characters, for example `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`.'
      x-brix-permission: alert-rule.view
      x-brix-schema: verified
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Alert rule id.
        example: alr_4d5e6f7a8b9c0d1e
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AlertRule'
                required:
                - data
        '401':
          description: Missing, expired or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The token lacks the permission this operation needs (see `x-brix-permission`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth:
        - alert-rule.view
    patch:
      operationId: updateAlertRule
      tags:
      - Alert Rules
      summary: Update an alert rule
      description: Update an alert rule's `name`, `trigger`, `config`, `enabled` flag, or `nodeId`. The same scope validation used when creating a rule applies here. To keep a saved URL, send its masked value back unchanged. To replace it, send the new URL. A masked value that matches no saved URL is refused.
      x-brix-permission: alert-rule.edit
      x-brix-schema: verified
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Alert rule id.
        example: alr_4d5e6f7a8b9c0d1e
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                trigger:
                  type: string
                config:
                  $ref: '#/components/schemas/AlertRuleConfig'
                enabled:
                  type: boolean
                nodeId:
                  anyOf:
                  - type: string
                  - type: 'null'
                baseUpdatedAt:
                  description: The `updatedAt` your edit is based on; 409 with the current row if it moved.
                  type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AlertRule'
                required:
                - data
        '401':
          description: Missing, expired or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The token lacks the permission this operation needs (see `x-brix-permission`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No rule with this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: '`conflict`: changed since `baseUpdatedAt`; the body carries `current`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The scope target does not exist, a Microsoft Teams URL is not a workflow URL, or a masked URL matches no saved URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth:
        - alert-rule.edit
  /v1/alert-rules/{id}/restore:
    post:
      operationId: restoreAlertRule
      tags:
      - Alert Rules
      summary: Restore a deleted alert rule
      description: Restore an alert rule that was deleted within the last 30 days. The rule resumes firing once restored.
      x-brix-permission: alert-rule.delete
      x-brix-schema: verified
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Alert rule id.
        example: alr_4d5e6f7a8b9c0d1e
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                      restored:
                        type: boolean
                        const: true
                    required:
                    - id
                    - restored
                required:
                - data
        '401':
          description: Missing, expired or revoked bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The token lacks the permission this operation needs (see `x-brix-permission`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such alert rule in this workspace, or it was purged.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: '`not_deleted`: the rule is not in the recycle bin.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server error. The body carries a `requestId` to quote to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - bearerAuth:
        - alert-rule.delete
components:
  schemas:
    AlertRule:
      type: object
      properties:
        id:
          type: string
          description: Alert rule id.
          examples:
          - alr_4d5e6f7a8b9c0d1e
        spaceId:
          type: string
        name:
          type: string
        trigger:
          type: string
          description: The first trigger code, e.g. `connection-lost`.
        config:
          $ref: '#/components/schemas/AlertRuleConfig'
        enabled:
          type: boolean
        nodeId:
          anyOf:
          - type: string
          - type: 'null'
          description: Home location; null = workspace root.
        createdAt:
          type: string
          description: ISO-8601 timestamp (UTC).
        updatedAt:
          type: string
          description: ISO-8601 timestamp (UTC).
        deletedAt:
          anyOf:
          - type: string
            description: ISO-8601 timestamp (UTC).
          - type: 'null'
      required:
      - id
      - spaceId
      - name
      - trigger
      - config
      - enabled
      - nodeId
      - createdAt
      - updatedAt
      - deletedAt
    Error:
      type: object
      properties:
        error:
          type: string
          description: 'Machine-readable code: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `conflict`, `rate_limited`, `internal_error`, …'
        message:
          description: Human-readable explanation. Safe to show an operator.
          type: string
        requestId:
          description: 'Present on 5xx: quote it to support.'
          type: string
      required:
      - error
      additionalProperties: {}
      description: Error envelope returned by every failing request.
    AlertRuleConfig:
      type: object
      properties:
        codes:
          description: Every trigger code the rule watches; the first is also `trigger`.
          type: array
          items:
            type: string
        severity:
          type: string
        scopeKind:
          description: '`workspace`, `org_unit`, `location`, `screen_group` or `screen`.'
          type: string
        scopeId:
          type: string
        thresholds:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
        channels:
          description: '`in-app`, `email`, `webhook`, `teams`.'
          type: array
          items:
            type: string
        recipients:
          description: 'Email addresses, `role:` tokens and webhook URLs. Webhook URLs are Masked: a delivery URL is a credential (a Microsoft Teams workflow URL carries it in `sig=`), so every response shows the host and the last four characters only — `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`. On update, send a masked value back unchanged to keep the saved URL, or a full URL to replace it.'
          type: array
          items:
            type: string
        teamsUrls:
          description: 'Microsoft Teams workflow URLs for the `teams` channel. Masked: a delivery URL is a credential (a Microsoft Teams workflow URL carries it in `sig=`), so every response shows the host and the last four characters only — `https://prod-12.westus.logic.azure.com/…?sig=••••a1b2`. On update, send a masked value back unchanged to keep the saved URL, or a full URL to replace it.'
          type: array
          items:
            type: string
      additionalProperties: {}
      description: The rule's trigger, scope and delivery settings. Other keys pass through unchanged.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key (`ak_…`) or a user session token. API keys carry `resource.verb` permissions.