openapi: 3.0.1
info:
  title: Elevate Events API
  description: >
    ### Events


    This API provides read-only access to time-based events recorded within
    Elevate. Example events include;


    - A user has logged in

    - A user has been locked out due to reaching a maximum number of failed
    login attempts

    - A role has been created


    The initial release of this API contains only security-related events. Over
    time this API will evolve to include events from elsewhere in the system
    e.g.


    - A bill run has been closed

    - Invoices have been distributed

    - A customer has been created
  version: '1.0'
servers:
  - url: https://rest.elevatebilling.com/v1
tags:
  - name: events
    description: Access to time-based events recorded within Elevate
paths:
  /events:
    get:
      tags:
        - events
      summary: Get a list of events
      operationId: findEvents
      x-si-permissions:
        - VIEW_EVENTS
      security:
        - bearerAuth: []
      x-si-filterable: true
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/fields'
        - name: category
          in: query
          description: Filter by event category
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: action
          in: query
          description: Filter by the action in the event
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
        - name: createdFrom
          in: query
          description: Filter by events created after this timestamp
          schema:
            $ref: '#/components/schemas/DateTimeFilterParam'
          required: true
        - name: createdTo
          in: query
          description: Filter by events created before this timestamp
          schema:
            $ref: '#/components/schemas/DateTimeFilterParam'
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
components:
  schemas:
    Event:
      required:
        - timestamp
        - category
        - action
      type: object
      properties:
        id:
          description: Event ID
          readOnly: true
          type: integer
          format: int64
          x-si-validation: '@ValidId'
          example: 1
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the event was created
        category:
          type: string
          description: Category of the event
          minLength: 1
          maxLength: 100
          pattern: '[a-zA-Z0-9_-]+'
          example: authentication
        action:
          type: string
          description: The action performed by the user
          minLength: 1
          maxLength: 100
          pattern: '[a-zA-Z0-9_-]+'
          example: user-login-success
        description:
          type: string
          description: Textual description of the event
          minLength: 1
          maxLength: 255
          pattern: '[\w\p{L}\s%£@&#='':;`’,|!_—–\(\)\\/\-\+\.\?\*\$]*'
          example: User bob.smith has logged in
        username:
          type: string
          description: The username associated with the event
          minLength: 1
          maxLength: 100
          example: bob.smith
        ipAddress:
          type: string
          format: ipv4
          description: The IP address associated with the event
          example: 12.34.56.78
    PageParam:
      description: Page of results to show
      minimum: 1
      type: integer
      format: int32
      example: 1
    ResultsPerPageParam:
      description: Results to return per page
      maximum: 1000
      minimum: 1
      type: integer
      format: int32
      example: 100
    SortParam:
      description: >-
        Comma-delimited list of the fields to sort by - defaults to ascending
        order, suffix :desc to change
      example: id,name | name:desc
      type: string
    FieldsParam:
      description: >-
        Comma-delimited list of the field(s) to return if only a subset is
        required
      example: id,name
      type: string
    StringFilterParam:
      description: >-
        Filter by this string value where value can optionally be prefixed
        (in:|like:)
      example: xyz | in:x,y | like:xyz
      type: string
    DateTimeFilterParam:
      description: >-
        Filter by this date/time value where value can optionally be prefixed
        (gt:|lt:)
      example: yyyy-MM-ddTHH:mm:ssZ | lt:yyyy-MM-ddTHH:mm:ssZ | gt:yyyy-MM-ddTHH:mm:ssZ
      type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    page:
      name: page
      in: query
      description: Page of results to show
      schema:
        $ref: '#/components/schemas/PageParam'
      required: true
    pageSize:
      name: pageSize
      description: Results to return per page
      in: query
      schema:
        $ref: '#/components/schemas/ResultsPerPageParam'
      required: true
    sort:
      name: sort
      in: query
      description: >-
        Comma-delimited list of the fields to sort by - defaults to ascending
        order, suffix :desc to change
      schema:
        $ref: '#/components/schemas/SortParam'
      required: false
    fields:
      name: fields
      in: query
      description: >-
        Comma-delimited list of the field(s) to return if only a subset is
        required
      schema:
        $ref: '#/components/schemas/FieldsParam'
      required: false
