openapi: 3.2.0
info:
  title: 7SIGNAL Alert Rules API
  description: This is the 7SIGNAL public API for interacting with the 7SIGNAL Platform
  version: 2.21.1
  contact:
    email: info@7signal.com
  license:
    name: All Rights Reserved
    url: https://www.7signal.com/contact
servers:
- url: https://api-v2.7signal.com
  description: 7SIGNAL API Gateway (production)
tags:
- name: Alert Rules
paths:
  /alerting/alert-rules:
    get:
      summary: List alert rules
      operationId: list-alert-rules
      description: Page through the alert rules for an organization, optionally filtering by metric, enabled state, and name
      security:
      - oauth2: []
      parameters:
      - $ref: '#/components/parameters/common.OrganizationRequestParam'
      - $ref: '#/components/parameters/alert-rules.MetricFilterParam'
      - $ref: '#/components/parameters/alert-rules.EnabledFilterParam'
      - $ref: '#/components/parameters/alert-rules.NameFilterParam'
      - $ref: '#/components/parameters/common.PageRequestParam'
      - $ref: '#/components/parameters/common.PerPageRequestParam'
      - $ref: '#/components/parameters/common.SortFieldParam'
      - $ref: '#/components/parameters/common.SortOrderParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/alert-rules.GetAlertRulesResponse'
        '400':
          $ref: '#/components/responses/common.400BadRequestResponse'
        '403':
          $ref: '#/components/responses/common.403Forbidden'
      tags:
      - Alert Rules
    post:
      summary: Create an alert rule
      operationId: create-alert-rule
      description: Create a new alert rule for an organization
      security:
      - oauth2: []
      parameters:
      - $ref: '#/components/parameters/common.OrganizationRequestParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/alert-rules.AlertRuleRequest'
            examples:
              minimal:
                summary: Minimal — required fields only
                value:
                  metric: client_health_score
                  dimensionSet:
                  - network
                  - band
                  aggregationFunction: avg
                  thresholdValue: 70.0
                  thresholdOperator: <
              full:
                summary: Full — with overrides and notifications
                value:
                  name: Low client health on guest network
                  metric: client_health_score
                  dimensionSet:
                  - network
                  - band
                  aggregationFunction: avg
                  thresholdValue: 70.0
                  thresholdOperator: <
                  pendingPeriodSeconds: 600
                  missingDataPolicy: ignore
                  enabled: true
                  notificationConfig:
                    deliveries:
                    - kind: email
                      address: neteng@example.com
                    - kind: servicenow
                      mdsConfigId: abc-123
                      organizationName: globalcorp
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/alert-rules.AlertRuleResponse'
        '400':
          $ref: '#/components/responses/common.400BadRequestResponse'
        '403':
          $ref: '#/components/responses/common.403Forbidden'
      tags:
      - Alert Rules
  /alerting/alert-rules/summary:
    get:
      summary: Get an alert rules summary
      operationId: alert-rules-summary
      description: Fetch aggregate counts of the alert rules for an organization
      security:
      - oauth2: []
      parameters:
      - $ref: '#/components/parameters/common.OrganizationRequestParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/alert-rules.AlertRulesSummary'
        '400':
          $ref: '#/components/responses/common.400BadRequestResponse'
        '403':
          $ref: '#/components/responses/common.403Forbidden'
      tags:
      - Alert Rules
  /alerting/alert-rules/{id}:
    get:
      summary: Fetch the specified alert rule
      operationId: get-alert-rule
      description: Fetch a single alert rule by its id
      security:
      - oauth2: []
      parameters:
      - $ref: '#/components/parameters/common.OrganizationRequestParam'
      - name: id
        in: path
        description: The alert rule id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/alert-rules.AlertRuleResponse'
        '400':
          $ref: '#/components/responses/common.400BadRequestResponse'
        '403':
          $ref: '#/components/responses/common.403Forbidden'
        '404':
          $ref: '#/components/responses/common.404NotFoundResponse'
      tags:
      - Alert Rules
    put:
      summary: Replace an alert rule
      operationId: update-alert-rule
      description: Fully replace an existing alert rule
      security:
      - oauth2: []
      parameters:
      - $ref: '#/components/parameters/common.OrganizationRequestParam'
      - name: id
        in: path
        description: The alert rule id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/alert-rules.AlertRuleRequest'
            examples:
              minimal:
                summary: Minimal — required fields only
                value:
                  metric: client_health_score
                  dimensionSet:
                  - network
                  - band
                  aggregationFunction: avg
                  thresholdValue: 70.0
                  thresholdOperator: <
              full:
                summary: Full — with overrides and notifications
                value:
                  name: Low client health on guest network
                  metric: client_health_score
                  dimensionSet:
                  - network
                  - band
                  aggregationFunction: avg
                  thresholdValue: 70.0
                  thresholdOperator: <
                  pendingPeriodSeconds: 600
                  missingDataPolicy: ignore
                  enabled: true
                  notificationConfig:
                    deliveries:
                    - kind: email
                      address: neteng@example.com
                    - kind: servicenow
                      mdsConfigId: abc-123
                      organizationName: globalcorp
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/alert-rules.AlertRuleResponse'
        '400':
          $ref: '#/components/responses/common.400BadRequestResponse'
        '403':
          $ref: '#/components/responses/common.403Forbidden'
        '404':
          $ref: '#/components/responses/common.404NotFoundResponse'
      tags:
      - Alert Rules
    delete:
      summary: Delete an alert rule
      operationId: delete-alert-rule
      description: Delete an existing alert rule
      security:
      - oauth2: []
      parameters:
      - $ref: '#/components/parameters/common.OrganizationRequestParam'
      - name: id
        in: path
        description: The alert rule id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: No Content
        '400':
          $ref: '#/components/responses/common.400BadRequestResponse'
        '403':
          $ref: '#/components/responses/common.403Forbidden'
        '404':
          $ref: '#/components/responses/common.404NotFoundResponse'
      tags:
      - Alert Rules
  /alerting/alert-rules/{id}/enabled:
    patch:
      summary: Enable or disable an alert rule
      operationId: patch-alert-rule-enabled
      description: Toggle the enabled state of an alert rule
      security:
      - oauth2: []
      parameters:
      - $ref: '#/components/parameters/common.OrganizationRequestParam'
      - name: id
        in: path
        description: The alert rule id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/alert-rules.EnabledRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/alert-rules.AlertRuleResponse'
        '400':
          $ref: '#/components/responses/common.400BadRequestResponse'
        '403':
          $ref: '#/components/responses/common.403Forbidden'
        '404':
          $ref: '#/components/responses/common.404NotFoundResponse'
      tags:
      - Alert Rules
components:
  parameters:
    common.OrganizationRequestParam:
      name: organization
      in: query
      description: Fetch a specific organization. By default, the organization associated with your JWT token will be used.
      required: false
      schema:
        type: string
    common.PerPageRequestParam:
      name: perPage
      in: query
      description: Fetch a specific number of records per page
      required: false
      schema:
        type: integer
    alert-rules.NameFilterParam:
      name: name
      in: query
      description: Filter the alert rules by name using a case-insensitive partial match
      required: false
      schema:
        type: string
    alert-rules.EnabledFilterParam:
      name: enabled
      in: query
      description: Filter the alert rules by their enabled state
      required: false
      schema:
        type: boolean
    common.SortFieldParam:
      name: sortField
      in: query
      description: The field on which to sort the results
      required: false
      schema:
        type: string
    common.PageRequestParam:
      name: page
      in: query
      description: Fetch a particular page of data. The first page is 1.
      required: false
      schema:
        type: integer
        minimum: 1
    common.SortOrderParam:
      name: order
      in: query
      description: Sort order
      required: false
      schema:
        type: string
        enum:
        - asc
        - desc
    alert-rules.MetricFilterParam:
      name: metric
      in: query
      description: Filter the alert rules by metric name
      required: false
      schema:
        type: string
  schemas:
    alert-rules.AlertRulesSummary:
      type: object
      properties:
        totalCount:
          type: integer
          format: int64
        activeCount:
          type: integer
          format: int64
        disabledCount:
          type: integer
          format: int64
    alert-rules.EnabledRequest:
      type: object
      required:
      - enabled
      properties:
        enabled:
          type: boolean
    alert-rules.Delivery:
      type: object
      description: A single notification target, discriminated by `kind`
      required:
      - kind
      discriminator:
        propertyName: kind
      oneOf:
      - type: object
        required:
        - kind
        - url
        - auth
        properties:
          kind:
            type: string
            enum:
            - webhook
          name:
            type: string
          url:
            type: string
            description: http or https URL with no spaces
            pattern: ^https?://\S+$
          auth:
            $ref: '#/components/schemas/alert-rules.WebhookAuth'
          format:
            $ref: '#/components/schemas/alert-rules.WebhookFormat'
      - type: object
        required:
        - kind
        - address
        properties:
          kind:
            type: string
            enum:
            - email
          name:
            type: string
          address:
            type: string
            format: email
      - type: object
        required:
        - kind
        - mdsConfigId
        - organizationName
        properties:
          kind:
            type: string
            enum:
            - servicenow
          name:
            type: string
          mdsConfigId:
            type: string
          organizationName:
            type: string
    alert-rules.AlertRuleRequest:
      type: object
      description: Body for creating (POST) or replacing (PUT) an alert rule. Enum fields use their wire values exactly as listed (e.g. ">", "avg", "ignore" in lowercase), not the uppercase names.
      required:
      - metric
      - dimensionSet
      - aggregationFunction
      - thresholdValue
      - thresholdOperator
      properties:
        name:
          type: string
          description: Optional human-readable name for the rule.
        metric:
          type: string
          minLength: 1
          description: Required. Non-blank metric name to evaluate.
        dimensionSet:
          type: array
          minItems: 1
          uniqueItems: true
          description: Required. At least one dimension the metric is grouped/keyed by.
          items:
            $ref: '#/components/schemas/alert-rules.Dimension'
        dimensionFilters:
          type:
          - object
          - 'null'
          additionalProperties: true
          description: Optional free-form JSON object narrowing which series the rule applies to.
        aggregationFunction:
          allOf:
          - $ref: '#/components/schemas/alert-rules.AggregationFunction'
          description: Required. How matching samples are aggregated before the threshold comparison.
        thresholdValue:
          type: number
          format: double
          description: Required. Value the aggregated metric is compared against.
        thresholdOperator:
          allOf:
          - $ref: '#/components/schemas/alert-rules.ThresholdOperator'
          description: Required. Comparison operator applied between the aggregated value and thresholdValue.
        pendingPeriodSeconds:
          type: integer
          minimum: 1
          default: 300
          description: Optional. How long (seconds) the condition must hold before an incident is raised. Minimum 1; defaults to 300.
        missingDataPolicy:
          allOf:
          - $ref: '#/components/schemas/alert-rules.MissingDataPolicy'
          default: ignore
          description: Optional. How missing data is treated during evaluation. Defaults to ignore.
        notificationConfig:
          allOf:
          - $ref: '#/components/schemas/alert-rules.NotificationConfig'
          description: Optional. Notification targets fired when the rule breaches.
        locationSelection:
          type:
          - object
          - 'null'
          additionalProperties: true
          description: Optional free-form JSON describing which locations the rule applies to.
        enabled:
          type: boolean
          default: true
          description: Optional. Whether the rule is active. Defaults to true.
      example:
        name: Low client health on guest network
        metric: client_health_score
        dimensionSet:
        - network
        - band
        aggregationFunction: avg
        thresholdValue: 70.0
        thresholdOperator: <
        pendingPeriodSeconds: 600
        missingDataPolicy: ignore
        enabled: true
        notificationConfig:
          deliveries:
          - kind: email
            address: neteng@example.com
          - kind: servicenow
            mdsConfigId: abc-123
            organizationName: globalcorp
    common.Pagination:
      type: object
      required:
      - perPage
      - page
      - total
      - pages
      properties:
        perPage:
          type: integer
          example: 10
        page:
          type: integer
          description: The current page number. The first page is 1
          minimum: 1
          example: 2
        total:
          type: integer
          example: 45
        pages:
          type: integer
          example: 5
    alert-rules.WebhookFormat:
      type: string
      description: Per-destination payload shape for a webhook delivery. Defaults to generic when omitted.
      enum:
      - generic
      - slack
    alert-rules.AlertRuleResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        metric:
          type: string
        dimensionSet:
          type: array
          items:
            $ref: '#/components/schemas/alert-rules.Dimension'
        dimensionFilters:
          type:
          - object
          - 'null'
          additionalProperties: true
        aggregationFunction:
          $ref: '#/components/schemas/alert-rules.AggregationFunction'
        thresholdValue:
          type: number
          format: double
        thresholdOperator:
          $ref: '#/components/schemas/alert-rules.ThresholdOperator'
        pendingPeriodSeconds:
          type: integer
        missingDataPolicy:
          $ref: '#/components/schemas/alert-rules.MissingDataPolicy'
        notificationConfig:
          $ref: '#/components/schemas/alert-rules.NotificationConfig'
        enabled:
          type: boolean
        locationSelection:
          type:
          - object
          - 'null'
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    common.ResponseStatusException:
      type: object
      required:
      - timestamp
      - status
      - error
      - path
      - requestId
      properties:
        timestamp:
          type: string
          format: date-time
        status:
          type: integer
        error:
          type: string
        message:
          type: string
        path:
          type: string
        requestId:
          type: string
    alert-rules.NotificationConfig:
      type: object
      required:
      - deliveries
      properties:
        deliveries:
          type: array
          items:
            $ref: '#/components/schemas/alert-rules.Delivery'
    alert-rules.Dimension:
      type: string
      description: A dimension the metric can be grouped/keyed by
      enum:
      - device_id
      - bssid
      - network
      - band
      - location_id
      - target
    alert-rules.AggregationFunction:
      type: string
      description: How matching samples are aggregated before the threshold comparison
      enum:
      - avg
      - min
      - max
    alert-rules.WebhookAuth:
      type: object
      description: Authentication mode for a webhook delivery, discriminated by `type`. Credentials are referenced by Secrets Manager ARN; the secret value is never stored here.
      required:
      - type
      discriminator:
        propertyName: type
      oneOf:
      - type: object
        required:
        - type
        properties:
          type:
            type: string
            enum:
            - NONE
      - type: object
        required:
        - type
        - username
        - passwordSecretArn
        properties:
          type:
            type: string
            enum:
            - BASIC
          username:
            type: string
          passwordSecretArn:
            type: string
            description: Secrets Manager ARN holding the password
            pattern: ^arn:aws:secretsmanager:[a-z0-9-]+:[0-9]{12}:secret:.+
      - type: object
        required:
        - type
        - tokenSecretArn
        properties:
          type:
            type: string
            enum:
            - TOKEN
          tokenSecretArn:
            type: string
            description: Secrets Manager ARN holding the token
            pattern: ^arn:aws:secretsmanager:[a-z0-9-]+:[0-9]{12}:secret:.+
    alert-rules.ThresholdOperator:
      type: string
      description: The comparison operator applied between the aggregated value and the threshold
      enum:
      - <
      - <=
      - '>'
      - '>='
    alert-rules.MissingDataPolicy:
      type: string
      description: How missing data is treated while evaluating the rule
      enum:
      - ignore
      - good
      - bad
    alert-rules.GetAlertRulesResponse:
      type: object
      required:
      - results
      - pagination
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/alert-rules.AlertRuleResponse'
        pagination:
          $ref: '#/components/schemas/common.Pagination'
  responses:
    common.400BadRequestResponse:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/common.ResponseStatusException'
    common.403Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/common.ResponseStatusException'
    common.404NotFoundResponse:
      description: Resource Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/common.ResponseStatusException'
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth2/token
          scopes: {}