Amperity Audit Events API

openapi: 3.2.0
info:
  title: Amperity API (Unstable) Audit Events API
  version: unstable
  description: '## Overview


    The Amperity API enables programmatic access to your Amperity tenant through a collection

    of RESTful endpoints that support API-first use cases for integrations, applications, and

    custom workflows.'
  contact:
    url: https://docs.amperity.com/api/
servers:
- url: https://app.amperity.com/api
  description: Amazon AWS
- url: https://<tenant-id>.amperity.com/api
  description: Microsoft Azure
  variables:
    tenant-id:
      default: your-tenant-id
      description: Your Amperity tenant ID.
security:
- BearerAuth: []
tags:
- name: Audit Events
  description: Return records for user activity that occurred in your tenant.
paths:
  /audit-events:
    get:
      tags:
      - Audit Events
      summary: GET /audit-events
      operationId: list-events
      description: Amperity maintains records of user activity that occured in your tenant.
      parameters:
      - $ref: '#/components/parameters/ApiVersionHeader'
      - $ref: '#/components/parameters/AmperityTenant'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/NextToken'
      - $ref: '#/components/parameters/WithTotal'
      - name: happened_from
        in: query
        required: false
        description: 'The start date (inclusive) that defines the beginning of the time range for which audit

          events are returned. For example: "2026-04-01T11:11:11Z".


          The start date must be a string, should be in ISO-8601 format, and should be in UTC.

          '
        schema:
          type: string
          format: date-time
          default: '2026-04-01T11:11:11Z'
          example: '2026-04-01T11:11:11Z'
      - name: happened_to
        in: query
        required: false
        description: 'The end date (exclusive) that defines the end of the time range for which audit events

          are returned. For example: "2026-03-01T11:11:11Z".


          The values for the end date must be a string, should be in ISO-8601 format, and should be in UTC.

          '
        schema:
          type: string
          format: date-time
          default: '2026-04-10T11:11:11Z'
          example: '2026-04-10T11:11:11Z'
      responses:
        '200':
          description: 'A successful request returns a response with up to 1000 audit events.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditEventList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    WithTotal:
      name: with_total
      in: query
      required: false
      description: 'Set this value to `true` to include a total count of all results. Default value: `false`.


        > **Note:** Obtaining the total count of all results can be an expensive operation when there is a high number of pages in the results set.

        '
      schema:
        type: boolean
        default: false
    NextToken:
      name: next_token
      in: query
      required: false
      description: 'An opaque token that is used to paginate results. Omit the `next_token` property

        to return the first page. Use the cursor value for `next_token` that was returned

        in a response to view the next page of results.


        For example: `ABCd1fghIJk2l3M`


        > **Note:** The possible values for `next_token` are returned within the 200 response.


        > **Important:** The value for `next_token` cannot be null.

        '
      schema:
        type: string
        example: ZVEy1iwsKBs9a6H
    AmperityTenant:
      name: amperity-tenant
      in: header
      required: true
      description: The unique identifier for the tenant.
      schema:
        type: string
        example: <tenant-id>
    Limit:
      name: limit
      in: query
      required: false
      description: The maximum number of records to include in a single page of results.
      schema:
        type: integer
    ApiVersionHeader:
      name: api-version
      in: header
      required: true
      description: 'A supported version of the Amperity API. For example: 2024-04-01.'
      schema:
        type: string
        enum:
        - '2024-04-01'
        - unstable
        default: unstable
        example: '2024-04-01'
  schemas:
    ErrorResponse:
      type: object
      description: An error response returned by the API.
      required:
      - status
      - message
      additionalProperties: false
      properties:
        status:
          type: integer
          description: The HTTP status code.
          example: 400
        message:
          type: string
          description: A description of the error.
          example: An unexpected error occurred.
    AuditEventList:
      type: object
      description: A paginated list of audit events.
      required:
      - data
      additionalProperties: false
      properties:
        data:
          type: array
          description: Audit event items on this page.
          items:
            $ref: '#/components/schemas/AuditEvent'
        next_token:
          type: string
          description: 'The cursor value to use in a subsequent request to return the next page of results. When empty, the last page has been returned.

            '
          example: ZVEy1iwsKBs9a6H
        total:
          type: integer
          description: The total count of all results. Only returned when with_total is set to true.
    AuditEvent:
      type: object
      description: A record of user activity that occurred within your tenant.
      required:
      - event_id
      - event_type
      - tenant
      - tenant_family
      - happened_at
      - principal_id
      - principal_name
      - principal_email
      - object_id
      - origin_ip
      - user_agent
      - session_id
      additionalProperties: false
      properties:
        event_id:
          type: string
          description: The Amperity internal identifier for the event.
          example: ae-Ab1cDeFg
        event_type:
          type: string
          description: The type of event.
          example: :amperity.alert.audience/created
        tenant:
          type: string
          description: The tenant ID of the tenant associated with the action. This ID may be for a sandbox.
          example: socktown-sb
        tenant_family:
          type: string
          description: 'The name of the tenant family that is associated with the action. When tenant is a sandbox, tenant_family is the tenant ID of the production tenant.

            '
          example: socktown
        happened_at:
          type: string
          format: date-time
          description: The date and time at which the action occurred, in ISO-8601 format and in UTC.
          example: '2026-04-09T17:21:06.747Z'
        principal_id:
          type: string
          description: 'The authentication identifier for the user who initiated the action. This user may be an API key or a non-human user.

            '
          example: google-apps|user@socktown.com
        principal_name:
          type: string
          description: 'The friendly name of the user associated with the activity, if available, otherwise the email address or API key.

            '
          example: Socktown User
        principal_email:
          type: string
          description: The email address for the user who initiated the action.
          example: user@socktown.com
        object_id:
          type: string
          description: The identifier for the object against which the action occurred.
          example: seg-35GMWpn6Y
        object_name:
          type: string
          description: A composed string that describes the objects for which the action occurred.
          example: Socktown Returning Customers
        origin_ip:
          type: string
          description: The IP address associated with the user who initiated the action.
          example: 111.11.111.1
        user_agent:
          type: string
          description: The user agent string of the client that initiated the action.
          example: Mac OS X 4.5.6
        session_id:
          type: string
          description: The identifier for the session from which the action occurred.
          example: Ab1cDeFgHijkLMN2Op3QrStUvWxYZ0123
  responses:
    Forbidden:
      description: Not Authorized — the API key does not have permission for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Internal Server Error — an unexpected error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad Request — the request was malformed or contained invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication Required — no valid Bearer token was provided.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Authenticate using a Bearer token generated from an Amperity API key. Include the token in the Authorization header of every request.

        '