openapi: 3.1.0
info:
  title: LaserData Cloud Audit Account Notification Subscriptions API
  description: 'Tenant audit log and per-user activity feed.


    Public REST API for the LaserData Cloud audit service.


    ## Authentication


    Every endpoint accepts either of two auth methods:

    - **API key** (machine / CI / SDK): send in the `ld-api-key` header. Cannot be used on `GET /audit/users/activity` which is session-only.

    - **Session cookie** (browser / console): obtained from `POST /account/sign_in` on the control plane.


    Audit endpoints are read-only and replay-safe by definition.


    ## Pagination


    List endpoints return a `Paged<T>` body (`page`, `total_pages`, `total_results`, `items`) and a `link` header (RFC 8288) with `rel="first"`, `"prev"`, `"next"`, `"last"` when applicable.


    ## Errors


    Error responses follow RFC 7807 `application/problem+json` with `type`, `title`, `code`, `reason`, `instance`, `status`, `retryable`, and optional `field` / `field_issues`. `retryable` is `true` for 408, 425, 429, 500, 502, 503, 504.


    ## Response headers


    - `ld-request`: request ID. Include it when reporting issues.

    - `link`: pagination relations.

    - `retry-after`: wait hint on 429 / 503.'
  termsOfService: https://laserdata.com/terms
  contact:
    name: LaserData Support
    url: https://docs.laserdata.com
    email: support@laserdata.com
  license:
    name: Proprietary
  version: 0.0.66
  x-logo:
    url: https://assets.laserdata.com/laserdata_dark.png
    altText: LaserData
    href: https://laserdata.com
servers:
- url: https://api.laserdata.cloud
  description: Production
security:
- ld_api_key: []
- session_cookie: []
tags:
- name: Notification Subscriptions
  description: Channel subscriptions to notification types
paths:
  /tenants/{tenant_id}/channels/{channel_id}/subscriptions:
    get:
      tags:
      - Notification Subscriptions
      summary: List tenant notification subscriptions
      description: Returns paged subscription entries configured for a tenant-owned channel. Supports pagination and optional message-type filtering.
      operationId: get_tenant_subscriptions
      parameters:
      - name: tenant_id
        in: path
        description: Tenant identifier
        required: true
        schema:
          $ref: '#/components/schemas/TenantId'
      - name: channel_id
        in: path
        description: Channel identifier
        required: true
        schema:
          $ref: '#/components/schemas/NotificationChannelId'
      - name: page
        in: query
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
          minimum: 1
        example: 1
      - name: results
        in: query
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
          minimum: 1
        example: 10
      - name: message_type
        in: query
        required: false
        schema:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/NotificationMessageType'
      responses:
        '200':
          description: Paged subscriptions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paged_NotificationSubscriptionInfo'
        '403':
          description: Insufficient permissions
        '404':
          description: Channel not found
    put:
      tags:
      - Notification Subscriptions
      summary: Replace tenant notification subscriptions
      description: Atomically replaces all subscriptions for a tenant-owned channel with the supplied list.
      operationId: set_tenant_subscriptions
      parameters:
      - name: tenant_id
        in: path
        description: Tenant identifier
        required: true
        schema:
          $ref: '#/components/schemas/TenantId'
      - name: channel_id
        in: path
        description: Channel identifier
        required: true
        schema:
          $ref: '#/components/schemas/NotificationChannelId'
      requestBody:
        description: Complete subscription set for the channel
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetSubscriptions'
        required: true
      responses:
        '204':
          description: Subscriptions set
        '400':
          description: Invalid notification types
        '403':
          description: Insufficient permissions
        '404':
          description: Channel not found
    post:
      tags:
      - Notification Subscriptions
      summary: Create tenant notification subscription
      description: Adds one subscription entry for a tenant-owned channel. The subscription can be scoped to selected tenants, divisions, environments, or deployments.
      operationId: create_tenant_subscription
      parameters:
      - name: tenant_id
        in: path
        description: Tenant identifier
        required: true
        schema:
          $ref: '#/components/schemas/TenantId'
      - name: channel_id
        in: path
        description: Channel identifier
        required: true
        schema:
          $ref: '#/components/schemas/NotificationChannelId'
      requestBody:
        description: Message types and optional scope filters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscription'
        required: true
      responses:
        '201':
          description: Subscription created
        '400':
          description: Invalid notification type
        '403':
          description: Insufficient permissions
        '404':
          description: Channel not found
        '409':
          description: Subscription already exists or limit reached
  /tenants/{tenant_id}/channels/{channel_id}/subscriptions/{subscription_id}:
    get:
      tags:
      - Notification Subscriptions
      summary: Get tenant notification subscription
      description: Returns one subscription entry configured for a tenant-owned channel.
      operationId: get_tenant_subscription
      parameters:
      - name: tenant_id
        in: path
        description: Tenant identifier
        required: true
        schema:
          $ref: '#/components/schemas/TenantId'
      - name: channel_id
        in: path
        description: Channel identifier
        required: true
        schema:
          $ref: '#/components/schemas/NotificationChannelId'
      - name: subscription_id
        in: path
        description: Subscription identifier
        required: true
        schema:
          $ref: '#/components/schemas/NotificationSubscriptionId'
      responses:
        '200':
          description: Subscription details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationSubscriptionDetails'
        '403':
          description: Insufficient permissions
        '404':
          description: Subscription not found
    delete:
      tags:
      - Notification Subscriptions
      summary: Delete tenant notification subscription
      description: Deletes one subscription entry from a tenant-owned channel.
      operationId: delete_tenant_subscription
      parameters:
      - name: tenant_id
        in: path
        description: Tenant identifier
        required: true
        schema:
          $ref: '#/components/schemas/TenantId'
      - name: channel_id
        in: path
        description: Channel identifier
        required: true
        schema:
          $ref: '#/components/schemas/NotificationChannelId'
      - name: subscription_id
        in: path
        description: Subscription identifier
        required: true
        schema:
          $ref: '#/components/schemas/NotificationSubscriptionId'
      responses:
        '204':
          description: Subscription deleted
        '403':
          description: Insufficient permissions
        '404':
          description: Subscription not found
  /tenants/{tenant_id}/divisions/{division_id}/channels/{channel_id}/subscriptions:
    get:
      tags:
      - Notification Subscriptions
      summary: List division notification subscriptions
      description: Returns paged subscription entries configured for a division-owned channel. Supports pagination and optional message-type filtering.
      operationId: get_division_subscriptions
      parameters:
      - name: tenant_id
        in: path
        description: Tenant identifier
        required: true
        schema:
          $ref: '#/components/schemas/TenantId'
      - name: division_id
        in: path
        description: Division identifier
        required: true
        schema:
          $ref: '#/components/schemas/DivisionId'
      - name: channel_id
        in: path
        description: Channel identifier
        required: true
        schema:
          $ref: '#/components/schemas/NotificationChannelId'
      - name: page
        in: query
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
          minimum: 1
        example: 1
      - name: results
        in: query
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
          minimum: 1
        example: 10
      - name: message_type
        in: query
        required: false
        schema:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/NotificationMessageType'
      responses:
        '200':
          description: Paged subscriptions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paged_NotificationSubscriptionInfo'
        '403':
          description: Insufficient permissions
        '404':
          description: Channel not found
    put:
      tags:
      - Notification Subscriptions
      summary: Replace division notification subscriptions
      description: Atomically replaces all subscriptions for a division-owned channel with the supplied list.
      operationId: set_division_subscriptions
      parameters:
      - name: tenant_id
        in: path
        description: Tenant identifier
        required: true
        schema:
          $ref: '#/components/schemas/TenantId'
      - name: division_id
        in: path
        description: Division identifier
        required: true
        schema:
          $ref: '#/components/schemas/DivisionId'
      - name: channel_id
        in: path
        description: Channel identifier
        required: true
        schema:
          $ref: '#/components/schemas/NotificationChannelId'
      requestBody:
        description: Complete subscription set for the channel
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetSubscriptions'
        required: true
      responses:
        '204':
          description: Subscriptions set
        '400':
          description: Invalid notification types
        '403':
          description: Insufficient permissions
        '404':
          description: Channel not found
    post:
      tags:
      - Notification Subscriptions
      summary: Create division notification subscription
      description: Adds one subscription entry for a division-owned channel. The subscription can be scoped to selected tenants, divisions, environments, or deployments.
      operationId: create_division_subscription
      parameters:
      - name: tenant_id
        in: path
        description: Tenant identifier
        required: true
        schema:
          $ref: '#/components/schemas/TenantId'
      - name: division_id
        in: path
        description: Division identifier
        required: true
        schema:
          $ref: '#/components/schemas/DivisionId'
      - name: channel_id
        in: path
        description: Channel identifier
        required: true
        schema:
          $ref: '#/components/schemas/NotificationChannelId'
      requestBody:
        description: Message types and optional scope filters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscription'
        required: true
      responses:
        '201':
          description: Subscription created
        '400':
          description: Invalid notification type
        '403':
          description: Insufficient permissions
        '404':
          description: Channel not found
        '409':
          description: Subscription already exists or limit reached
  /tenants/{tenant_id}/divisions/{division_id}/channels/{channel_id}/subscriptions/{subscription_id}:
    get:
      tags:
      - Notification Subscriptions
      summary: Get division notification subscription
      description: Returns one subscription entry configured for a division-owned channel.
      operationId: get_division_subscription
      parameters:
      - name: tenant_id
        in: path
        description: Tenant identifier
        required: true
        schema:
          $ref: '#/components/schemas/TenantId'
      - name: division_id
        in: path
        description: Division identifier
        required: true
        schema:
          $ref: '#/components/schemas/DivisionId'
      - name: channel_id
        in: path
        description: Channel identifier
        required: true
        schema:
          $ref: '#/components/schemas/NotificationChannelId'
      - name: subscription_id
        in: path
        description: Subscription identifier
        required: true
        schema:
          $ref: '#/components/schemas/NotificationSubscriptionId'
      responses:
        '200':
          description: Subscription details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationSubscriptionDetails'
        '403':
          description: Insufficient permissions
        '404':
          description: Subscription not found
    delete:
      tags:
      - Notification Subscriptions
      summary: Delete division notification subscription
      description: Deletes one subscription entry from a division-owned channel.
      operationId: delete_division_subscription
      parameters:
      - name: tenant_id
        in: path
        description: Tenant identifier
        required: true
        schema:
          $ref: '#/components/schemas/TenantId'
      - name: division_id
        in: path
        description: Division identifier
        required: true
        schema:
          $ref: '#/components/schemas/DivisionId'
      - name: channel_id
        in: path
        description: Channel identifier
        required: true
        schema:
          $ref: '#/components/schemas/NotificationChannelId'
      - name: subscription_id
        in: path
        description: Subscription identifier
        required: true
        schema:
          $ref: '#/components/schemas/NotificationSubscriptionId'
      responses:
        '204':
          description: Subscription deleted
        '403':
          description: Insufficient permissions
        '404':
          description: Subscription not found
components:
  schemas:
    ScopeEntry_DeploymentId:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: integer
          format: int64
          example: 7261845127892140000
          minimum: 0
        name:
          type: string
          example: production
    ScopeEntry_TenantId:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: integer
          format: int64
          example: 7261845022003200001
          minimum: 0
        name:
          type: string
          example: production
    DivisionId:
      type: integer
      format: int64
      example: 7261844974723780000
      minimum: 0
    SetSubscriptions:
      type: object
      required:
      - subscriptions
      properties:
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionEntry'
    NotificationSubscriptionDetails:
      allOf:
      - $ref: '#/components/schemas/NotificationSubscriptionInfo'
    NotificationChannelId:
      type: integer
      format: int64
      example: 7261845612345670000
      minimum: 0
    ScopeEntry_EnvironmentId:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: integer
          format: int64
          example: 7261845066528310000
          minimum: 0
        name:
          type: string
          example: production
    NotificationMessageType:
      type: string
      enum:
      - deployment_created
      - deployment_initialized
      - deployment_upgraded
      - deployment_deleted
      - invitation_accepted
      - invitation_rejected
      - high_cpu_usage
      - high_memory_usage
      - high_disk_usage
      - node_unreachable
      - cpu_usage_resolved
      - memory_usage_resolved
      - disk_usage_resolved
      - node_reachable
      - certificate_expiring
      - billing_limit_reached
      - invoice_created
      - invoice_paid
      - invoice_payment_failed
      - payment_method_added
      - payment_method_removed
      - tenant_created
      - tenant_deleted
      - user_created
      - user_deleted
      - division_created
      - division_deleted
      - environment_created
      - environment_deleted
      - cert_refresh_failed
      - deployment_certificates_rotated
      - deployment_secrets_rotated
      - tenant_updated
      - division_updated
      - environment_updated
      - invitation_created
      - resource_code_requested
      - deployment_inactive
      - tenant_join_requested
      - member_joined
      - shared_host_drained
    CreateSubscription:
      type: object
      required:
      - message_types
      properties:
        message_types:
          type: array
          items:
            $ref: '#/components/schemas/NotificationMessageType'
        scope_deployment_ids:
          type:
          - array
          - 'null'
          items:
            type: integer
            format: int64
            minimum: 0
        scope_division_ids:
          type:
          - array
          - 'null'
          items:
            type: integer
            format: int64
            minimum: 0
        scope_environment_ids:
          type:
          - array
          - 'null'
          items:
            type: integer
            format: int64
            minimum: 0
        scope_tenant_ids:
          type:
          - array
          - 'null'
          items:
            type: integer
            format: int64
            minimum: 0
    ScopeEntry_DivisionId:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: integer
          format: int64
          example: 7261844974723780000
          minimum: 0
        name:
          type: string
          example: production
    Paged_NotificationSubscriptionInfo:
      type: object
      required:
      - total_pages
      - total_results
      - page
      - items
      properties:
        items:
          type: array
          items:
            type: object
            required:
            - id
            - channel_id
            - message_types
            - created_at
            - updated_at
            properties:
              channel_id:
                $ref: '#/components/schemas/NotificationChannelId'
              created_at:
                type: string
                format: date-time
              id:
                $ref: '#/components/schemas/NotificationSubscriptionId'
              message_types:
                type: array
                items:
                  $ref: '#/components/schemas/NotificationMessageType'
              scope_deployments:
                type: array
                items:
                  $ref: '#/components/schemas/ScopeEntry_DeploymentId'
              scope_divisions:
                type: array
                items:
                  $ref: '#/components/schemas/ScopeEntry_DivisionId'
              scope_environments:
                type: array
                items:
                  $ref: '#/components/schemas/ScopeEntry_EnvironmentId'
              scope_tenants:
                type: array
                items:
                  $ref: '#/components/schemas/ScopeEntry_TenantId'
              updated_at:
                type: string
                format: date-time
            example:
              id: 7261845404510330000
              channel_id: 7261845330120500000
              message_types:
              - deployment_created
              - deployment_initialized
              scope_tenants:
              - id: 7261845022003200001
                name: Acme
              scope_environments:
              - id: 7261845066528310000
                name: production
              created_at: '2026-05-20T10:00:00Z'
              updated_at: '2026-05-20T10:00:00Z'
        page:
          type: integer
          format: int64
          example: 1
          minimum: 1
        total_pages:
          type: integer
          format: int64
          example: 4
          minimum: 0
        total_results:
          type: integer
          format: int64
          example: 137
          minimum: 0
    NotificationSubscriptionInfo:
      type: object
      required:
      - id
      - channel_id
      - message_types
      - created_at
      - updated_at
      properties:
        channel_id:
          $ref: '#/components/schemas/NotificationChannelId'
        created_at:
          type: string
          format: date-time
        id:
          $ref: '#/components/schemas/NotificationSubscriptionId'
        message_types:
          type: array
          items:
            $ref: '#/components/schemas/NotificationMessageType'
        scope_deployments:
          type: array
          items:
            $ref: '#/components/schemas/ScopeEntry_DeploymentId'
        scope_divisions:
          type: array
          items:
            $ref: '#/components/schemas/ScopeEntry_DivisionId'
        scope_environments:
          type: array
          items:
            $ref: '#/components/schemas/ScopeEntry_EnvironmentId'
        scope_tenants:
          type: array
          items:
            $ref: '#/components/schemas/ScopeEntry_TenantId'
        updated_at:
          type: string
          format: date-time
      example:
        id: 7261845404510330000
        channel_id: 7261845330120500000
        message_types:
        - deployment_created
        - deployment_initialized
        scope_tenants:
        - id: 7261845022003200001
          name: Acme
        scope_environments:
        - id: 7261845066528310000
          name: production
        created_at: '2026-05-20T10:00:00Z'
        updated_at: '2026-05-20T10:00:00Z'
    TenantId:
      type: integer
      format: int64
      example: 7261845022003200001
      minimum: 0
    SubscriptionEntry:
      type: object
      required:
      - message_types
      properties:
        message_types:
          type: array
          items:
            $ref: '#/components/schemas/NotificationMessageType'
        scope_deployment_ids:
          type:
          - array
          - 'null'
          items:
            type: integer
            format: int64
            minimum: 0
        scope_division_ids:
          type:
          - array
          - 'null'
          items:
            type: integer
            format: int64
            minimum: 0
        scope_environment_ids:
          type:
          - array
          - 'null'
          items:
            type: integer
            format: int64
            minimum: 0
        scope_tenant_ids:
          type:
          - array
          - 'null'
          items:
            type: integer
            format: int64
            minimum: 0
    NotificationSubscriptionId:
      type: integer
      format: int64
      example: 7261845612345671000
      minimum: 0
  securitySchemes:
    ld_api_key:
      type: apiKey
      in: header
      name: ld-api-key
      description: Tenant API key sent in the ld-api-key request header. Scoped to tenant-level audit reads. Cannot be used on user-scope endpoints (`/audit/users/activity`).
    session_cookie:
      type: apiKey
      in: cookie
      name: session
      description: Browser session cookie issued by POST /account/sign_in on core. Required for user-scope endpoints.
externalDocs:
  url: https://docs.laserdata.com
  description: LaserData Cloud documentation