openapi: 3.2.0
info:
  title: Platform Instance Notification Rules API
  version: 1.31.0
  description: User API for accessing platform data
servers:
- url: https://api.losant.com
security:
- bearerAuth: []
tags:
- name: Instance Notification Rules
paths:
  /instances/{instanceId}/notification-rules:
    get:
      operationId: instanceNotificationRules.get
      summary: Returns the notification rules for an instance
      tags:
      - Instance Notification Rules
      parameters:
      - name: instanceId
        in: path
        required: true
        description: ID associated with the instance
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec7417ae143cd83dc4a96
      - name: sortField
        in: query
        required: false
        description: Field to sort the results by
        schema:
          type: string
          enum:
          - name
          - id
          - creationDate
          - lastUpdated
          default: name
        example: name
      - name: sortDirection
        in: query
        required: false
        description: Direction to sort the results by
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
        example: asc
      - name: page
        in: query
        required: false
        description: Which page of results to return
        schema:
          type: string
          default: 0
        example: 0
      - name: perPage
        in: query
        required: false
        description: How many items to return per page
        schema:
          type: string
          default: 100
        example: 10
      - name: filterField
        in: query
        required: false
        description: Field to filter the results by. Blank or not provided means no filtering.
        schema:
          type: string
          enum:
          - name
        example: key
      - name: filter
        in: query
        required: false
        description: Filter to apply against the filtered field. Supports globbing. Blank or not provided means no filtering.
        schema:
          type: string
        example: my*rule
      responses:
        '200':
          description: Collection of notification rules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notificationRules'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      x-losant-auth-scopes:
      - instanceNotificationRules.get
    post:
      operationId: instanceNotificationRules.post
      summary: Create a new notification rule for an instance
      tags:
      - Instance Notification Rules
      parameters:
      - name: instanceId
        in: path
        required: true
        description: ID associated with the instance
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec7417ae143cd83dc4a96
      responses:
        '201':
          description: The successfully created notification rule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notificationRule'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/notificationRulePost'
        description: Notification rule information
      x-losant-auth-scopes:
      - instanceNotificationRules.post
  /instances/{instanceId}/notification-rules/{notificationRuleId}:
    get:
      operationId: instanceNotificationRule.get
      summary: Retrieves information on a notification rule
      tags:
      - Instance Notification Rules
      parameters:
      - name: instanceId
        in: path
        required: true
        description: ID associated with the instance
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec7417ae143cd83dc4a96
      - name: notificationRuleId
        in: path
        required: true
        description: ID associated with the notification rule
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec7417ae143cd83dc4a95
      responses:
        '200':
          description: Notification rule information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notificationRule'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if notification rule was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      x-losant-auth-scopes:
      - instanceNotificationRule.get
    patch:
      operationId: instanceNotificationRule.patch
      summary: Updates information about a notification rule
      tags:
      - Instance Notification Rules
      parameters:
      - name: instanceId
        in: path
        required: true
        description: ID associated with the instance
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec7417ae143cd83dc4a96
      - name: notificationRuleId
        in: path
        required: true
        description: ID associated with the notification rule
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec7417ae143cd83dc4a95
      responses:
        '200':
          description: Updated notification rule information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notificationRule'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if notification rule was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/notificationRulePatch'
        description: Object containing new properties of the notification rule
      x-losant-auth-scopes:
      - instanceNotificationRule.patch
    delete:
      operationId: instanceNotificationRule.delete
      summary: Deletes a notification rule
      tags:
      - Instance Notification Rules
      parameters:
      - name: instanceId
        in: path
        required: true
        description: ID associated with the instance
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec7417ae143cd83dc4a96
      - name: notificationRuleId
        in: path
        required: true
        description: ID associated with the notification rule
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec7417ae143cd83dc4a95
      responses:
        '200':
          description: If notification rule was successfully deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if notification rule was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      x-losant-auth-scopes:
      - instanceNotificationRule.delete
  /instances/{instanceId}/notification-rules/{notificationRuleId}/evaluate:
    post:
      operationId: instanceNotificationRule.evaluate
      summary: Queues the evaluation of a notification rule
      tags:
      - Instance Notification Rules
      parameters:
      - name: instanceId
        in: path
        required: true
        description: ID associated with the instance
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec7417ae143cd83dc4a96
      - name: notificationRuleId
        in: path
        required: true
        description: ID associated with the notification rule
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec7417ae143cd83dc4a95
      responses:
        '202':
          description: If the evaluation was successfully queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/jobEnqueuedResult'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if notification rule was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/notificationRuleEvaluationOptions'
        description: The options for the evaluation
      x-losant-auth-scopes:
      - instanceNotificationRule.evaluate
  /instances/{instanceId}/notification-rules/{notificationRuleId}/logs:
    get:
      operationId: instanceNotificationRule.logs
      summary: Retrieves information on notification rule deliveries
      tags:
      - Instance Notification Rules
      parameters:
      - name: instanceId
        in: path
        required: true
        description: ID associated with the instance
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec7417ae143cd83dc4a96
      - name: notificationRuleId
        in: path
        required: true
        description: ID associated with the notification rule
        schema:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        example: 575ec7417ae143cd83dc4a95
      - name: limit
        in: query
        required: false
        description: Max log entries to return (ordered by time descending)
        schema:
          type: string
          default: 1
        example: 10
      - name: since
        in: query
        required: false
        description: Look for log entries since this time (ms since epoch)
        schema:
          type: string
        example: 1465790400000
      responses:
        '200':
          description: Notification delivery information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/notificationRuleDeliveryLogs'
        '400':
          description: Error if malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Error if notification rule was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      x-losant-auth-scopes:
      - instanceNotificationRule.logs
components:
  schemas:
    error:
      title: Error
      description: Schema for errors returned by the API
      type: object
      properties:
        type:
          type: string
        message:
          type: string
        validationErrors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              validationMessage:
                type: string
    success:
      title: Success
      description: Schema for reporting a successful operation
      type: object
      properties:
        success:
          type: boolean
          enum:
          - true
    jobEnqueuedResult:
      title: Job Enqueued API Result
      description: Schema for the result of a job being queued
      type: object
      properties:
        jobQueued:
          type: boolean
          enum:
          - true
        jobId:
          type: string
          maxLength: 24
        success:
          type: boolean
          enum:
          - true
    notificationRulePatch:
      title: Notification Rule Patch
      description: Schema for the body of a notification rule modification request
      type: object
      properties:
        targetQueryJson:
          type: string
          maxLength: 8192
        name:
          type: string
          minLength: 1
          maxLength: 255
        description:
          type: string
          maxLength: 32767
        enabled:
          type: boolean
        callbackUrl:
          oneOf:
          - type: string
            format: uri
            maxLength: 1024
          - type: 'null'
          - type: string
            enum:
            - ''
        emailConfig:
          oneOf:
          - type: object
            properties:
              subjectTemplate:
                type: string
                minLength: 1
                maxLength: 1024
              bodyTemplate:
                type: string
                maxLength: 32767
              sendToTarget:
                type: string
                enum:
                - admins
                - members
                - none
              sendToOwner:
                type: string
                enum:
                - admins
                - members
                - none
              sendToAddresses:
                type: array
                maxItems: 10
                items:
                  type: string
                  format: email
                  maxLength: 1024
            required:
            - subjectTemplate
            - bodyTemplate
            additionalProperties: false
          - type: 'null'
        ruleConfig:
          type: object
          properties:
            ruleType:
              type: string
              enum:
              - payloadUsage
              - notebookMinuteUsage
            thresholdType:
              type: string
              enum:
              - percentOfLimit
            threshold:
              type: number
              minimum: 0
              maximum: 1000
            maxFrequency:
              type: string
              enum:
              - billingCycle
              - daily
          required:
          - ruleType
          - thresholdType
          - threshold
          additionalProperties: false
      additionalProperties: false
    notificationRule:
      title: Notification Rule
      description: Schema for a single notification rule
      type: object
      properties:
        id:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        notificationRuleId:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        ownerId:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        ownerType:
          type: string
          enum:
          - instance
        instanceId:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        creationDate:
          type: string
          format: date-time
        lastUpdated:
          type: string
          format: date-time
        createdById:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        createdByType:
          type: string
          enum:
          - apiToken
          - user
        lastUpdatedById:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        lastUpdatedByType:
          type: string
          enum:
          - apiToken
          - user
        targetType:
          type: string
          enum:
          - organization
        targetQueryJson:
          type: string
          maxLength: 8192
        name:
          type: string
          minLength: 1
          maxLength: 255
        description:
          type: string
          maxLength: 32767
        enabled:
          type: boolean
        callbackUrl:
          type: string
          format: uri
          maxLength: 1024
        emailConfig:
          type: object
          properties:
            subjectTemplate:
              type: string
              minLength: 1
              maxLength: 1024
            bodyTemplate:
              type: string
              maxLength: 32767
            sendToTarget:
              type: string
              enum:
              - admins
              - members
              - none
            sendToOwner:
              type: string
              enum:
              - admins
              - members
              - none
            sendToAddresses:
              type: array
              maxItems: 10
              items:
                type: string
                format: email
                maxLength: 1024
          required:
          - subjectTemplate
          - bodyTemplate
          additionalProperties: false
        ruleConfig:
          type: object
          properties:
            ruleType:
              type: string
              enum:
              - payloadUsage
              - notebookMinuteUsage
            thresholdType:
              type: string
              enum:
              - percentOfLimit
            threshold:
              type: number
              minimum: 0
              maximum: 1000
            maxFrequency:
              type: string
              enum:
              - billingCycle
              - daily
          required:
          - ruleType
          - thresholdType
          - threshold
          additionalProperties: false
    notificationRules:
      title: Notification Rules
      description: Schema for a collection of notification rules
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/notificationRule'
        count:
          type: integer
        totalCount:
          type: integer
        perPage:
          type: integer
        page:
          type: integer
        filter:
          type: string
        filterField:
          type: string
        sortField:
          type: string
        sortDirection:
          type: string
          enum:
          - asc
          - desc
          - ASC
          - DESC
          - ''
        ownerId:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
        ownerType:
          type: string
          enum:
          - instance
        instanceId:
          type: string
          pattern: ^[A-Fa-f\d]{24}$
    notificationRuleDeliveryLogs:
      title: Notification Rule Delivery Logs
      description: Schema for a set of Notification Rule delivery logs
      type: array
      items:
        type: object
        properties:
          id:
            type: string
            pattern: ^[A-Fa-f\d]{24}$
          notificationRuleDeliveryId:
            type: string
            pattern: ^[A-Fa-f\d]{24}$
          notificationRuleId:
            type: string
            pattern: ^[A-Fa-f\d]{24}$
          ownerId:
            type: string
            pattern: ^[A-Fa-f\d]{24}$
          ownerType:
            type: string
            enum:
            - instance
          requestedById:
            type: string
            pattern: ^[A-Fa-f\d]{24}$
          requestedByType:
            type: string
            enum:
            - user
            - apiToken
            - system
          sentAt:
            type: string
            format: date-time
          targetType:
            type: string
            enum:
            - organization
          targetId:
            type: string
            pattern: ^[A-Fa-f\d]{24}$
          targetName:
            type: string
            minLength: 1
            maxLength: 255
          callbackUrl:
            type: string
            format: uri
            maxLength: 1024
          email:
            type: object
            properties:
              subject:
                type: string
              body:
                type: string
              addresses:
                type: array
                items:
                  type: string
                  format: email
                  maxLength: 1024
          evaluation:
            type: object
            properties:
              value:
                type: number
              limit:
                type: number
              ruleType:
                type: string
                enum:
                - payloadUsage
                - notebookMinuteUsage
              thresholdType:
                type: string
                enum:
                - percentOfLimit
              threshold:
                type: number
                minimum: 0
                maximum: 1000
              maxFrequency:
                type: string
                enum:
                - billingCycle
                - daily
                - unlimited
    notificationRuleEvaluationOptions:
      title: Notification Rule Evaluation Options
      description: Schema for evaluation options for a notification rule
      type: object
      properties:
        ignoreFrequencyCheck:
          type: boolean
      additionalProperties: false
    notificationRulePost:
      title: Notification Rule Post
      description: Schema for the body of a notification rule creation request
      type: object
      properties:
        targetType:
          type: string
          enum:
          - organization
        targetQueryJson:
          type: string
          maxLength: 8192
        name:
          type: string
          minLength: 1
          maxLength: 255
        description:
          type: string
          maxLength: 32767
        enabled:
          type: boolean
        callbackUrl:
          oneOf:
          - type: string
            format: uri
            maxLength: 1024
          - type: 'null'
          - type: string
            enum:
            - ''
        emailConfig:
          oneOf:
          - type: object
            properties:
              subjectTemplate:
                type: string
                minLength: 1
                maxLength: 1024
              bodyTemplate:
                type: string
                maxLength: 32767
              sendToTarget:
                type: string
                enum:
                - admins
                - members
                - none
              sendToOwner:
                type: string
                enum:
                - admins
                - members
                - none
              sendToAddresses:
                type: array
                maxItems: 10
                items:
                  type: string
                  format: email
                  maxLength: 1024
            required:
            - subjectTemplate
            - bodyTemplate
            additionalProperties: false
          - type: 'null'
        ruleConfig:
          type: object
          properties:
            ruleType:
              type: string
              enum:
              - payloadUsage
              - notebookMinuteUsage
            thresholdType:
              type: string
              enum:
              - percentOfLimit
            threshold:
              type: number
              minimum: 0
              maximum: 1000
            maxFrequency:
              type: string
              enum:
              - billingCycle
              - daily
          required:
          - ruleType
          - thresholdType
          - threshold
          additionalProperties: false
      additionalProperties: false
      required:
      - targetType
      - targetQueryJson
      - name
      - ruleConfig
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
x-derived-from:
  format: bravado 1.0
  by: all/0-working/bravado-to-openapi.py (roadmap#799)
  note: 'every action keeps its own path: resource.path + action.path'