openapi: 3.1.0
info:
  title: Audit Log
  description: Query audit log events
  version: 1.0.0
  contact:
    name: Bandwidth
  termsOfService: https://www.bandwidth.com/legal/terms-of-use-bandwidthcom-web-sites/
servers:
  - url: https://api.bandwidth.com
paths:
  /v1/accounts/{accountId}/events:
    get:
      summary: List Events
      description: >-
        Returns a paginated list of audit log events for the specified account.
        Supports cursor-based pagination and filtering by timestamp, principal,
        resource, event type, and HTTP context. When multiple filter parameters
        are provided, they are combined using AND logic.
      operationId: listEvents
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/timestamp'
        - $ref: '#/components/parameters/afterCursor'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/terms'
        - $ref: '#/components/parameters/principalEnvironment'
        - $ref: '#/components/parameters/principalService'
        - $ref: '#/components/parameters/principalResourceType'
        - $ref: '#/components/parameters/principalResourceId'
        - $ref: '#/components/parameters/resourceEnvironment'
        - $ref: '#/components/parameters/resourceService'
        - $ref: '#/components/parameters/resourceResourceType'
        - $ref: '#/components/parameters/resourceResourceId'
        - $ref: '#/components/parameters/eventType'
        - $ref: '#/components/parameters/httpRequestMethod'
        - $ref: '#/components/parameters/httpResponseStatusCode'
        - $ref: '#/components/parameters/bwContextRequestId'
      responses:
        '200':
          $ref: '#/components/responses/listEventsResponse'
        '400':
          $ref: '#/components/responses/badRequestError'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '403':
          $ref: '#/components/responses/forbiddenError'
        '404':
          $ref: '#/components/responses/notFoundError'
        '405':
          $ref: '#/components/responses/methodNotAllowedError'
        '429':
          $ref: '#/components/responses/tooManyRequestsError'
        5XX:
          $ref: '#/components/responses/serviceUnavailableError'
      tags:
        - Events
components:
  responses:
    listEventsResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/listEventsResponse'
          example:
            links:
              - href: >-
                  https://api.bandwidth.com/v1/accounts/123456/events?limit=100&afterCursor=abc
                rel: self
                method: GET
              - href: >-
                  https://api.bandwidth.com/v1/accounts/123456/events?limit=100&afterCursor=xyz
                rel: next
                method: GET
            data:
              events: []
              terms: []
            errors: []
            page:
              pageSize: 100
              totalCount: 42
    badRequestError:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/genericError'
    forbiddenError:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/genericError'
    unauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/genericError'
    notFoundError:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/genericError'
    methodNotAllowedError:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/genericError'
    tooManyRequestsError:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/genericError'
    serviceUnavailableError:
      description: Service Unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/genericError'
  parameters:
    accountId:
      name: accountId
      in: path
      description: The Bandwidth account ID associated with the events to query.
      required: true
      schema:
        type: string
        examples:
          - '123456'
    timestamp:
      name: timestamp
      in: query
      description: Filtering parameter for `timestamp`
      style: deepObject
      explode: true
      schema:
        $ref: '#/components/schemas/timestampFilter'
    afterCursor:
      name: afterCursor
      in: query
      description: Opaque string used to retrieve the next set of results.
      schema:
        type: string
        examples:
          - 1701374259320946200
    limit:
      name: limit
      in: query
      description: number of results to return
      schema:
        type: integer
        examples:
          - 100
    terms:
      name: terms
      in: query
      description: >-
        a comma-separated string of fields that will have term counts included
        in the response
      style: deepObject
      explode: true
      schema:
        properties:
          eq:
            type: string
            description: Comma-separated list of fields to include term counts for.
            examples:
              - principalResourceType,bwContextAccountId
    principalEnvironment:
      name: principalEnvironment
      in: query
      description: >-
        The environment that emitted this event. Supports comma-separated values
        for OR matching (e.g., `principalEnvironment[eq]=prod,test`).
      style: deepObject
      explode: true
      schema:
        properties:
          eq:
            type: string
            description: Comma-separated list of environment values to match.
    principalService:
      name: principalService
      in: query
      description: >-
        The domain and service name maintaining a resource, in the form
        `<domain>/<service>`. Must be registered before use. Supports
        comma-separated values for OR matching.
      style: deepObject
      explode: true
      schema:
        properties:
          eq:
            type: string
            description: Comma-separated list of service values to match.
    principalResourceType:
      name: principalResourceType
      in: query
      description: >-
        A general name for a resource being referenced (e.g., User, Message).
        Supports comma-separated values for OR matching.
      style: deepObject
      explode: true
      schema:
        properties:
          eq:
            type: string
            description: Comma-separated list of resource type values to match.
    principalResourceId:
      name: principalResourceId
      in: query
      description: >-
        The primary identifier of the resource referenced. Supports
        comma-separated values for OR matching.
      style: deepObject
      explode: true
      schema:
        properties:
          eq:
            type: string
            description: Comma-separated list of resource ID values to match.
    resourceEnvironment:
      name: resourceEnvironment
      in: query
      description: >-
        The environment of the resource acted upon. Supports comma-separated
        values for OR matching (e.g., `resourceEnvironment[eq]=prod,test`).
      style: deepObject
      explode: true
      schema:
        properties:
          eq:
            type: string
            description: Comma-separated list of environment values to match.
    resourceService:
      name: resourceService
      in: query
      description: >-
        The domain and service name of the resource acted upon, in the form
        `<domain>/<service>`. Must be registered before use. Supports
        comma-separated values for OR matching.
      style: deepObject
      explode: true
      schema:
        properties:
          eq:
            type: string
            description: Comma-separated list of service values to match.
    resourceResourceType:
      name: resourceResourceType
      in: query
      description: >-
        A general name for the resource type acted upon (e.g., User, Message).
        Supports comma-separated values for OR matching.
      style: deepObject
      explode: true
      schema:
        properties:
          eq:
            type: string
            description: Comma-separated list of resource type values to match.
    resourceResourceId:
      name: resourceResourceId
      in: query
      description: >-
        The primary identifier of the resource acted upon. Supports
        comma-separated values for OR matching.
      style: deepObject
      explode: true
      schema:
        properties:
          eq:
            type: string
            description: Comma-separated list of resource ID values to match.
    eventType:
      name: eventType
      in: query
      description: >-
        A specific event type that must have been previously registered.
        Supports comma-separated values for OR matching (e.g.,
        `eventType[eq]=auth_success,auth_failure`).
      style: deepObject
      explode: true
      schema:
        properties:
          eq:
            type: string
            description: Comma-separated list of event type values to match.
    httpRequestMethod:
      name: httpRequestMethod
      in: query
      description: >-
        The HTTP request method associated with the event. Supports
        comma-separated values for OR matching (e.g.,
        `httpRequestMethod[eq]=GET,POST`).
      style: deepObject
      explode: true
      schema:
        properties:
          eq:
            type: string
            description: Comma-separated list of HTTP methods to match.
    httpResponseStatusCode:
      name: httpResponseStatusCode
      in: query
      description: >-
        The HTTP response status code associated with the event. Supports
        comma-separated values for OR matching (e.g.,
        `httpResponseStatusCode[eq]=200,201`).
      style: deepObject
      explode: true
      schema:
        properties:
          eq:
            type: integer
            description: Comma-separated list of HTTP status codes to match.
    bwContextRequestId:
      name: bwContextRequestId
      in: query
      description: >-
        Request ID from the Bandwidth context. Supports comma-separated values
        for OR matching.
      style: deepObject
      explode: true
      schema:
        properties:
          eq:
            type: string
            format: uuid
            description: Comma-separated list of request ID UUIDs to match.
  schemas:
    page:
      title: Page
      type: object
      properties:
        pageSize:
          type: integer
          description: Number of results returned in this page.
          example: 100
        totalCount:
          type: integer
          description: The estimated total number of events for this query.
          example: 42
      required:
        - pageSize
    listEventsResponse:
      title: List Events Response
      type: object
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/link'
        data:
          $ref: '#/components/schemas/data'
          nullable: true
        errors:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/error'
        page:
          $ref: '#/components/schemas/page'
      required:
        - links
        - data
        - errors
        - page
    data:
      type: object
      properties:
        events:
          type: array
          description: The list of audit log events matching the query criteria.
          nullable: true
          items:
            $ref: '#/components/schemas/event'
        terms:
          type: array
          description: >-
            Term count aggregations for the fields requested via the terms query
            parameter.
          nullable: true
          items:
            $ref: '#/components/schemas/term'
    event:
      title: AuditLogEvent
      description: An emitted audit event
      type: object
      properties:
        version:
          description: The expected version of the event schema
          type: string
          enum:
            - v1
            - v2
        principal:
          description: The BARN of the principal that triggered the event
          $ref: '#/components/schemas/event/$defs/bandwidthResourceName'
        resource:
          description: The BARN of the resource acted upon
          $ref: '#/components/schemas/event/$defs/bandwidthResourceName'
        eventTime:
          description: The time the event was triggered
          type: string
          format: date-time
          examples:
            - '2024-01-01T00:00:00Z'
        replayTime:
          description: The time the event was replayed
          type: string
          format: date-time
          nullable: true
          examples:
            - '2024-01-01T00:00:00Z'
        deduplicationId:
          description: >-
            A unique identifier for the event to distinguish between a replay
            and a new event
          type: string
          format: uuid
          examples:
            - 80c9a7f7-9a7f-bf58-f6de-942cea16cee4
        eventType:
          description: >-
            The type of event that was triggered. Prefixed with the domain and
            service for the event. Must be registered before use
          $ref: '#/components/schemas/event/$defs/eventTypes'
        http:
          description: >-
            Attributes for the HTTP request/response associated with this event.
            Extracted from OTel Semantic Conventions v1.28.0
          type: object
          nullable: true
          properties:
            requestMethod:
              description: The HTTP request method
              type: string
              examples:
                - GET
                - POST
                - PUT
                - DELETE
                - PATCH
                - HEAD
                - OPTIONS
                - TRACE
                - CONNECT
                - _OTHER
            responseStatusCode:
              description: The HTTP response status code
              type: integer
              minimum: 100
              maximum: 599
              examples:
                - 200
          required:
            - requestMethod
        customerContext:
          description: >-
            Customer-specific context that may be useful after retrieving the
            event, but not necessarily indexed
          type: object
          nullable: true
          additionalProperties:
            type: string
        bwContext:
          description: Additional context for the event specific to Bandwidth
          type: object
          nullable: true
          properties:
            accountId:
              description: The Bandwidth account ID associated with the event
              type: string
              examples:
                - '123456'
            requestId:
              description: A traceable ID for this event
              type: string
              format: uuid
              examples:
                - d3243458-ad6e-4de1-848f-be591b63f360
      required:
        - version
        - principal
        - resource
        - eventTime
        - deduplicationId
        - eventType
      $defs:
        bandwidthResourceName:
          description: A unique identifier for a Bandwidth resource
          type: object
          properties:
            version:
              description: BARN version
              type: string
              examples:
                - v1
            environment:
              description: The environment that emitted this event
              type: string
              examples:
                - prod
                - test
                - qa
                - stage
                - dev
                - lab
                - sbx
            service:
              description: >-
                The domain and service name maintaining a resource, in the form
                <domain>/<service>. Must be registered before use
              type: string
              examples:
                - software_infrastructure/test_service
                - identity/signum
            resourceType:
              description: >-
                A general name for a resource being referenced. This field does
                not need to be registered before use, but consistency is desired
                here as well. Only teams working with a Domain and Service
                should create a new resource type. For example, User, Message
              type: string
              pattern: ^[a-z0-9_-]+$
              examples:
                - userid
            resourceId:
              description: >-
                The primary identifier of the resource referenced. This ID
                should be the common an expected value used to track a resource
                though Bandwidth APIs. If a Resource has a secondary ID, like an
                external ID, that ID should be kept in a separate BARN with a
                different resourceType
              type: string
              pattern: ^[a-z0-9_-]+$
              examples:
                - sample_user_id
                - >-
                  sha256_c0fb1bb9c369c722ca11b6b79c9cb682c645af965709188d651f666ac2680552
          required:
            - version
            - environment
            - service
            - resourceType
            - resourceId
        eventTypes:
          description: The types of events that can be emitted
          type: string
          examples:
            - software_infrastructure/test_service/test_event
            - identity/signum/auth_success
    term:
      type: object
      description: Counts of unique keys for a term
      properties:
        name:
          type: string
          nullable: true
          description: The name of the key
          examples:
            - test-resource-1
        otherCount:
          type: integer
          nullable: true
          description: the number of items excluded from the terms list
          examples:
            - 100
        keys:
          type: object
          nullable: true
          description: the top unique keys and their counts
          additionalProperties:
            type: integer
          examples:
            - sample: 1000
    timestamp:
      type: string
      format: date-time
      description: RFC 3339 timestamp
    timestampFilter:
      title: Timestamp Filter Range
      description: Start and end time for filtering events
      properties:
        eq:
          $ref: '#/components/schemas/timestamp'
          description: Exact timestamp match.
        gte:
          $ref: '#/components/schemas/timestamp'
          description: Starting timestamp (inclusive)
        lte:
          $ref: '#/components/schemas/timestamp'
          description: Ending timestamp (inclusive)
    link:
      type: object
      description: Relevant links for the current resource
      properties:
        href:
          type: string
          description: URI of the link
          examples:
            - https://api.bandwidth.com/v1/accounts/123456/events
        rel:
          type: string
          description: Specifies the relationship between this link and the resource
          examples:
            - self
        method:
          type: string
          description: HTTP method to be used
          examples:
            - GET
      required:
        - href
        - rel
        - method
    error:
      title: Error
      type: object
      properties:
        id:
          type: string
          format: uuid
          nullable: true
          description: A unique identifier for this particular instance of this problem.
          examples:
            - 68793412-493c-4a5a-bcd3-44d2ab695a5b
        type:
          type: string
          description: >-
            A short, human-readable summary of the problem that SHOULD NOT
            change from occurrence to occurrence of the problem.
          examples:
            - REQUEST_ERROR
        description:
          type: string
          description: >-
            A human-readable explanation that SHOULD be specific to this
            occurrence of the problem.
          examples:
            - There was an issue with a field in your request body
        code:
          type: integer
          format: int32
          nullable: true
          description: >-
            An application-specific error code for services with extensive error
            scenarios to supplement `description`.
          minimum: 4
          examples:
            - 51130
        source:
          $ref: '#/components/schemas/errorSource'
          nullable: true
        meta:
          $ref: '#/components/schemas/errorMeta'
          nullable: true
      required:
        - type
        - description
    errorSource:
      title: Error Source
      type: object
      properties:
        parameter:
          type: string
          description: A string indicating which URI query parameter caused the error.
          examples:
            - someParameter
        field:
          type: string
          description: A string indicating which request body field caused the error.
          examples:
            - someField
        header:
          type: string
          description: A string indicating which header field caused the error.
          examples:
            - someHeader
        reference:
          type: string
          description: >-
            A string that references a resource ID or path to the resource (or
            non-existent resource) causing the error.
          examples:
            - /some/reference
    errorMeta:
      title: Error Meta
      type: object
      properties:
        message:
          type: string
          description: >-
            An optional metadata message providing additional context for the
            error.
          examples:
            - An optional metadata field
    genericError:
      title: Generic Error
      type: object
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/link'
          examples:
            - null
        data:
          type: object
          nullable: true
          examples:
            - null
        errors:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/error'
      required:
        - links
        - data
        - errors
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []
tags:
  - name: Audit Log
  - name: Events
