Talon.One Experiments API

openapi: 3.2.0
info:
  title: Management Experiments API
  version: ''
  description: "The Management API allows you to programmatically do what the Campaign Manager\ndoes. Use this API for back-office operations such as campaign\nand coupon management, maintenance jobs, and bulk operations.\n\nFor more background information about this API, see\n[Management API overview](https://docs.talon.one/docs/dev/management-api/overview).\n\n> [!note] **Are you looking for a different API?**\n> - To integrate with Talon.One directly and send real-time data, see the [Integration API](https://docs.talon.one/integration-api).\n> - To integrate with Talon.One from a CEP or CDP platform, see the [Third-party API](https://docs.talon.one/third-party-api).\n\n## Authentication\n\nManagement API keys are scoped to a user account and become invalid if the user is\ndeactivated or removed from the organization. Use a dedicated service account to\ncreate keys for production integrations.\n\nFor details on generating and managing API keys, see\n[Manage Management API keys](https://docs.talon.one/docs/product/account/dev-tools/manage-mapi-keys).\n\n## Security\n\nConsider the following recommendations:\n- Store API keys securely via environment variables or by using a secret management system.\n- Only call this API from backend services.\n- Implement HTTPS for all communication with the API to ensure data privacy and security.\n- Create [user roles](https://docs.talon.one/docs/product/account/account-settings/manage-roles)\n  reflecting your own company hierarchies.\n\n## Response codes and error handling\n\nTalon.One uses conventional HTTP response codes to indicate the success or failure of an API request.\nCodes in the `2xx` range indicate success. Codes in the `4xx` range indicate the request failed based\non the information provided. Codes in the `5xx` range indicate an error with Talon.One servers.\n\nError responses include a `message` that summarizes what went wrong. Use it for logging and debugging.\n\nWhen a request has one or more specific problems, the `errors` array lists each one separately:\n- `title` gives a short description of the problem\n- `source` shows where the error originated, for example, using a `pointer` property indicating the\n  problematic property in the request body.\n\n| Code | Description | Action |\n|------|-------------|--------|\n| `2xx` | Success | None. |\n| `400` | Bad request | Fix the request (for example, a missing or invalid parameter). Not retryable. |\n| `401` | Unauthorized | Provide a valid API key. Not retryable. |\n| `404` | Not found | Check the resource path or ID. Not retryable. |\n| `409` | Conflict | If you are creating a resource, use a unique resource name/ID. Generally not retryable. |\n| `429` | Rate limit exceeded | Retry with exponential backoff. |\n| `5xx` | Server error | Retry with exponential backoff. |\n\n## URL encoding\n\nEncode all path and query parameter values that contain special characters. This applies to\ncustomer profile IDs, session IDs, coupon codes, and any other user-supplied string passed as\na URL segment or query parameter.\n\nFor example, encode a `10$OFF_NOW` coupon code as `10%24OFF_NOW` before\nincluding it in a request URL.\n\nRequests with unencoded special characters may be misrouted or return unexpected errors.\n\nFor more information, see [HTML URL Encoding Reference](https://www.w3schools.com/tags/ref_urlencode.asp).\n\n## MCP server (closed beta)\n\nTalon.One provides an MCP server that gives AI agents\nread-only access to your campaigns, customers, coupons, and loyalty programs,\nso they can answer questions about your campaigns and customers in plain language.\n\nAgents can explain campaign rule logic, check campaign status and budgets, analyze customer point\nbalances and tier status, and investigate failed API requests.\n\nTo connect, append `/v1/mcp/entrypoint` to your Talon.One deployment URL and authenticate with an MCP\nconnection API key generated in **Campaign Manager > Account > Tools > MCP Connections**.\n\nThe server is compatible with Claude Desktop, Claude Code, Cursor, Gemini CLI, ChatGPT CLI,\nCodex CLI, and other stdio-compatible MCP clients.\n\nFor more information, see [Talon.One MCP server](https://docs.talon.one/docs/dev/mcp).\n\n## Rate limiting\n\nThis API is **not** meant to be used in real-time integrations that directly serve your end users.\nIt supports a maximum of **3 requests per second** for each of these endpoints.\nFor real-time integrations use the [Integration API](https://docs.talon.one/integration-api).\n"
servers:
- url: https://yourbaseurl.talon.one
security:
- manager_auth: []
- management_key: []
tags:
- name: Experiments
  description: 'Represents an A/B testing configuration within a campaign that splits customer sessions across multiple variants to compare rule effects against each other.

    '
paths:
  /v1/applications/{applicationId}/experiments:
    get:
      operationId: listExperiments
      summary: List experiments
      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 experiments of the specified Application that match your filter criteria.'
      tags:
      - Experiments
      parameters:
      - 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
      - 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
      - name: skip
        in: query
        required: false
        description: The number of items to skip when paging through large result sets.
        example: 100
        schema:
          type: integer
      - 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
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - totalResultSize
                properties:
                  totalResultSize:
                    type: integer
                    example: 1
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Experiment'
  /v1/applications/{applicationId}/experiments/{experimentId}:
    get:
      operationId: getExperiment
      summary: Get experiment in 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 given experiment associated with the Application.'
      tags:
      - Experiments
      parameters:
      - 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
      - name: experimentId
        in: path
        description: The ID of the experiment.
        example: 1
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Experiment'
components:
  schemas:
    Ruleset:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - $ref: '#/components/schemas/UserEntity'
      - $ref: '#/components/schemas/NewRuleset'
      - type: object
        properties:
          campaignId:
            type: integer
            title: Campaign ID
            description: The ID of the campaign that owns this entity.
            example: 320
          templateId:
            type: integer
            title: Campaign Template ID
            description: The ID of the campaign template that owns this entity.
            example: 3
          activatedAt:
            type: string
            format: date-time
            description: Timestamp indicating when this Ruleset was activated.
    ExperimentVariant:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - type: object
        required:
        - name
        - isPrimary
        properties:
          name:
            type: string
            example: Variant A
          experimentId:
            type: integer
            example: 10
          ruleset:
            $ref: '#/components/schemas/Ruleset'
          weight:
            type: integer
            example: 12
          isPrimary:
            type: boolean
            example: true
    CampaignVersions:
      type: object
      properties:
        revisionFrontendState:
          type: string
          description: The campaign revision state displayed in the Campaign Manager.
          enum:
          - revised
          - pending
          example: revised
        activeRevisionId:
          type: integer
          description: 'ID of the revision that was last activated on this campaign.

            '
          example: 6
        activeRevisionVersionId:
          type: integer
          description: 'ID of the revision version that is active on the campaign.

            '
          example: 6
        version:
          type: integer
          description: 'Incrementing number representing how many revisions have been activated on this campaign, starts from 0 for a new campaign.

            '
          example: 6
        currentRevisionId:
          type: integer
          description: 'ID of the revision currently being modified for the campaign.

            '
          example: 6
        currentRevisionVersionId:
          type: integer
          description: 'ID of the latest version applied on the current revision.

            '
          example: 6
        stageRevision:
          type: boolean
          description: 'Flag for determining whether we use current revision when sending requests with staging API key.

            '
          example: false
          default: false
    Experiment:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - $ref: '#/components/schemas/ApplicationEntity'
      - type: object
        properties:
          isVariantAssignmentExternal:
            type: boolean
            description: 'The source of the assignment. - false - The variant assignment is handled internally by Talon.One. - true - The variant assignment is handled externally.

              '
          campaign:
            $ref: '#/components/schemas/Campaign'
          activated:
            type: string
            format: date-time
            description: 'The date and time the experiment was activated.

              '
          state:
            type: string
            enum:
            - enabled
            - disabled
            - archived
            default: disabled
            example: enabled
            description: 'A disabled experiment is not evaluated for rules or coupons.

              '
          variants:
            type: array
            items:
              $ref: '#/components/schemas/ExperimentVariant'
          goalType:
            type: string
            enum:
            - other
            - maximize_revenue
            - optimize_discount_efficiency
            - maximize_items_sold
            description: 'The goal of the experiment. Determines which single metric is used to decide the winning variant. When set to `other`, multiple metrics are used.

              '
          goalDescription:
            type: string
            description: 'A description of the experiment goal. Provides context for the AI summary and helps it interpret the outcome of the experiment against the stated goal.

              '
            example: Offering free shipping will increase average order revenue more than a 10% discount
          deletedat:
            type: string
            format: date-time
            description: 'The date and time the experiment was deleted.

              '
        required:
        - state
        - goalType
    Rule:
      type: object
      required:
      - title
      - condition
      - effects
      properties:
        id:
          type: string
          format: uuid
          description: A unique identifier for the rule.
          example: 7fa800a8-ac8d-4792-85dc-c4650dcc8f23
        parentId:
          type: string
          format: uuid
          description: The ID of the rule that was copied to create this rule.
          example: 7fa800a8-ac8d-4792-85dc-c4650dcc8f23
        title:
          type: string
          description: A short description of the rule.
          example: Give discount via coupon
        description:
          type: string
          description: A longer, more detailed description of the rule.
          example: Creates a discount when a coupon is valid
        bindings:
          type: array
          description: An array that provides objects with variable names (name) and talang expressions to whose result they are bound (expression) during rule evaluation. The order of the evaluation is decided by the position in the array.
          items:
            $ref: '#/components/schemas/Binding'
        condition:
          type: array
          description: A Talang expression that will be evaluated in the context of the given event.
          minItems: 1
          example:
          - and
          - - couponValid
          items: {}
        effects:
          type: array
          description: An array of effectful Talang expressions in arrays that will be evaluated when a rule matches.
          items:
            type: array
            items: {}
          example:
          - catch
          - - noop
          - - setDiscount
            - 10% off
            - - '*'
              - - .
                - Session
                - Total
              - - /
                - 10
                - 100
    Campaign:
      allOf:
      - $ref: '#/components/schemas/EntityWithTalangVisibleID'
      - $ref: '#/components/schemas/ApplicationEntity'
      - $ref: '#/components/schemas/UserEntity'
      - $ref: '#/components/schemas/BaseCampaign'
      - $ref: '#/components/schemas/AdditionalCampaignProperties'
      - $ref: '#/components/schemas/CampaignVersions'
      - type: object
        required:
        - reevaluateOnReturn
    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'
    UserEntity:
      type: object
      required:
      - userId
      properties:
        userId:
          type: integer
          description: The ID of the user associated with this entity.
          example: 388
    CodeGeneratorSettings:
      type: object
      properties:
        validCharacters:
          type: array
          description: 'List of characters used to generate the random parts of a code.

            '
          example:
          - A
          - B
          - C
          - D
          - E
          - F
          - G
          - H
          - I
          - J
          - K
          - L
          - M
          - N
          - O
          - P
          - Q
          - R
          - S
          - T
          - U
          - V
          - W
          - X
          - Y
          - Z
          - '0'
          - '1'
          - '2'
          - '3'
          - '4'
          - '5'
          - '6'
          - '7'
          - '8'
          - '9'
          items:
            type: string
        couponPattern:
          type: string
          description: 'The pattern used to generate codes, such as coupon codes, referral codes, and loyalty cards. The character `#` is a placeholder and is replaced by a random character from the `validCharacters` set.

            '
          maxLength: 100
          minLength: 3
          pattern: ^[A-Za-z0-9._%+@#-]+$
          example: SUMMER-####-####
      additionalProperties: false
      required:
      - couponPattern
      - validCharacters
    Binding:
      type: object
      required:
      - name
      - expression
      properties:
        name:
          type: string
          description: A descriptive name for the value to be bound.
          example: Discount percentage
        type:
          type: string
          description: 'The kind of binding. Possible values are:

            - `bundle`

            - `cartItemFilter`

            - `subledgerBalance`

            - `templateParameter`

            '
          example: templateParameter
        expression:
          type: array
          description: 'A Talang expression that is evaluated, and its result is bound to the name of

            the binding. The first element must be one of the functions or operators supported

            by Talang, followed by its arguments. The arguments can be strings, numbers, or

            nested expressions. For example:

            - `["list", "10014", "10015"]` calls the `list` function to build a list of strings.

            - `["+", 2, 0]` uses the `+` operator to add two numbers.

            '
          example:
          - identity
          - 10
          items: {}
        valueType:
          type: string
          description: 'The data type of the value. One of the following:

            - `string`

            - `number`

            - `boolean`

            '
          example: number
        minValue:
          type: number
          description: The minimum value allowed for this placeholder.
          example: 0
        maxValue:
          type: number
          description: The maximum value allowed for this placeholder.
          example: 19.9
        attributeId:
          type: integer
          title: Attribute ID
          description: Identifier of the attribute attached to the placeholder.
          example: 100
        description:
          type: string
          description: Description of the placeholder field and its value in the template. This text can be shown when creating campaigns from this template.
          example: The percentage discount applied to the cart total.
    BaseCampaign:
      type: object
      properties:
        name:
          type: string
          title: Campaign Name
          description: A user-facing name for this campaign.
          minLength: 1
          example: Summer promotions
        description:
          type: string
          title: Campaign Description
          description: A detailed description of the campaign.
          example: Campaign for all summer 2021 promotions
        startTime:
          type: string
          format: date-time
          description: Timestamp when the campaign will become active.
          example: '2021-07-20T22:00:00Z'
        endTime:
          type: string
          format: date-time
          description: Timestamp when the campaign will become inactive.
          example: '2021-09-22T22:00:00Z'
        attributes:
          type: object
          description: Arbitrary properties associated with this campaign.
        state:
          type: string
          enum:
          - enabled
          - disabled
          - archived
          default: enabled
          example: enabled
          description: 'A disabled or archived campaign is not evaluated for rules or coupons.

            '
        activeRulesetId:
          type: integer
          description: '[ID of Ruleset](https://docs.talon.one/management-api#tag/Campaigns/operation/getRulesets) this

            campaign applies on customer session evaluation.

            '
          example: 6
        tags:
          type: array
          description: A list of tags for the campaign.
          example:
          - summer
          maxItems: 50
          items:
            type: string
            minLength: 1
            maxLength: 50
        reevaluateOnReturn:
          type: boolean
          title: Reevaluate on return
          description: Indicates whether this campaign should be reevaluated when a customer returns an item.
          example: true
        features:
          type: array
          description: The features enabled in this campaign.
          example:
          - coupons
          - referrals
          items:
            type: string
            enum:
            - coupons
            - referrals
            - loyalty
            - giveaways
            - strikethrough
            - achievements
            - advancedEvents
        couponSettings:
          $ref: '#/components/schemas/CodeGeneratorSettings'
        referralSettings:
          $ref: '#/components/schemas/CodeGeneratorSettings'
        limits:
          type: array
          description: 'The set of [budget limits](https://docs.talon.one/docs/product/campaigns/settings/managing-campaign-budgets) for this campaign.

            '
          items:
            $ref: '#/components/schemas/LimitConfig'
        campaignGroups:
          type: array
          description: 'The IDs of the [campaign groups](https://docs.talon.one/docs/product/account/managing-campaign-groups) this campaign belongs to.

            '
          example:
          - 1
          - 3
          items:
            type: integer
        type:
          type: string
          title: Type
          enum:
          - cartItem
          - advanced
          default: advanced
          example: advanced
          description: "The campaign type. Possible type values:\n  - `cartItem`: Type of campaign that can apply effects only to cart items.\n  - `advanced`: Type of campaign that can apply effects to customer sessions and cart items.\n"
        linkedStoreIds:
          type: array
          description: 'A list of store IDs that you want to link to the campaign.


            **Note:** Campaigns with linked store IDs will only be evaluated when there is a

            [customer session update](https://docs.talon.one/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)

            that references a linked store.

            '
          items:
            type: integer
          example:
          - 1
          - 2
          - 3
        couponAttributes:
          type: object
          description: Arbitrary properties associated with coupons in this campaign.
      required:
      - name
      - state
      - tags
      - limits
      - features
    NewRuleset:
      type: object
      required:
      - rules
      - bindings
      properties:
        rules:
          type: array
          description: Set of rules to apply.
          items:
            $ref: '#/components/schemas/Rule'
        strikethroughRules:
          type: array
          description: Set of rules to apply for strikethrough.
          items:
            $ref: '#/components/schemas/Rule'
        bindings:
          type: array
          description: An array that provides objects with variable names (name) and talang expressions to whose result they are bound (expression) during rule evaluation. The order of the evaluation is decided by the position in the array.
          items:
            $ref: '#/components/schemas/Binding'
          example: []
        rbVersion:
          type: string
          description: The version of the rulebuilder used to create this ruleset.
          example: v2
        activate:
          type: boolean
          description: Indicates whether this created ruleset should be activated for the campaign that owns it.
          example: true
    CampaignBudget:
      type: object
      required:
      - action
      - limit
      - counter
      properties:
        action:
          type: string
          description: 'The limitable action to which this limit applies. For example:

            - `setDiscount`

            - `setDiscountEffect`

            - `redeemCoupon`

            - `createCoupon`

            '
          example: createCoupon
        limit:
          type: number
          minimum: 0
          example: 1000
          description: The value to set for the limit.
        counter:
          type: number
          minimum: 0
          example: 42
          description: The number of occurrences of the limited action in the context of the campaign.
    EntityWithTalangVisibleID:
      type: object
      required:
      - id
      - created
      properties:
        id:
          type: integer
          description: Unique ID for this entity.
          example: 4
        created:
          type: string
          format: date-time
          description: The exact moment this entity was created.
          example: '2020-06-10T09:05:27.993483Z'
    ApplicationEntity:
      type: object
      required:
      - applicationId
      properties:
        applicationId:
          type: integer
          description: The ID of the Application that owns this entity.
          example: 322
    AdditionalCampaignProperties:
      type: object
      properties:
        budgets:
          type: array
          items:
            $ref: '#/components/schemas/CampaignBudget'
          description: 'A list of all the budgets that are defined by this campaign and their usage.


            **Note:** Budgets that are not defined do not appear in this list and their usage is

            not counted until they are defined.

            '
        couponRedemptionCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Number of coupons redeemed in the campaign.

            '
          example: 163
        referralRedemptionCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Number of referral codes redeemed in the campaign.

            '
          example: 3
        discountCount:
          type: number
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total amount of discounts redeemed in the campaign.

            '
          example: 288
        discountEffectCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of times discounts were redeemed in this campaign.

            '
          example: 343
        couponCreationCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of coupons created by rules in this campaign.

            '
          example: 16
        customEffectCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of custom effects triggered by rules in this campaign.

            '
          example: 0
        referralCreationCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of referrals created by rules in this campaign.

            '
          example: 8
        addFreeItemEffectCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of times the [add free item effect](https://docs.talon.one/docs/dev/integration-api/api-effects#addfreeitem) can be triggered in this campaign.

            '
          example: 0
        awardedGiveawaysCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of giveaways awarded by rules in this campaign.

            '
          example: 9
        createdLoyaltyPointsCount:
          type: number
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of loyalty points created by rules in this campaign.

            '
          example: 9
        createdLoyaltyPointsEffectCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of loyalty point creation effects triggered by rules in this campaign.

            '
          example: 2
        redeemedLoyaltyPointsCount:
          type: number
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of loyalty points redeemed by rules in this campaign.

            '
          example: 8
        redeemedLoyaltyPointsEffectCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of loyalty point redemption effects triggered by rules in this campaign.

            '
          example: 9
        callApiEffectCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of webhooks triggered by rules in this campaign.

            '
          example: 0
        reservecouponEffectCount:
          type: integer
          deprecated: true
          description: 'This property is **deprecated**. The count should be available under *budgets* property.

            Total number of reserve coupon effects triggered by rules in this campaign.

            '
          example: 9
        lastActivity:
          type: string
          format: date-time
          example: '2022-11-10T23:00:00Z'
          description: Timestamp of the most recent event received by this campaign.
        updated:
          type: string
          format: date-time
          example: '2022-10-27T15:00:00Z'
          description: 'Timestamp of the most recent update to the campaign''s property. Updates to external entities used in this campaign

            are **not** registered by this property, such as collection or coupon updates.

            '
        createdBy:
          type: string
          description: Name of the user who created this campaign if available.
          example: John Doe
        updatedBy:
          type: string
          description: Name of the user who last updated this campaign if available.
          example: Jane Doe
        templateId:
          type: integer
          description: The ID of the Campaign Template this Campaign was created from.
          example: 3
        frontendState:
          type: string
          description: The campaign state displayed in the Campaign Manager.
          enum:
          - expired
          - scheduled
          - running
          - disabled
          - archived
          - staged
          example: running
        storesImported:
          type: boolean
          description: Indicates whether the linked stores were imported via a CSV file.
          example: true
        valueMapsIds:
          type: array
          description: A list of value map IDs for the campaign.
          items:
            type: integer
          example:
          - 100
          - 215
        experimentId:
          type: integer
          description: The 

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/talon-one/refs/heads/main/openapi/talon-one-experiments-api-openapi.yml