Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Intelligems External Experiences API
version: v25-10-beta
description: Programmatic access to manage Intelligems A/B tests, personalizations, and experiences, to define custom events, and to pull experiment and sitewide analytics for a Shopify store. Authenticate with an API key in the `intelligems-access-token` header.
contact:
name: Intelligems
url: https://docs.intelligems.io/developer-resources/external-api
servers:
- url: https://api.intelligems.io
description: Production
security:
- accessToken: []
tags:
- name: Experiences
description: Create, read, update, and control A/B tests and personalizations.
paths:
/v25-10-beta/experiences-list:
get:
tags:
- Experiences
description: Retrieve a paginated list of experiences (experiments and personalizations), optionally filtered by category, status and module.
parameters:
- in: query
name: category
schema:
description: Filter by experience category. Omit to return all categories.
type: string
enum:
- experiment
- personalization
description: Filter by experience category. Omit to return all categories.
- in: query
name: module
schema:
description: Filter by modification type / module (content, checkout, postPurchase, pricing, merchandising, shipping). Category-agnostic. Omit to return all modules.
type: string
enum:
- content
- checkout
- postPurchase
- pricing
- merchandising
- shipping
description: Filter by modification type / module (content, checkout, postPurchase, pricing, merchandising, shipping). Category-agnostic. Omit to return all modules.
- in: query
name: status
schema:
description: Filter by lifecycle status. Omit to return all statuses.
type: string
enum:
- pending
- started
- ended
- paused
description: Filter by lifecycle status. Omit to return all statuses.
- in: query
name: limit
schema:
description: Maximum number of experiences per page.
type: integer
minimum: 1
maximum: 9007199254740991
description: Maximum number of experiences per page.
- in: query
name: page
schema:
description: 1-based page number for paginated results.
type: integer
minimum: 1
maximum: 9007199254740991
description: 1-based page number for paginated results.
responses:
'200':
description: OK
headers:
access-control-allow-origin:
schema:
type: string
description: CORS allow-origin header.
access-control-allow-credentials:
schema:
type: string
description: CORS allow-credentials header.
content-type:
schema:
type: string
description: Response content type.
Timing-Allow-Origin:
schema:
type: string
description: Allowed origin for Timing headers.
content:
application/json:
schema:
type: object
properties:
experiencesList:
type: array
items:
type: object
properties:
archivedAtTs:
description: Server-generated. Read-only. Unix timestamp in milliseconds. Null if not archived.
anyOf:
- type: number
- type: 'null'
audience:
description: Visitor segmentation rules. Null means all visitors are eligible.
anyOf:
- type: object
properties:
id:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
description: Server-generated. Read-only.
experienceId:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
description: References the parent experience.
enabled:
type: boolean
description: When false, audience rules are ignored and all visitors are eligible.
excludeCurrency:
type: object
properties:
exclude:
type: boolean
description: Whether currency/geo-based exclusion is active.
currency:
anyOf:
- type: string
- type: 'null'
description: ISO 4217 currency code to include. Null disables currency-based exclusion.
country:
description: ISO country code to include visitors from.
type: string
region:
description: Region or state code to include visitors from.
type: string
city:
description: City name to include visitors from.
type: string
required:
- exclude
- currency
additionalProperties: false
description: Currency and geo-based visitor exclusion configuration.
wholesale:
type: boolean
description: Controls whether wholesale (B2B) customers are included in or excluded from the experience.
audienceType:
description: 'Complexity level of the targeting rules: common (prebuilt), custom (simple), or advanced (full expression trees).'
type: string
enum:
- common
- custom
- advanced
elseAction:
anyOf:
- type: string
enum:
- experienceInclude
- experienceExclude
- experienceUnassigned
- assignVariation
- randomVariation
- leaveUnassigned
- type: 'null'
description: 'Fallback for visitors matching no filter: ''randomVariation'' assigns randomly across variations (most common), ''assignVariation'' forces a specific variation (set elseVariationId), ''experienceExclude'' removes them from the experience entirely, ''leaveUnassigned'' skips assignment.'
elseVariationId:
description: Variation to force-assign when elseAction is 'assignVariation'. Typically set to the control variation to default non-targeted visitors to baseline.
anyOf:
- type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
- type: 'null'
elseExcludeFromAnalytics:
default: false
description: When true, visitors who match no filter are tracked but excluded from analytics calculations.
type: boolean
filters:
default: []
description: Ordered filter rules evaluated from lowest priority value first (0-indexed). First matching filter determines visitor treatment.
type: array
items:
type: object
properties:
id:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
description: Server-generated. Read-only.
priority:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: Evaluation order. 0-indexed. Filters with lower values are evaluated first.
action:
anyOf:
- type: string
enum:
- experienceInclude
- experienceExclude
- experienceUnassigned
- assignVariation
- randomVariation
- leaveUnassigned
- type: 'null'
description: 'What happens when a visitor matches this filter: ''assignVariation'' forces a specific variation (set variationId), ''experienceExclude'' removes from the experience, ''randomVariation'' assigns randomly.'
filterType:
type: string
enum:
- utm
- url
- urlPath
- device
- visitor
- jsExpression
- trafficSource
- country
- referrer
- cookie
- klaviyo
- landingPage
description: Category of targeting rule (e.g., UTM parameters, device type, visitor type).
expression:
anyOf:
- type: array
items:
type: object
properties:
query:
type: object
properties:
key:
type: string
description: Visitor attribute or parameter name to match (e.g., 'utm_source', 'device_type').
value:
type: string
description: 'Expected value to compare against the visitor''s actual value for this key. Constrained by `type`: when type is ''device'' this must be exactly ''any'', ''mobile'', or ''desktop''.'
filter:
description: Comparison operator (e.g., equals, contains, startsWith).
anyOf:
- type: string
enum:
- equals
- contains
- startsWith
- endsWith
- doesNotEqual
- doesNotContain
- doesNotStartWith
- doesNotEndWith
- isNull
- isNotNull
- regex
- type: 'null'
type:
default: utm
description: Category of the parameter being matched. Determines which keys are valid. Use 'device' for device targeting (pair with key 'device', filter 'equals', and value 'any' | 'mobile' | 'desktop'); 'utm'/'url' for query params; 'urlPath' for the path; and 'country', 'visitor', 'trafficSource', 'referrer', 'cookie', 'landingPage', 'klaviyo', or 'jsExpression' for the rest.
type: string
enum:
- utm
- url
- urlPath
- device
- visitor
- jsExpression
- trafficSource
- country
- referrer
- cookie
- klaviyo
- landingPage
required:
- key
- value
- type
additionalProperties: false
operator:
type: string
enum:
- and
- or
- start_paren
- end_paren
additionalProperties: false
- type: 'null'
description: Boolean expression tree. Each node has either a 'query' (leaf condition) or 'operator' (logical combinator), not both.
expressionType:
description: Whether this uses prebuilt common rules or custom expression logic.
anyOf:
- type: string
enum:
- common
- custom
- type: 'null'
variationId:
description: Variation to assign when action is 'assignVariation'. References a variation in the parent experience.
anyOf:
- type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
- type: 'null'
excludeFromAnalytics:
default: false
description: When true, visitors matching this filter are excluded from analytics even if included in the experience.
type: boolean
required:
- id
- priority
- action
- filterType
- excludeFromAnalytics
additionalProperties: false
evaluationFrequency:
description: How often (in seconds) to re-evaluate audience rules for a returning visitor. Controls targeting freshness.
anyOf:
- type: number
- type: 'null'
required:
- id
- experienceId
- enabled
- excludeCurrency
- wholesale
- elseAction
- elseExcludeFromAnalytics
- filters
additionalProperties: false
- type: 'null'
category:
type: string
enum:
- experiment
- personalization
description: Distinguishes A/B experiments (statistical testing) from personalization rules (deterministic targeting).
createdAtTs:
type: number
description: Server-generated. Read-only. Unix timestamp in milliseconds.
currency:
description: Currency settings for price display and analytics calculations. Null inherits store default.
anyOf:
- type: object
properties:
code:
default: USD
description: ISO 4217 currency code used for analytics and price calculations.
type: string
country:
description: ISO country code for locale-specific formatting.
type: string
options:
description: Additional locale-specific formatting options.
symbol:
default: $
description: Display symbol prepended to amounts (e.g., '$', '€').
type: string
suffix:
description: Text appended after amounts for postfix currencies (e.g., 'kr' in '100 kr').
type: string
required:
- code
- symbol
additionalProperties: false
- type: 'null'
description:
description: Internal note explaining what this experience tests.
anyOf:
- type: string
- type: 'null'
devicePreview:
description: Device and path configuration for the preview iframe.
anyOf:
- type: object
properties:
device:
default: desktop
description: Viewport to simulate when rendering the preview.
type: string
enum:
- any
- mobile
- desktop
path:
default: /
description: Storefront URL path to load in the preview (e.g., '/products/example').
type: string
required:
- device
- path
additionalProperties: false
description: Device and path configuration for previewing the experience.
- type: 'null'
endedAtTs:
anyOf:
- type: number
- type: 'null'
description: Server-generated. Read-only. Unix timestamp in milliseconds. Null if still active.
experienceActions:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
experienceId:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
action:
type: string
enum:
- start
- pause
- end
- delete
- reset
actionTs:
type: number
performedBy:
description: Email of the user who triggered this lifecycle event. Resolved from History records by matching action type and timestamp within a 5-minute window. Null if no matching History record is found, or if the record has no associated user. Currently only populated by GET /experiences/{experienceId}; list endpoints return null.
anyOf:
- type: string
- type: 'null'
required:
- id
- experienceId
- action
- actionTs
additionalProperties: false
description: Server-generated. Read-only. Lifecycle state transitions (start, pause, end, delete, reset) recorded for this experience. On GET /experiences/{experienceId}, each entry includes a `performedBy` field with the triggering user's email, resolved from History records (may be null if unresolvable). Distinct from the list endpoint's raw `history` field, which contains broader user-action records.
experiencePageTargeting:
default: []
description: Rules controlling where this experience activates. Primarily URL/path rules, but the same expression format also supports 'device', 'country', 'visitor', 'trafficSource', 'referrer', and 'cookie'. Empty means all pages. To target the whole experience at a device (e.g. desktop only), prefer an `audience` filter over a page-targeting rule.
type: array
items:
type: object
properties:
id:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
filter:
anyOf:
- type: string
enum:
- equals
- contains
- startsWith
- endsWith
- doesNotEqual
- doesNotContain
- doesNotStartWith
- doesNotEndWith
- isNull
- isNotNull
- regex
- type: 'null'
filterType:
default: url
type: string
enum:
- utm
- url
- device
- visitor
- jsExpression
- trafficSource
- country
- referrer
- cookie
value:
type: string
order:
type: number
expression:
anyOf:
- type: array
items:
type: object
properties:
query:
type: object
properties:
key:
type: string
description: Visitor attribute or parameter name to match (e.g., 'utm_source', 'device_type').
value:
type: string
description: 'Expected value to compare against the visitor''s actual value for this key. Constrained by `type`: when type is ''device'' this must be exactly ''any'', ''mobile'', or ''desktop''.'
filter:
description: Comparison operator (e.g., equals, contains, startsWith).
anyOf:
- type: string
enum:
- equals
- contains
- startsWith
- endsWith
- doesNotEqual
- doesNotContain
- doesNotStartWith
- doesNotEndWith
- isNull
- isNotNull
- regex
- type: 'null'
type:
default: utm
description: Category of the parameter being matched. Determines which keys are valid. Use 'device' for device targeting (pair with key 'device', filter 'equals', and value 'any' | 'mobile' | 'desktop'); 'utm'/'url' for query params; 'urlPath' for the path; and 'country', 'visitor', 'trafficSource', 'referrer', 'cookie', 'landingPage', 'klaviyo', or 'jsExpression' for the rest.
type: string
enum:
- utm
- url
- urlPath
- device
- visitor
- jsExpression
- trafficSource
- country
- referrer
- cookie
- klaviyo
- landingPage
required:
- key
- value
- type
additionalProperties: false
operator:
type: string
enum:
- and
- or
- start_paren
- end_paren
additionalProperties: false
- type: 'null'
experienceId:
type: string
format: uuid
pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
required:
- id
- filterType
- value
- order
additionalProperties: false
experienceProductTargeting:
default: []
description: Product attribute rules controlling which products this experience applies to. Empty means all products.
type: array
items:
type: object
properties:
id:
type: string
# --- truncated at 32 KB (1566 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/intelligems/refs/heads/main/openapi/intelligems-experiences-api-openapi.yml