RESTful entry point to the Monetate decision engine. A client POSTs a batch of context events, page events and record events for a session and receives back the actions (experiences) the engine decided to serve — usable from a server, a browser, a mobile app, a single-page app, or non-web channels such as in-store displays, kiosks and SMS. Regional endpoints are available alongside the default host.
swagger: "2.0"
info:
description: |
The Monetate Engine API allows clients to request decisions (in terms of actions) when an event occurs.
version: "1.0.0"
title: Monetate Engine API
termsOfService: http://monetate.com/terms/
contact:
name: api@monetate.com
host: engine.monetate.net
basePath: /api/engine/v1
schemes:
- https
# ---------------------------------------------------
# Endpoints
# ---------------------------------------------------
paths:
/decide/{retailerShortname}:
post:
tags:
- Decision
summary: Request Decisions
description: |
Monetate Decision API
operationId: decide
consumes:
- application/json
produces:
- application/json
parameters:
- name: retailerShortname
in: path
description: Shortname of the retailer.
required: true
type: string
- in: body
name: body
description: The request containing the events requiring decisioning.
required: true
schema:
$ref: "#/definitions/HttpRequestBody"
responses:
"200":
description: The request was succesful and the payload will include valid actions.
schema:
$ref: "#/definitions/HttpResponseBody"
"400":
description: Invalid request.
The request was either malformated (did not follow this specification), or the data sent was invalid.
schema:
$ref: "#/definitions/HttpResponseBody"
definitions:
# ---------------------------------------------------
# Events
# ---------------------------------------------------
Event:
type: object
required:
- eventType
properties:
eventType:
type: string
description: A value that identifies the type of event.
discriminator: eventType
description: |
Parent class for all events, which dictates required fields.
example: |
{
"eventType": "Event"
}
monetate:decision:ServerSideRequest:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- requestId
properties:
account:
type: string
description: The account ID. Deprecated. Use HttpRequestBody channel.
domain:
type: string
description: The account domain (e.g., fifthlevelfashion.com). Deprecated. Use HttpRequestBody channel.
instance:
type: string
description: The type of instance (e.g., p for production). Deprecated. Use HttpRequestBody channel.
requestId:
type: string
description: A user-defined requestId that will be associated with the decision request.
description: |
This is a server-side request for decisioning.
Deprecated. Use [monetate:decision:DecisionRequest](https://developer.monetate.com/engine-api/monetate-decision-decisionrequest).
example: |
{
"eventType": "monetate:decision:ServerSideRequest",
"requestId": "12345"
}
monetate:decision:DecisionRequest:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- requestId
properties:
account:
type: string
description: The account ID. Deprecated. Use HttpRequestBody channel.
domain:
type: string
description: The account domain (e.g., fifthlevelfashion.com). Deprecated. Use HttpRequestBody channel.
instance:
type: string
description: The type of instance (e.g., p for production). Deprecated. Use HttpRequestBody channel.
requestId:
type: string
description: A user-defined requestId that will be associated with the decision request.
manageImpressions:
type: boolean
description: Deprecated. Use action-level managed impressions instead.
includeReporting:
type: boolean
description: If includeReporting is set to true, each action returned in the response will include
an impressionReporting attribute, which contains reporting information about the
experience and variant associated with the action.
filters:
description: Deprecated. Use "slots" instead.
type: array
items:
type: string
slots:
description: Slot names to filter against. Only matching actions will be evaluated.
type: array
items:
type: string
actionTypes:
description: Action types to filter against. Only matching actions will be evaluated.
type: array
items:
type: string
description: |
Used to make a request for decisioning.
example: |
{
"eventType": "monetate:decision:DecisionRequest",
"requestId": "12345",
}
monetate:decision:PersonalizationFlagRequest:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- requestId
properties:
requestId:
type: string
description: A user-defined requestId that will be associated with the personalization flag request.
account:
type: string
description: The account ID. Deprecated. Use HttpRequestBody channel.
domain:
type: string
description: The account domain (e.g., fifthlevelfashion.com). Deprecated. Use HttpRequestBody channel.
instance:
type: string
description: The type of instance (e.g., p for production). Deprecated. Use HttpRequestBody channel.
actionTypes:
description: Action types to filter against. Only matching actions will be evaluated.
type: array
items:
type: string
description: |
Used to make a request for personalization flags.
example: |
{
"eventType": "monetate:decision:PersonalizationFlagRequest",
"requestId": "12345"
}
monetate:record:PageEvents:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- pageEvents
properties:
pageEvents:
description: An array of page events.
type: array
items:
type: string
description: |
Used to record when one or more page events have occurred.
Each string in the array should be a key that was defined in the Monetate UI when the page event was created.
example: |
{
"eventType": "monetate:record:PageEvents",
"pageEvents": ["myEvent"]
}
monetate:record:Impressions:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- impressionIds
properties:
impressionIds:
description: A list of impression identifier strings.
type: array
items:
type: string
description:
Used to record impressions. Each impressionId is a token that is
associated with an action from an earlier request.
example: |
{
"eventType": "monetate:record:Impressions",
"impressionIds": [
"3.MS4xLjE1MTQ4MDg5MDAuMDAwMDAw"
]
}
EndcapEvent:
type: object
properties:
actionId:
description: The action ID associated with the endcap event.
type: string
products:
type: array
description: The list of products and product-specific details.
items:
$ref: '#/definitions/EndcapProduct'
required:
- actionId
- products
description: |
Represents products and actionId interacted with.
example: |
{
"actionId": "1234567",
"products": [
{
"productId": "product72",
"sku": "product72-large-green",
"slotIndex": 0,
"recsetId": 4589,
}
]
}
monetate:record:EndcapClicks:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- endcapClicks
properties:
endcapClicks:
type: array
description: Array of endcap product clicks to be recorded.
items:
$ref: '#/definitions/EndcapEvent'
description:
Used to record endcap clicks. A click is recorded for each product sent.
Deprecated. Use [monetate:record:RecClicks](https://developer.monetate.com/engine-api/monetate-record-RecClicks).
example: |
{
"eventType": "monetate:record:EndcapClicks",
"endcapClicks": [
{
"actionId": "1234567",
"products": [
{
"productId": "product72",
"sku": "product72-large-green",
"slotIndex": 0,
"recsetId": 4589,
}
]
}
]
}
monetate:record:EndcapImpressions:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- endcapImpressions
properties:
endcapImpressions:
type: array
description: Array of endcap product impressions to be recorded.
items:
$ref: '#/definitions/EndcapEvent'
description:
Used to record endcap impressions. An impression is recorded for each product sent.
Deprecated. Use [monetate:record:RecImpressions](https://developer.monetate.com/engine-api/monetate-record-recimpressions).
example: |
{
"eventType": "monetate:record:EndcapImpressions",
"endcapImpressions": [
{
"actionId": "1234567",
"products": [
{
"productId": "product72",
"sku": "product72-large-green",
"slotIndex": 0,
"recsetId": 4589,
},
{
"productId": "product43",
"sku": "product43-medium-striped"
"slotIndex": 1,
"recsetId": 4588,
},
{
"productId": "product57"
"slotIndex": 2,
"recsetId": 4589,
}
]
}
]
}
monetate:record:RecClicks:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- recClicks
properties:
recClicks:
type: array
description: Array of rec tokens to be recorded.
items:
type: string
description:
Used to record rec clicks. A click is recorded for each token sent.
example: |
{
"eventType": "monetate:record:RecClicks",
"recClicks": ["rt.1.xxx", "rt.1.yyy"]
}
monetate:record:RecImpressions:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- recImpressions
properties:
recImpressions:
type: array
description: Array of rec tokens to be recorded.
items:
type: string
description:
Used to record rec impressions. An impression is recorded for each token sent.
example: |
{
"eventType": "monetate:record:RecImpressions",
"recImpressions": ["rt.1.xxx", "rt.1.yyy"]
}
monetate:context:CustomVariables:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- customVariables
properties:
customVariables:
description: An array of custom variables.
type: array
items:
$ref: "#/definitions/CustomVariables"
description: |
Used to pass in values of custom variables, which can be used for targeting.
example: |
{
"eventType": "monetate:context:CustomVariables",
"customVariables": [{
"variable": "favoriteTeam",
"value": "Blue Hens"
}]
}
CustomVariables:
type: object
required:
- variable
- value
properties:
variable:
type: string
description: The name of the custom variable.
value:
# nullable: true
description: The value of the custom variable.
description: |
A custom variable and its value. Value can be any type, including null.
example: |
{
"variable": "genderIfKnown",
"value": null
}
monetate:context:UserAgent:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- userAgent
properties:
userAgent:
type: string
description: The user-agent header value.
description: |
This is the user-agent header from the client originating the request.
example: |
{
"eventType": "monetate:context:UserAgent",
"userAgent": "Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en) AppleWebKit/522.11 (KHTML, like Gecko) Safari/3.0.2"
}
monetate:context:Language:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- language
properties:
language:
type: string
description: A language tag, in the format used in the Accept-Language HTTP header.
description: |
The visitor's language preference, if known. Used for experience targeting.
example: |
{
"eventType": "monetate:context:Language",
"language": "en-US"
}
monetate:context:IpAddress:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- ipAddress
properties:
ipAddress:
type: string
description: The IP address.
description: |
This is the IP address of the visitor.
example: |
{
"eventType": "monetate:context:IpAddress",
"ipAddress": "198.51.100.0"
}
monetate:context:PageView:
allOf:
- $ref: '#/definitions/Event'
- type: object
properties:
pageType:
type: string
description: The type of page viewed (e.g., "index" or "home" or "pdp").
path:
type: string
description: |
The path portion of the URL for the page viewed.
Must be included if "url" property is not included.
url:
type: string
description: |
The complete URL for the page viewed.
Must be included if "path" property is not included.
categories:
description: |
Categories to filter against.
Only matching actions will be evaluated.
type: array
items:
type: string
breadcrumbs:
description: |
Breadcrumbs to filter against.
Only matching actions will be evaluated.
type: array
items:
type: string
description: |
Used to communicate a page view.
example: |
{
"eventType": "monetate:context:PageView",
"url": "http://www.monetate.com/index.html",
"pageType": "home",
"categories": ["category"],
"breadcrumbs": ["breadcrumb"]
}
monetate:context:Cart:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- cartLines
properties:
cartLines:
description: The cart lines that comprise the cart. Unlike the
monetate:context:AddToCart event, which adds items
to an existing cart, this
cart in its entirety.
type: array
items:
$ref: "#/definitions/CartLine"
description: |
Used to communicate the contents of the cart. Must include line items.
example: |
{
"eventType": "monetate:context:Cart",
"cartLines": [{
"sku": "SKU1",
"pid": "PID1",
"quantity": 2,
"currency": "USD",
"value": "24.00"
}]
}
monetate:context:AddToCart:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- cartLines
properties:
cartLines:
description: The cart lines that should be added to the cart.
Unlike the monetate:context:Cart event, which
represent the current cart in its entirety, this
event only adds items to an existing cart.
type: array
items:
$ref: "#/definitions/CartLine"
description: |
Used to communicate the contents of the cart. Must include line items.
example: |
{
"eventType": "monetate:context:AddToCart",
"cartLines": [{
"sku": "SKU1",
"pid": "PID1",
"quantity": 2,
"currency": "USD",
"value": "24.00"
}]
}
CartLine:
type: object
required:
- sku
- pid
- quantity
- currency
- value
properties:
sku:
type: string
description: The unique identifier for the product.
pid:
type: string
description: The parent identifier for a related set of SKUs.
quantity:
type: integer
description: The number of products matching this SKU that are in the cart.
currency:
type: string
description: The currency of the item value.
value:
type: string
description: The total value of the items.
pattern: '^(\d{1,9})?(\.\d{1,2})?$'
description: |
Represents an item in a cart.
example: |
{
"sku": "SKU1",
"pid": "PID1"
"quantity": 2,
"currency": "USD",
"value": "24.00"
}
monetate:context:Purchase:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- purchaseId
- purchaseLines
properties:
account:
type: string
description: The account ID. Deprecated. Use HttpRequestBody channel.
domain:
type: string
description: The account domain (e.g., fifthlevelfashion.com). Deprecated. Use HttpRequestBody channel.
instance:
type: string
description: The type of instance (e.g., p for production). Deprecated. Use HttpRequestBody channel.
purchaseId:
type: string
description: Unique identifier for the purchase.
purchaseLines:
description: The purchase lines defining the contents of the purchase.
type: array
items:
$ref: "#/definitions/PurchaseLine"
description: |
Used to communicate a purchase. Must include line items.
example: |
{
"eventType": "monetate:context:Purchase",
"purchaseId": "1b2c3d",
"purchaseLines": [{
"sku": "SKU1",
"pid": "PID1"
"quantity": 2,
"currency": "USD",
"value": "24.00"
}]
}
PurchaseLine:
type: object
required:
- sku
- pid
- quantity
- currency
- value
properties:
sku:
type: string
description: The unique identifier for the product.
pid:
type: string
description: The parent identifier for a related set of SKUs.
quantity:
type: integer
description: The number of items purchased.
currency:
type: string
description: The currency of the purchase value.
value:
type: string
description: The total value of the items.
pattern: '^(\d{1,9})?(\.\d{1,2})?$'
description: |
Represents an item in a purchase.
example: |
{
"sku": "SKU1",
"pid": "PID1"
"quantity": 2,
"currency": "USD",
"value": "24.00"
}
monetate:context:Metadata:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- metadata
properties:
metadata:
type: object
description: Arbitrary additional custom data to be sent for action.
description: |
Used to communicate additional metadata that might be needed for actioning.
example: |
{
"eventType": "monetate:context:Metadata",
"metadata": {
"language": "en-GB"
}
}
monetate:context:ProductView:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- products
properties:
products:
type: array
description: The list of products viewed on a product detail page.
items:
type: string
description: |
Used to communicate product views.
Deprecated. Use [monetate:context:ProductDetailView](https://developer.monetate.com/engine-api/monetate-context-productdetailview).
example: |
{
"eventType": "monetate:context:ProductView",
"products": ["product72", "product43", "product42"]
}
monetate:context:ProductDetailView:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- products
properties:
products:
type: array
description: The list of products and product-specific details being viewed.
items:
$ref: '#/definitions/Product'
description: |
Used to communicate product views.
example: |
{
"eventType": "monetate:context:ProductDetailView",
"products": [
{
"productId": "product72",
"sku": "product72-large-green",
},
{
"productId": "product43",
"sku": "product43-medium-striped"
},
{
"productId": "product57"
}
]
}
monetate:context:ContentView:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- items
properties:
items:
type: array
description: The list of contents viewed.
items:
$ref: '#/definitions/Content'
description: |
Used to communicate content views.
example: |
{
"eventType": "monetate:context:ContentView",
"items": [
{
"contentType": "article",
"id": "content72",
"itemGroupId": "content72"
},
{
"contentType": "video",
"id": "content43",
"itemGroupId": "content43"
}
]
}
Product:
type: object
properties:
productId:
type: string
description: The product ID.
sku:
type: string
description: The unique identifier for the product.
required:
- productId
description: |
Represents an item.
example: |
{
"productId": "product72",
"sku": "product72-large-green",
}
Content:
type: object
properties:
contentType:
type: string
description: A value that identifies the type of content.
id:
type: string
description: The unique identifier for the content item.
itemGroupId:
type: string
description: An optional identifier that links different versions of the same content.
required:
- contentType
- id
description: |
Represents an item.
example: |
{
"contentType": "content11-image",
"id": "content11",
"itemGroupId": "content11"
}
EndcapProduct:
type: object
properties:
productId:
type: string
description: The product ID.
sku:
type: string
description: The unique identifier for the product.
slotIndex:
type: integer
description: The index of the recommendation in the list of recommended products.
recsetId:
type: integer
description: The ID of the recommendation set that recommended this item.
required:
- productId
description: |
Represents an item that was recommended. The slotIndex/recsetId are used for reporting and for improving models.
example: |
{
"productId": "product72",
"sku": "product72-large-green",
"slotIndex": 0,
"recsetId": 4589,
}
monetate:context:ProductThumbnailView:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- products
properties:
products:
type: array
description: The list of products thumbnails viewed on a product listing page.
items:
type: string
description: |
Used to communicate product thumbnail views.
example: |
{
"eventType": "monetate:context:ProductThumbnailView",
"products": ["product72", "product43", "product42"]
}
monetate:context:ProductThumbnailSkuView:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- productSkus
properties:
productSkus:
type: array
description: The list of SKU-specific details being viewed.
items:
type: string
description: |
Used to communicate product SKU thumbnail views.
example: |
{
"eventType": "monetate:context:ProductThumbnailSkuView",
"productSkus": ["product72_a", "product43_b", "product42_c"]
}
monetate:context:SearchView:
allOf:
- $ref: '#/definitions/Event'
- type: object
properties:
searchTerm:
type: string
description: |
What the user searched for. This can be something such as "black shoes", a category such as "clothing", or a product ID such as "123abc". Defaults to an empty string.
searchType:
type: string
description: |
The type of search. Should be "site" for normal textual site searches. Should be "category" when searching by
category (e.g., category links on home page). Defaults to "site".
searchTermType:
type: string
description: |
The type for the search term. Should be "text" for searches by category and normal site searches. Should be "product_id" when searching by product ID. Defaults to "text".
searchActionId:
type: string
description: |
The ID of the action, if this search was provided by a Monetate search action. Defaults to "0". Should only be
passed if search is being provided by Monetate.
NOTE: In the future, search results may be provided by the track API. In such a case, this parameter should become unnecessary.
description: |
Used to communicate search events from the client's own search functionality for Monetate to record and use for the [**On-site search terms**](https://docs.monetate.com/docs/configure-on-site-search-terms-target) WHO target. Use the [Personalized Search API](https://developer.monetate.com/personalized-search) for Monetate's search feature.
example: |
{
"eventType": "monetate:context:SearchView",
"searchTerm":"foo",
"searchType":"site",
"searchTermType":"text",
"searchActionId":"1"
}
monetate:context:Referrer:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- referrer
properties:
referrer:
type: string
description: The referring URL.
description: |
This is the referring URL of the visitor.
example: |
{
"eventType": "monetate:context:Referrer",
"referrer": "http://www.example.com"
}
monetate:context:Coordinates:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- latitude
- longitude
properties:
latitude:
type: string
description: Device latitude.
longitude:
type: string
description: Device longitude.
description: |
This is the latitude and longitude provide by the device.
example: |
{
"eventType": "monetate:context:Coordinates",
"latitude": "49.566667",
"longitude": "10.883333"
monetate:context:ScreenSize:
allOf:
- $ref: '#/definitions/Event'
- type: object
required:
- height
- width
properties:
height:
type: integer
description: Screen height in pixels.
width:
type: integer
description: Screen width in pixels.
description: |
This visitor's screen size, height, and width in pixels.
example: |
{
"eventType": "monetate:context:ScreenSize",
"height": 762,
"width": 1024
}
# ---------------------------------------------------
# Actions
# ---------------------------------------------------
Action:
type: object
required:
- actionType
properties:
actionType:
type: string
description: The value that identifies the type of action.
impressionId:
type: string
description: A token to be used for recording managed impressions.
impressionReporting:
description: This array identifies the experience and variant associated with the action.
It's included for each action if the "includeReporting" option
is set to true on the DecisionRequest event.
type: array
items:
$ref: "#/definitions/ImpressionReporting"
discriminator: actionType
description: |
Parent class for all actions, which dictates required field.
example: |
{
"actionType": "Action"
}
ImpressionReporting:
type: object
required:
- experience_id
- experience_label
- experience_name
- variant_label
- is_control
- control_allocation
- experience_type
- has_targets
- tags
properties:
experience_id:
type: integer
description: The unique identifier for the experience associated with the action.
experience_label:
type: string
description: A static reporting label, set at experience activation, based on experience name.
experience_name:
type: string
description: The title of the experience associated with the action.
variant_label:
type: string
description: The name of the variant associated with the action.
is_control:
type: boolean
description: Whether the user was assigned to a control group for this action.
control_allocation:
# nullable: true
description: A value from 0.0 to 1.0 representing the percentage of traffic allocated to the control group.
experience_type:
type: string
description: The type of experience (e.g., "100% Experience" or "Majority Fit").
has_targets:
type: boolean
description: Indicates whether there are any WHO targets associated with the experience.
tags:
type: array
items:
type: string
description: An array containing the tag names associated to the experience.
description: |
Identifies the experience and variant associated with the action.
example: |
{
"experience_id": 1,
"experience_label": "Homepage Hero Replacement"
"variant_label": "New Arrivals",
"is_control": False,
"control_allocation": 0.50,
"experience_type": "Standard Test",
"has_targets": False,
"tags": ["Default"]
}
monetate:action:OpenAction:
allOf:
- $ref: '#/definitions/Action'
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/monetate/refs/heads/main/openapi/monetate-engine-api-openapi.yml