Talon.One Logs API

openapi: 3.2.0
info:
  title: Management Logs API
  version: ''
  description: 'The Management API allows you to programmatically do what the Campaign Manager

    does.'
servers:
- url: https://yourbaseurl.talon.one
security:
- manager_auth: []
- management_key: []
tags:
- name: Logs
  description: Represents the Talon.One logs, which contain all incoming and outgoing requests.
paths:
  /v1/applications/{applicationId}/access_logs/no_total:
    get:
      operationId: getAccessLogsWithoutTotalCount
      summary: Get access logs for Application
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Retrieve the list of API calls sent to the specified Application.'
      tags:
      - Logs
      parameters:
      - $ref: '#/components/parameters/applicationId'
      - name: path
        in: query
        description: Only return results where the request path matches the given regular expression.
        example: pattern1
        schema:
          type: string
      - name: method
        in: query
        description: Only return results where the request method matches the given regular expression.
        example: get
        schema:
          type: string
          enum:
          - get
          - put
          - post
          - delete
          - patch
      - name: status
        in: query
        description: Filter results by HTTP status codes.
        example: success
        required: false
        schema:
          type: string
          enum:
          - success
          - error
      - name: rangeStart
        in: query
        required: true
        description: 'Only return results from after this timestamp.


          > [!note] **Note**

          > - This must be an RFC3339 timestamp string.

          > - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting

          >   considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered.

          '
        example: '2024-05-29T15:04:05+07:00'
        schema:
          type: string
          format: date-time
      - name: rangeEnd
        in: query
        required: true
        description: 'Only return results from before this timestamp.


          > [!note] **Note**

          > - This must be an RFC3339 timestamp string.

          > - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting

          >   considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered.

          '
        example: '2024-05-29T15:04:05+07:00'
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/sort'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - hasMore
                - data
                properties:
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccessLogEntry'
  /v1/message_logs:
    get:
      operationId: getMessageLogs
      summary: List message log entries
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Retrieve all message log entries.'
      tags:
      - Logs
      parameters:
      - name: messageID
        in: query
        description: Filter results by message ID.
        example: message1
        required: false
        schema:
          type: string
      - name: changeType
        in: query
        description: Filter results by change type.
        example: CampaignEvaluationTreeChanged
        required: false
        schema:
          type: string
          enum:
          - CampaignEvaluationTreeChanged
          - CampaignNotification
          - CouponCreated
          - CouponUpdated
          - CouponDeleted
          - AsyncCouponsCreated
          - CouponsDeleted
          - CouponsUpdated
          - CouponCodeExpiring
          - StrikethroughPrice
          - LoyaltyPointsAdded
          - LoyaltyPointsDeducted
          - LoyaltyPointsExpiring
          - LoyaltyPointsPendingToActive
          - LoyaltyAddedDeductedPointsBalances
          - LoyaltyCardAddedDeductedPointsBalances
          - TierWillDowngrade
          - TierUpgrade
          - TierDowngrade
          - LoyaltyCardPointsAdded
          - LoyaltyCardPointsDeducted
          - LoyaltyCardPointsExpiring
      - name: notificationIDs
        in: query
        description: Filter results by notification ID (include up to 30 values, separated by a comma).
        example: 23,46
        required: false
        schema:
          type: string
      - name: createdBefore
        in: query
        description: Filter results where request and response times to return entries before parameter value, expected to be an RFC3339 timestamp string. Use UTC time.
        required: false
        example: '2024-05-29T15:04:05Z'
        schema:
          type: string
          format: date-time
      - name: createdAfter
        in: query
        description: Filter results where request and response times to return entries after parameter value, expected to be an RFC3339 timestamp string. Use UTC time.
        required: false
        example: '2024-05-29T15:04:05Z'
        schema:
          type: string
          format: date-time
      - name: cursor
        in: query
        description: 'A specific unique value in the database. If this value is not given, the server fetches results starting with the first record.

          '
        example: U3dhZ2dlciByb2Nrcw==
        required: false
        schema:
          type: string
          format: byte
      - name: period
        in: query
        description: 'Filter results by time period. Choose between the available relative time frames.

          '
        example: 15m
        required: false
        schema:
          type: string
          enum:
          - 15m
          - 30m
          - 1h
          - 4h
          - 1d
          - 2d
      - in: query
        name: isSuccessful
        description: 'Indicates whether to return log entries with either successful or unsuccessful HTTP response codes. When set to`true`, only log entries with `2xx` response codes are returned. When set to `false`, only log entries with `4xx` and `5xx` response codes are returned.

          '
        example: false
        required: false
        schema:
          type: boolean
      - in: query
        name: entityType
        description: 'The entity type the log is related to.

          '
        example: application
        required: true
        schema:
          type: string
          enum:
          - application
          - loyalty_program
          - webhook
      - name: applicationId
        in: query
        description: Filter results by Application ID.
        example: 19
        required: false
        schema:
          type: number
      - name: campaignId
        in: query
        description: Filter results by campaign ID.
        example: 49
        schema:
          type: number
      - in: query
        name: loyaltyProgramId
        description: Identifier of the loyalty program.
        example: 40
        required: false
        schema:
          type: integer
      - in: query
        name: responseCode
        description: Filter results by response status code.
        example: 200
        required: false
        schema:
          type: integer
      - in: query
        name: webhookIDs
        description: Filter results by webhook ID (include up to 30 values, separated by a comma).
        example: 23,46
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageLogEntries'
  /v1/changes:
    get:
      operationId: getChanges
      summary: Get audit logs for an account
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        Retrieve the audit logs displayed in **Accounts > Audit logs**.'
      tags:
      - Logs
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/sort'
      - name: applicationId
        in: query
        description: Filter results by Application ID.
        example: 19
        required: false
        schema:
          type: number
      - name: entityPath
        in: query
        description: Filter results on a case insensitive matching of the url path of the entity
        example: example/url/path
        required: false
        schema:
          type: string
      - in: query
        description: Filter results by user ID.
        example: 34
        required: false
        name: userId
        schema:
          type: integer
      - name: createdBefore
        in: query
        description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the change creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
        required: false
        example: '2024-05-29T15:04:05+07:00'
        schema:
          type: string
          format: date-time
      - name: createdAfter
        in: query
        description: Filter results comparing the parameter value, expected to be an RFC3339 timestamp string, to the change creation timestamp. You can use any time zone setting. Talon.One will convert to UTC internally.
        required: false
        example: '2024-05-29T15:04:05+07:00'
        schema:
          type: string
          format: date-time
      - name: withTotalResultSize
        in: query
        description: 'When this flag is set, the result includes the total number of results for this query. This might decrease performance on large data sets.


          - When `true`: `totalResultSize` contains the total number of results for this query.

          - When `false`: Only `hasMore` is returned, and it is set to `true` when there are more results than shown on the page.

          '
        example: false
        schema:
          type: boolean
      - name: managementKeyId
        in: query
        description: Filter results that match the given management key ID.
        example: 16
        required: false
        schema:
          type: integer
      - name: includeOld
        in: query
        description: When this flag is set to false, the state without the change will not be returned. The default value is true.
        example: false
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  hasMore:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Change'
  /v1/exports:
    get:
      operationId: getExports
      summary: Get exports
      description: '> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.


        List all past exports'
      tags:
      - Logs
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/skip'
      - name: applicationId
        in: query
        description: Filter results by Application ID.
        example: 19
        required: false
        schema:
          type: number
      - name: campaignId
        in: query
        description: Filter by the campaign ID on which the limit counters are used.
        example: 8
        required: false
        schema:
          type: integer
      - name: entity
        in: query
        required: false
        description: The name of the entity type that was exported.
        example: Coupon
        schema:
          type: string
          enum:
          - Coupon
          - Referral
          - Effect
          - CustomerSession
          - LoyaltyLedger
          - LoyaltyLedgerLog
          - Collection
          - AudienceMembership
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - totalResultSize
                - data
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Export'
components:
  parameters:
    applicationId:
      name: applicationId
      in: path
      required: true
      description: The ID of the Application. It is displayed in your Talon.One deployment URL.
      example: 42
      schema:
        type: integer
    sort:
      name: sort
      in: query
      required: false
      description: 'The field by which results should be sorted. By default, results are sorted in ascending order. To sort them in descending order, prefix the field name with `-`.


        **Note:** You may not be able to use all fields for sorting. This is due to performance limitations.

        '
      example: name
      schema:
        type: string
    skip:
      name: skip
      in: query
      required: false
      description: The number of items to skip when paging through large result sets.
      example: 100
      schema:
        type: integer
    pageSize:
      name: pageSize
      in: query
      required: false
      description: The number of items in the response.
      example: 1000
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 1000
  schemas:
    AccessLogEntry:
      type: object
      description: Log of application accesses.
      required:
      - uuid
      - status
      - method
      - requestUri
      - time
      - requestPayload
      - responsePayload
      properties:
        uuid:
          type: string
          description: UUID reference of request.
          example: 606e7d34-2d36-4d53-ac71-d4442c325985
        status:
          type: integer
          description: HTTP status code of response.
          example: 200
        method:
          type: string
          description: HTTP method of request.
          example: PUT
        requestUri:
          type: string
          description: target URI of request
          example: /v2/customer_sessions/Session136667
        time:
          type: string
          format: date-time
          description: timestamp of request
          example: '2023-01-16T16:00:00.700763Z'
        requestPayload:
          type: string
          description: payload of request
          example: "{\n    \"customerSession\": {\n        \"profileId\": \"customer123\",\n        \"state\": \"closed\",\n...\n}"
        responsePayload:
          type: string
          description: payload of response
          example: '{"coupons":[],"createdCoupons":[],...}'
    AccountEntity:
      type: object
      required:
      - accountId
      properties:
        accountId:
          type: integer
          description: The ID of the account that owns this entity.
          example: 3886
    MessageLogResponse:
      type: object
      description: Details of the response.
      properties:
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the response was received.
          example: '2021-07-20T22:00:50Z'
        response:
          type: string
          format: byte
          description: Raw response data.
          example: UmVzcG9uc2UgY29udGVudA==
        status:
          type: integer
          description: HTTP status code of the response.
          example: 200
    MessageLogEntry:
      type: object
      description: Message Log.
      required:
      - service
      - createdAt
      - id
      - entityType
      properties:
        id:
          type: string
          description: Unique identifier of the message.
          example: 123e4567-e89b-12d3-a456-426614174000
        service:
          type: string
          description: Name of the service that generated the log entry.
          example: NotificationService
        changeType:
          type: string
          description: Type of change that triggered the notification.
          example: Update
        notificationId:
          type: integer
          description: ID of the notification.
          example: 101
        notificationName:
          type: string
          description: The name of the notification.
          example: My campaign notification
        webhookId:
          type: integer
          description: ID of the webhook.
          example: 101
        webhookName:
          type: string
          description: The name of the webhook.
          example: My webhook
        request:
          $ref: '#/components/schemas/MessageLogRequest'
        response:
          $ref: '#/components/schemas/MessageLogResponse'
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the log entry was created.
          example: '2021-07-20T22:00:00Z'
        entityType:
          type: string
          description: 'The entity type the log is related to.

            '
          enum:
          - application
          - loyalty_program
          - webhook
          example: loyalty_program
        url:
          type: string
          description: The target URL of the request.
          example: www.my-company.com/my-endpoint-name
        applicationId:
          type: integer
          description: Identifier of the Application.
          example: 5
          minimum: 1
        loyaltyProgramId:
          type: integer
          description: Identifier of the loyalty program.
          example: 2
          minimum: 1
        campaignId:
          type: integer
          description: Identifier of the campaign.
          example: 2
          minimum: 1
    UserEntity:
      type: object
      required:
      - userId
      properties:
        userId:
          type: integer
          description: The ID of the user associated with this entity.
          example: 388
    Export:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - $ref: '#/components/schemas/AccountEntity'
      - $ref: '#/components/schemas/UserEntity'
      - type: object
        required:
        - entity
        - filter
        properties:
          entity:
            type: string
            enum:
            - Coupon
            - Referral
            - Effect
            - CustomerSession
            - LoyaltyLedger
            - LoyaltyLedgerLog
            - Collection
            description: The name of the entity that was exported.
          filter:
            type: object
            description: Map of keys and values that were used to filter the exported rows.
    MessageLogEntries:
      type: object
      required:
      - data
      properties:
        nextCursor:
          description: 'The next value in the database.


            **Note:** If this value is not present, it means that there are no more values in the database for this combination of request parameters.

            '
          type: string
          format: byte
          example: SmJlNERRMHdyNWFsTmRDZDVYU0c=
        data:
          type: array
          description: List of message logs.
          items:
            $ref: '#/components/schemas/MessageLogEntry'
    Change:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - $ref: '#/components/schemas/UserEntity'
      - type: object
        required:
        - entity
        properties:
          applicationId:
            type: integer
            description: ID of application associated with change.
            example: 359
          entity:
            type: string
            description: API endpoint on which the change was initiated.
            example: /v1/applications/359/campaigns/6727
          old:
            type: object
            description: Resource before the change occurred.
            example: {}
          new:
            type: object
            description: Resource after the change occurred.
            example:
              applicationId": 359
              attributes": {}
              campaignGroups": []
              created": '2022-07-08T13:04:02.972762328Z'
              description": ''
              features":
              - referrals
              - loyalty
              id: 6727
          managementKeyId:
            type: integer
            description: ID of management key used to perform changes.
            example: 3
    Entity:
      type: object
      required:
      - id
      - created
      properties:
        id:
          type: integer
          description: The internal ID of this entity.
          example: 6
        created:
          type: string
          format: date-time
          description: The time this entity was created.
          example: '2020-06-10T09:05:27.993483Z'
    MessageLogRequest:
      type: object
      description: Details of the request.
      required:
      - createdAt
      - request
      properties:
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the request was made.
          example: '2021-07-20T21:59:00Z'
        request:
          type: string
          format: byte
          description: Raw request data.
          example: SGVsbG8sIHdvcmxkIQ==
  securitySchemes:
    manager_auth:
      type: apiKey
      name: Authorization
      in: header
      description: 'This authentication scheme relies on a bearer token that you can use to

        access all the endpoints of the Management API.


        To create the token:


        1. Get a bearer token by calling the

        [createSession](#tag/Sessions/operation/createSession) endpoint.

        1. Use the `token` property of the response in the HTTP header of your

        next queries: `Authorization: Bearer $TOKEN`.


        A token is valid for 3 months. In accordance with best pratices, use

        your generated token for all your API requests. Do **not** regenerate a token for each

        request.


        > [!note]

        > We recommend that you use a [Management API key](https://docs.talon.one/management-api#section/Authentication/management_key)

        > instead of a bearer token.

        '
    management_key:
      type: apiKey
      name: Authorization
      in: header
      description: "The API key authentication gives you access to the endpoints selected by\nthe admin who created the key.\n\nUsing an API key is the recommended authentication method.\n\nThe key must be generated by an admin and given to the developer that\nrequires it:\n\n1. Sign in to the Campaign Manager and click **Account** > **Tools** >\n**Management API Keys**.\n1. Click **Create Key** and give it a name.\n1. Set an expiration date.\n   **Tip**: Avoid choosing expiration dates that fall at the end of the year or during other high-traffic periods.\n1. Choose the endpoints the key should give access to.\n1. Click **Create Key**.\n1. Share it with your developer.\n\nThe developer can now use the API key in the HTTP header, prefixing it\nwith `ManagementKey-v1`:\n\n```\nAuthorization: ManagementKey-v1 bd9479c59e16f9dbc644d33aa74d58270fe13bf3\n```\n"