TrueLoyal
v1.0.0https://mcp.trueloyal.comBeta. Search, analyze and manage the posts, assets and loyalty programs of your teams from AI assistants such as Claude. See Connecting AI Assistants to connect one.
Add to your MCP client configuration:
Teams
list_teams
read-onlyidempotentLists the teams you belong to that enabled access for AI assistants (MCP). Every other tool takes the ID of one of these teams.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_teams",
"arguments": {}
}
}const result = await client.callTool("list_teams", {});result = await session.call_tool("list_teams", arguments={}){
"content": [
{
"type": "text",
"text": "..."
}
]
}Boards
list_tints
read-onlyidempotentLists the boards (also called tints) of a team that you have access to. Posts are collected into boards by their social feeds.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_tints",
"arguments": {
"team_id": 0
}
}
}const result = await client.callTool("list_tints", {
"team_id": 0
});result = await session.call_tool("list_tints", arguments={
"team_id": 0
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}list_saved_filters
read-onlyidempotentLists the saved filters of a board. Pass a saved filter to search_posts or aggregate_posts (with the tint_id of its board) to use it.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
tint_idintegerrequiredargumentThe ID of the board, as returned by list_tints.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_saved_filters",
"arguments": {
"team_id": 0,
"tint_id": 0
}
}
}const result = await client.callTool("list_saved_filters", {
"team_id": 0,
"tint_id": 0
});result = await session.call_tool("list_saved_filters", arguments={
"team_id": 0,
"tint_id": 0
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}Accounts
list_accounts
read-onlyidempotentLists the social and integration accounts connected to a team (for example the brand's Instagram or TikTok account) that you have access to.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_accounts",
"arguments": {
"team_id": 0
}
}
}const result = await client.callTool("list_accounts", {
"team_id": 0
});result = await session.call_tool("list_accounts", arguments={
"team_id": 0
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}Posts
search_posts
read-onlyidempotentSearches the posts of a team, newest first by default. Returns up to 100 posts per page and the total number of posts that match, and can page through the first 10000 of them. Teams can have millions of posts, so read a sample of them to summarize or find themes, and use aggregate_posts instead to count posts, rank them or compute averages.
Body
team_idintegerrequiredThe ID of the team, as returned by list_teams.
qstringFull-text search of the text, title, author and OCR text of the posts.
usernamestringOnly posts by these authors (usernames without the @).
networkstringOnly posts from these networks, for example instagram_business, tiktok, facebook or review_trackers. One of: facebook, twitter, youtube, pinterest, rss, linkedin, tumblr, custom, flickr, google_news, hootsuite, public_post, slack, spark, sms, review_trackers, instagram_business, externally_sourced_posts_account, tiktok, form_submission, email, mission, threads, creator_iq, tiktok_business.
tint_idstringOnly posts on these boards.
social_feed_idstringOnly posts collected by these social feeds, for example the feed of the posts that mention or tag the brand's account.
saved_filter_idstringApply this saved filter of the board given in tint_id.
statusstringOnly posts with these statuses: recurring, public, private, deleted, author_deleted, privacy_deleted, moderation_deleted, image_moderation_pending, image_moderation_deleted, image_moderation_failed, custom_post. Defaults to every status except author_deleted and privacy_deleted (posts removed by their author or for privacy reasons).
published_atobjectOnly posts published in this range, for example {"$gte": "2026-09-21T00:00:00Z", "$lt": "2026-09-28T00:00:00Z"}.
sentimentstringOnly posts with these text sentiments: positive, neutral, negative.
languagestringOnly posts in these languages (ISO 639-1 codes, for example en).
media_typestringOnly posts with these media types: image, video, carousel, text.
image_objectstringOnly posts whose images show at least one of these objects (for example person, cat, dog).
all_image_objectsstringOnly posts whose images show all of these objects, for example "person,cat".
tagstringOnly posts with at least one of these tags.
has_tagsbooleanOnly posts with (or without) tags.
has_objectsbooleanOnly posts with (or without) objects detected in their image.
has_ratingbooleanOnly posts with (or without) a rating, such as reviews.
has_authorbooleanOnly posts with (or without) the username or name of their author.
product_skustringOnly posts tagged with products with these SKUs.
ratingobjectOnly reviews with a rating in this range (1 to 5), for example {"$gte": "2", "$lte": "3"} for ratings between 2 and 3.
right_request_statusstringOnly posts whose most recent right request has these statuses: none, requested, pending, approved, soft_approved, declined, expired, deleted, missing, error, token_error. Rights were acquired when it's approved (or soft_approved), and none means rights were never requested.
right_request_status_expires_atobjectOnly posts whose approved right request expires in this range, for example {"$gt": ""} for rights that haven't expired.
highlightedbooleanOnly posts that are (or are not) highlighted.
pinnedbooleanOnly posts that are (or are not) pinned.
sortstringnewestoldestratingrelevanceDefaults to newest.
pageinteger>= 1Defaults to 1.
page_sizeinteger[1, 100]Defaults to 25.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "search_posts",
"arguments": {
"team_id": 0,
"q": "string",
"username": "string",
"network": "string",
"tint_id": "string",
"social_feed_id": "string",
"saved_filter_id": "string",
"status": "string",
"published_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"sentiment": "string",
"language": "string",
"media_type": "string",
"image_object": "string",
"all_image_objects": "string",
"tag": "string",
"has_tags": true,
"has_objects": true,
"has_rating": true,
"has_author": true,
"product_sku": "string",
"rating": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"right_request_status": "string",
"right_request_status_expires_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"highlighted": true,
"pinned": true,
"sort": "newest",
"page": 1,
"page_size": 1
}
}
}const result = await client.callTool("search_posts", {
"team_id": 0,
"q": "string",
"username": "string",
"network": "string",
"tint_id": "string",
"social_feed_id": "string",
"saved_filter_id": "string",
"status": "string",
"published_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"sentiment": "string",
"language": "string",
"media_type": "string",
"image_object": "string",
"all_image_objects": "string",
"tag": "string",
"has_tags": true,
"has_objects": true,
"has_rating": true,
"has_author": true,
"product_sku": "string",
"rating": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"right_request_status": "string",
"right_request_status_expires_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"highlighted": true,
"pinned": true,
"sort": "newest",
"page": 1,
"page_size": 1
});result = await session.call_tool("search_posts", arguments={
"team_id": 0,
"q": "string",
"username": "string",
"network": "string",
"tint_id": "string",
"social_feed_id": "string",
"saved_filter_id": "string",
"status": "string",
"published_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"sentiment": "string",
"language": "string",
"media_type": "string",
"image_object": "string",
"all_image_objects": "string",
"tag": "string",
"has_tags": true,
"has_objects": true,
"has_rating": true,
"has_author": true,
"product_sku": "string",
"rating": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"right_request_status": "string",
"right_request_status_expires_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"highlighted": true,
"pinned": true,
"sort": "newest",
"page": 1,
"page_size": 1
}){
"team_id": 0,
"q": "string",
"username": "string",
"network": "string",
"tint_id": "string",
"social_feed_id": "string",
"saved_filter_id": "string",
"status": "string",
"published_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"sentiment": "string",
"language": "string",
"media_type": "string",
"image_object": "string",
"all_image_objects": "string",
"tag": "string",
"has_tags": true,
"has_objects": true,
"has_rating": true,
"has_author": true,
"product_sku": "string",
"rating": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"right_request_status": "string",
"right_request_status_expires_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"highlighted": true,
"pinned": true,
"sort": "newest",
"page": 1,
"page_size": 1
}{
"content": [
{
"type": "text",
"text": "..."
}
]
}aggregate_posts
read-onlyidempotentCounts the posts of a team that match the filters (the same as search_posts), with the totals asked for, optionally grouped by up to three fields or publication times, each within the previous one, or clustered (for example the creators, by username). For example, average rating for the average rating of reviews, group by network to find which network generated the most content, by username for the top creators, by hour_of_day to see when people post the most, or by username, hashtag and sentiment for the sentiment of the hashtags each author uses the most.
Body
team_idintegerrequiredThe ID of the team, as returned by list_teams.
qstringFull-text search of the text, title, author and OCR text of the posts.
usernamestringOnly posts by these authors (usernames without the @).
networkstringOnly posts from these networks, for example instagram_business, tiktok, facebook or review_trackers. One of: facebook, twitter, youtube, pinterest, rss, linkedin, tumblr, custom, flickr, google_news, hootsuite, public_post, slack, spark, sms, review_trackers, instagram_business, externally_sourced_posts_account, tiktok, form_submission, email, mission, threads, creator_iq, tiktok_business.
tint_idstringOnly posts on these boards.
social_feed_idstringOnly posts collected by these social feeds, for example the feed of the posts that mention or tag the brand's account.
saved_filter_idstringApply this saved filter of the board given in tint_id.
statusstringOnly posts with these statuses: recurring, public, private, deleted, author_deleted, privacy_deleted, moderation_deleted, image_moderation_pending, image_moderation_deleted, image_moderation_failed, custom_post. Defaults to every status except author_deleted and privacy_deleted (posts removed by their author or for privacy reasons).
published_atobjectOnly posts published in this range, for example {"$gte": "2026-09-21T00:00:00Z", "$lt": "2026-09-28T00:00:00Z"}.
sentimentstringOnly posts with these text sentiments: positive, neutral, negative.
languagestringOnly posts in these languages (ISO 639-1 codes, for example en).
media_typestringOnly posts with these media types: image, video, carousel, text.
image_objectstringOnly posts whose images show at least one of these objects (for example person, cat, dog).
all_image_objectsstringOnly posts whose images show all of these objects, for example "person,cat".
tagstringOnly posts with at least one of these tags.
has_tagsbooleanOnly posts with (or without) tags.
has_objectsbooleanOnly posts with (or without) objects detected in their image.
has_ratingbooleanOnly posts with (or without) a rating, such as reviews.
has_authorbooleanOnly posts with (or without) the username or name of their author.
product_skustringOnly posts tagged with products with these SKUs.
ratingobjectOnly reviews with a rating in this range (1 to 5), for example {"$gte": "2", "$lte": "3"} for ratings between 2 and 3.
right_request_statusstringOnly posts whose most recent right request has these statuses: none, requested, pending, approved, soft_approved, declined, expired, deleted, missing, error, token_error. Rights were acquired when it's approved (or soft_approved), and none means rights were never requested.
right_request_status_expires_atobjectOnly posts whose approved right request expires in this range, for example {"$gt": ""} for rights that haven't expired.
highlightedbooleanOnly posts that are (or are not) highlighted.
pinnedbooleanOnly posts that are (or are not) pinned.
group_byArray<string>networkusernamesentimentlanguagemedia_typeimage_objecthashtagtagproduct_skuratingstatussocial_feed_idtint_idright_request_statushour_of_dayday_of_weekdayweekmonthGroup the posts by these fields, or by the hour of the day, day of the week, day, week or month they were published, each group within the previous one. For example ["network", "sentiment"].
sizeinteger[1, 100]The number of groups (the largest first) to return for the first field. Deeper fields return up to 10. Defaults to 10.
time_zonestringThe time zone of the time groups, for example America/New_York. Defaults to UTC.
sumArray<string>ratingnsfw_scoreaverageArray<string>ratingnsfw_scoreFor example rating for the average rating of reviews.
minArray<string>ratingnsfw_scorepublished_atThe smallest of these, for example published_at for the first post.
maxArray<string>ratingnsfw_scorepublished_atThe largest of these, for example published_at for the latest post.
distinctArray<string>networkusernamesentimentlanguagemedia_typeimage_objecthashtagtagproduct_skuratingstatussocial_feed_idtint_idright_request_statusCount the distinct values of these fields, for example hashtag.
clusterobjectInstead of grouping, cluster the values of a field into groups of similar values (k-means), by their number of documents and the totals asked for (sum, average, min, max, distinct) of each value. Clusters the 10000 values with the most documents, and returns the size of each cluster, its average count and totals, and a few of its values. For example {"by": "username", "into": 5} with distinct hashtag and max published_at, for personas of the creators.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "aggregate_posts",
"arguments": {
"team_id": 0,
"q": "string",
"username": "string",
"network": "string",
"tint_id": "string",
"social_feed_id": "string",
"saved_filter_id": "string",
"status": "string",
"published_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"sentiment": "string",
"language": "string",
"media_type": "string",
"image_object": "string",
"all_image_objects": "string",
"tag": "string",
"has_tags": true,
"has_objects": true,
"has_rating": true,
"has_author": true,
"product_sku": "string",
"rating": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"right_request_status": "string",
"right_request_status_expires_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"highlighted": true,
"pinned": true,
"group_by": [
"network"
],
"size": 1,
"time_zone": "string",
"sum": [
"rating"
],
"average": [
"rating"
],
"min": [
"rating"
],
"max": [
"rating"
],
"distinct": [
"network"
],
"cluster": {
"by": "network",
"into": 2
}
}
}
}const result = await client.callTool("aggregate_posts", {
"team_id": 0,
"q": "string",
"username": "string",
"network": "string",
"tint_id": "string",
"social_feed_id": "string",
"saved_filter_id": "string",
"status": "string",
"published_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"sentiment": "string",
"language": "string",
"media_type": "string",
"image_object": "string",
"all_image_objects": "string",
"tag": "string",
"has_tags": true,
"has_objects": true,
"has_rating": true,
"has_author": true,
"product_sku": "string",
"rating": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"right_request_status": "string",
"right_request_status_expires_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"highlighted": true,
"pinned": true,
"group_by": [
"network"
],
"size": 1,
"time_zone": "string",
"sum": [
"rating"
],
"average": [
"rating"
],
"min": [
"rating"
],
"max": [
"rating"
],
"distinct": [
"network"
],
"cluster": {
"by": "network",
"into": 2
}
});result = await session.call_tool("aggregate_posts", arguments={
"team_id": 0,
"q": "string",
"username": "string",
"network": "string",
"tint_id": "string",
"social_feed_id": "string",
"saved_filter_id": "string",
"status": "string",
"published_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"sentiment": "string",
"language": "string",
"media_type": "string",
"image_object": "string",
"all_image_objects": "string",
"tag": "string",
"has_tags": true,
"has_objects": true,
"has_rating": true,
"has_author": true,
"product_sku": "string",
"rating": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"right_request_status": "string",
"right_request_status_expires_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"highlighted": true,
"pinned": true,
"group_by": [
"network"
],
"size": 1,
"time_zone": "string",
"sum": [
"rating"
],
"average": [
"rating"
],
"min": [
"rating"
],
"max": [
"rating"
],
"distinct": [
"network"
],
"cluster": {
"by": "network",
"into": 2
}
}){
"team_id": 0,
"q": "string",
"username": "string",
"network": "string",
"tint_id": "string",
"social_feed_id": "string",
"saved_filter_id": "string",
"status": "string",
"published_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"sentiment": "string",
"language": "string",
"media_type": "string",
"image_object": "string",
"all_image_objects": "string",
"tag": "string",
"has_tags": true,
"has_objects": true,
"has_rating": true,
"has_author": true,
"product_sku": "string",
"rating": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"right_request_status": "string",
"right_request_status_expires_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"highlighted": true,
"pinned": true,
"group_by": [
"network"
],
"size": 1,
"time_zone": "string",
"sum": [
"rating"
],
"average": [
"rating"
],
"min": [
"rating"
],
"max": [
"rating"
],
"distinct": [
"network"
],
"cluster": {
"by": "network",
"into": 2
}
}{
"content": [
{
"type": "text",
"text": "..."
}
]
}get_post
read-onlyidempotentGets a post of a team, the same as search_posts returns it: its text, author, media, moderation, sentiment, products, right request and the asset earned from it.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
post_idintegerrequiredargumentAs returned by search_posts.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "get_post",
"arguments": {
"team_id": 0,
"post_id": 0
}
}
}const result = await client.callTool("get_post", {
"team_id": 0,
"post_id": 0
});result = await session.call_tool("get_post", arguments={
"team_id": 0,
"post_id": 0
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}update_posts
destructiveidempotentUpdates posts of a team: approves (public) or hides (private) them, sets the reasons, adds or removes tags, sets the alternative text of their images, and highlights or pins them. It can't delete posts. Takes the IDs of up to 250 posts, as returned by search_posts (use several calls for more). Changes appear in searches within a few seconds, and can be undone by updating the posts again.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
post_idsArray<integer>requiredargumentstatusstringpublicprivateargumentstatus_reasonsArray<string>legal_transgressioninappropriateforeign_languagecontains_private_infounrelatedmisleadingfakeharmful_contentwrong_languageoff_topicspamlow_effortnonsenseauto_moderationauto_moderation_nsfwauto_moderation_authorauto_moderation_keywordauto_moderation_remote_ipargumentWhy the posts were moderated. Replaces their current reasons.
add_tagsArray<string>argumentremove_tagsArray<string>argumentIgnores case.
alternative_textstringargumentDescribes the images of the posts for people using screen readers. Since it describes an image, set it for one post at a time.
highlightedbooleanargumentpinnedbooleanargumentReturns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "update_posts",
"arguments": {
"team_id": 0,
"post_ids": [
0
],
"status": "public",
"status_reasons": [
"legal_transgression"
],
"add_tags": [
"string"
],
"remove_tags": [
"string"
],
"alternative_text": "string",
"highlighted": true,
"pinned": true
}
}
}const result = await client.callTool("update_posts", {
"team_id": 0,
"post_ids": [
0
],
"status": "public",
"status_reasons": [
"legal_transgression"
],
"add_tags": [
"string"
],
"remove_tags": [
"string"
],
"alternative_text": "string",
"highlighted": true,
"pinned": true
});result = await session.call_tool("update_posts", arguments={
"team_id": 0,
"post_ids": [
0
],
"status": "public",
"status_reasons": [
"legal_transgression"
],
"add_tags": [
"string"
],
"remove_tags": [
"string"
],
"alternative_text": "string",
"highlighted": true,
"pinned": true
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}Assets
search_assets
read-onlyidempotentSearches the assets (images and videos) in the library of a team, newest first by default. Returns up to 100 assets per page (1,000 with ids_only) and the total number that match, and can page through the first 10000 of them. Use aggregate_assets instead to count assets, and ids_only to collect the IDs of many assets to update with update_assets.
Body
team_idintegerrequiredThe ID of the team, as returned by list_teams.
qstringFull-text search of the title, description, alternative text and OCR text of the assets.
media_typestringOnly assets of these media types: image, video.
objectsstringOnly assets showing at least one of these objects, for example cat,dog.
all_objectsstringOnly assets showing all of these objects, for example person,cat.
tagsstringOnly assets with at least one of these tags.
without_tagsstringOnly assets with none of these tags.
has_tagsbooleanOnly assets with (or without) tags.
has_objectsbooleanOnly assets with (or without) detected objects.
has_alternative_textbooleanOnly assets with (or without) alternative text.
collection_idstringOnly assets in these collections (see list_collections).
member_idstringOnly assets from these loyalty members (see get_member).
sourcestringOnly assets from these sources: branded assets were uploaded by the team, and the others come from posts or forms. One of: branded, facebook, twitter, instagram, youtube, pinterest, rss, googleplus, linkedin, vine, tumblr, custom, flickr, google_news, wechat, hootsuite, public_post, slack, spark, sms, review_trackers, tiktok, form_submission, instagram_business, externally_sourced_posts, email, threads, creator_iq.
typestringOnly assets obtained this way: earned (rights granted by their creator), uploaded, influencer.
statusstringOnly assets with these statuses: active, archived. Defaults to active.
created_atobjectOnly assets added to the library in this range, for example {"$gte": "2026-09-21T00:00:00Z"}.
emotionsstringOnly assets showing faces with at least one of these emotions.
sfwbooleanOnly assets that are (or are not) safe for work.
sortstringnewestoldestrelevanceDefaults to newest.
ids_onlybooleanReturn only the IDs of the assets, up to 1,000 per page.
pageinteger>= 1Defaults to 1.
page_sizeinteger[1, 1000]Defaults to 25. At most 100, or 1,000 with ids_only.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "search_assets",
"arguments": {
"team_id": 0,
"q": "string",
"media_type": "string",
"objects": "string",
"all_objects": "string",
"tags": "string",
"without_tags": "string",
"has_tags": true,
"has_objects": true,
"has_alternative_text": true,
"collection_id": "string",
"member_id": "string",
"source": "string",
"type": "string",
"status": "string",
"created_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"emotions": "string",
"sfw": true,
"sort": "newest",
"ids_only": true,
"page": 1,
"page_size": 1
}
}
}const result = await client.callTool("search_assets", {
"team_id": 0,
"q": "string",
"media_type": "string",
"objects": "string",
"all_objects": "string",
"tags": "string",
"without_tags": "string",
"has_tags": true,
"has_objects": true,
"has_alternative_text": true,
"collection_id": "string",
"member_id": "string",
"source": "string",
"type": "string",
"status": "string",
"created_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"emotions": "string",
"sfw": true,
"sort": "newest",
"ids_only": true,
"page": 1,
"page_size": 1
});result = await session.call_tool("search_assets", arguments={
"team_id": 0,
"q": "string",
"media_type": "string",
"objects": "string",
"all_objects": "string",
"tags": "string",
"without_tags": "string",
"has_tags": true,
"has_objects": true,
"has_alternative_text": true,
"collection_id": "string",
"member_id": "string",
"source": "string",
"type": "string",
"status": "string",
"created_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"emotions": "string",
"sfw": true,
"sort": "newest",
"ids_only": true,
"page": 1,
"page_size": 1
}){
"team_id": 0,
"q": "string",
"media_type": "string",
"objects": "string",
"all_objects": "string",
"tags": "string",
"without_tags": "string",
"has_tags": true,
"has_objects": true,
"has_alternative_text": true,
"collection_id": "string",
"member_id": "string",
"source": "string",
"type": "string",
"status": "string",
"created_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"emotions": "string",
"sfw": true,
"sort": "newest",
"ids_only": true,
"page": 1,
"page_size": 1
}{
"content": [
{
"type": "text",
"text": "..."
}
]
}aggregate_assets
read-onlyidempotentCounts the assets in the library of a team that match the filters (the same as search_assets), with the totals asked for, optionally grouped by up to three fields or the day, week or month they were added, each within the previous one, or clustered (for example the members they came from, by member_id). For example, group by media_type to find whether the team has more images or videos, then by object for the objects they show the most.
Body
team_idintegerrequiredThe ID of the team, as returned by list_teams.
qstringFull-text search of the title, description, alternative text and OCR text of the assets.
media_typestringOnly assets of these media types: image, video.
objectsstringOnly assets showing at least one of these objects, for example cat,dog.
all_objectsstringOnly assets showing all of these objects, for example person,cat.
tagsstringOnly assets with at least one of these tags.
without_tagsstringOnly assets with none of these tags.
has_tagsbooleanOnly assets with (or without) tags.
has_objectsbooleanOnly assets with (or without) detected objects.
has_alternative_textbooleanOnly assets with (or without) alternative text.
collection_idstringOnly assets in these collections (see list_collections).
member_idstringOnly assets from these loyalty members (see get_member).
sourcestringOnly assets from these sources: branded assets were uploaded by the team, and the others come from posts or forms. One of: branded, facebook, twitter, instagram, youtube, pinterest, rss, googleplus, linkedin, vine, tumblr, custom, flickr, google_news, wechat, hootsuite, public_post, slack, spark, sms, review_trackers, tiktok, form_submission, instagram_business, externally_sourced_posts, email, threads, creator_iq.
typestringOnly assets obtained this way: earned (rights granted by their creator), uploaded, influencer.
statusstringOnly assets with these statuses: active, archived. Defaults to active.
created_atobjectOnly assets added to the library in this range, for example {"$gte": "2026-09-21T00:00:00Z"}.
emotionsstringOnly assets showing faces with at least one of these emotions.
sfwbooleanOnly assets that are (or are not) safe for work.
group_byArray<string>media_typesourcetypeobjecttagcollection_idmember_idemotionstatusdayweekmonthGroup the assets by these fields, or by the day, week or month they were added, each group within the previous one. For example ["media_type", "object"].
sizeinteger[1, 100]The number of groups (the largest first) to return for each field, up to 10 after the first one. Defaults to 10.
time_zonestringThe time zone of the days, weeks and months, for example America/New_York. Defaults to UTC.
sumArray<string>sizesize is in bytes.
averageArray<string>sizeminArray<string>sizecreated_atupdated_atThe smallest of these, for example created_at for the first asset added.
maxArray<string>sizecreated_atupdated_atThe largest of these, for example created_at for the latest asset added.
distinctArray<string>media_typesourcetypeobjecttagmember_idemotionstatusCount the distinct values of these fields, for example member_id for the number of creators.
clusterobjectInstead of grouping, cluster the values of a field into groups of similar values (k-means), by their number of documents and the totals asked for (sum, average, min, max, distinct) of each value. Clusters the 10000 values with the most documents, and returns the size of each cluster, its average count and totals, and a few of its values. For example {"by": "member_id", "into": 4} with distinct tag and max created_at, for the kinds of creators.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "aggregate_assets",
"arguments": {
"team_id": 0,
"q": "string",
"media_type": "string",
"objects": "string",
"all_objects": "string",
"tags": "string",
"without_tags": "string",
"has_tags": true,
"has_objects": true,
"has_alternative_text": true,
"collection_id": "string",
"member_id": "string",
"source": "string",
"type": "string",
"status": "string",
"created_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"emotions": "string",
"sfw": true,
"group_by": [
"media_type"
],
"size": 1,
"time_zone": "string",
"sum": [
"size"
],
"average": [
"size"
],
"min": [
"size"
],
"max": [
"size"
],
"distinct": [
"media_type"
],
"cluster": {
"by": "media_type",
"into": 2
}
}
}
}const result = await client.callTool("aggregate_assets", {
"team_id": 0,
"q": "string",
"media_type": "string",
"objects": "string",
"all_objects": "string",
"tags": "string",
"without_tags": "string",
"has_tags": true,
"has_objects": true,
"has_alternative_text": true,
"collection_id": "string",
"member_id": "string",
"source": "string",
"type": "string",
"status": "string",
"created_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"emotions": "string",
"sfw": true,
"group_by": [
"media_type"
],
"size": 1,
"time_zone": "string",
"sum": [
"size"
],
"average": [
"size"
],
"min": [
"size"
],
"max": [
"size"
],
"distinct": [
"media_type"
],
"cluster": {
"by": "media_type",
"into": 2
}
});result = await session.call_tool("aggregate_assets", arguments={
"team_id": 0,
"q": "string",
"media_type": "string",
"objects": "string",
"all_objects": "string",
"tags": "string",
"without_tags": "string",
"has_tags": true,
"has_objects": true,
"has_alternative_text": true,
"collection_id": "string",
"member_id": "string",
"source": "string",
"type": "string",
"status": "string",
"created_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"emotions": "string",
"sfw": true,
"group_by": [
"media_type"
],
"size": 1,
"time_zone": "string",
"sum": [
"size"
],
"average": [
"size"
],
"min": [
"size"
],
"max": [
"size"
],
"distinct": [
"media_type"
],
"cluster": {
"by": "media_type",
"into": 2
}
}){
"team_id": 0,
"q": "string",
"media_type": "string",
"objects": "string",
"all_objects": "string",
"tags": "string",
"without_tags": "string",
"has_tags": true,
"has_objects": true,
"has_alternative_text": true,
"collection_id": "string",
"member_id": "string",
"source": "string",
"type": "string",
"status": "string",
"created_at": {
"$eq": "string",
"$gt": "string",
"$gte": "string",
"$lt": "string",
"$lte": "string"
},
"emotions": "string",
"sfw": true,
"group_by": [
"media_type"
],
"size": 1,
"time_zone": "string",
"sum": [
"size"
],
"average": [
"size"
],
"min": [
"size"
],
"max": [
"size"
],
"distinct": [
"media_type"
],
"cluster": {
"by": "media_type",
"into": 2
}
}{
"content": [
{
"type": "text",
"text": "..."
}
]
}get_asset
read-onlyidempotentGets an asset in the library of a team, the same as search_assets returns it: where it came from (uploaded by the team, earned from a post through a right request, or submitted with a form), when its creator's rights were granted, its collections, the posts it came from and the loyalty member it came from (member_id, see get_member).
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
asset_idintegerrequiredargumentAs returned by search_assets.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "get_asset",
"arguments": {
"team_id": 0,
"asset_id": 0
}
}
}const result = await client.callTool("get_asset", {
"team_id": 0,
"asset_id": 0
});result = await session.call_tool("get_asset", arguments={
"team_id": 0,
"asset_id": 0
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}update_assets
destructiveidempotentUpdates assets in the library of a team: adds or removes tags, adds them to or removes them from collections, sets their title, description or alternative text, and archives or restores them. Takes the IDs of up to 250 assets, as returned by search_assets (use ids_only to collect many, and several calls to update them). Changes appear in searches within a few seconds, and can be undone by updating the assets again.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
asset_idsArray<integer>requiredargumentadd_tagsArray<string>argumentremove_tagsArray<string>argumentIgnores case.
add_collection_idsArray<integer>argumentSee list_collections.
remove_collection_idsArray<integer>argumentnamestringargumentThe title of the assets.
descriptionstringargumentalternative_textstringargumentDescribes the assets for people using screen readers.
statusstringactivearchivedargumentarchived hides the assets from the library.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "update_assets",
"arguments": {
"team_id": 0,
"asset_ids": [
0
],
"add_tags": [
"string"
],
"remove_tags": [
"string"
],
"add_collection_ids": [
0
],
"remove_collection_ids": [
0
],
"name": "string",
"description": "string",
"alternative_text": "string",
"status": "active"
}
}
}const result = await client.callTool("update_assets", {
"team_id": 0,
"asset_ids": [
0
],
"add_tags": [
"string"
],
"remove_tags": [
"string"
],
"add_collection_ids": [
0
],
"remove_collection_ids": [
0
],
"name": "string",
"description": "string",
"alternative_text": "string",
"status": "active"
});result = await session.call_tool("update_assets", arguments={
"team_id": 0,
"asset_ids": [
0
],
"add_tags": [
"string"
],
"remove_tags": [
"string"
],
"add_collection_ids": [
0
],
"remove_collection_ids": [
0
],
"name": "string",
"description": "string",
"alternative_text": "string",
"status": "active"
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}list_collections
read-onlyidempotentLists the collections of assets of a team that you have access to, with the number of active assets in each. Use their IDs to filter assets by collection_id or to add assets to them with update_assets.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
namestringargumentOnly the collections whose name contains this text, ignoring case.
statusstringactivearchivedargumentDefaults to active.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_collections",
"arguments": {
"team_id": 0,
"name": "string",
"status": "active"
}
}
}const result = await client.callTool("list_collections", {
"team_id": 0,
"name": "string",
"status": "active"
});result = await session.call_tool("list_collections", arguments={
"team_id": 0,
"name": "string",
"status": "active"
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}Members
search_members
read-onlyidempotentSearches the loyalty members (or members) of a team, newest first by default. Returns up to 100 members per page (1,000 with fields) and the total number that match, and can page through the first 10000 of them. Use aggregate_members instead to count members or compute totals.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
whereobjectargumentOnly members matching all of these conditions, by field: id (a list of IDs), email, first_name, last_name, member_uid, loyalty_level_id, loyalty_level_name, loyalty_lifetime_level_name, referral_code, referral_url, creation_source, acq_network, churn_status, preferred_language, tags, segments, twitter_handle, profile_url, city, state, country, postal_code, total_revenue, average_order_value, receipt_average_order_value, receipt_purchase_revenue, no_of_purchase, no_of_receipt_purchase, no_of_referral_purchase, no_of_referral_share, no_of_review, no_of_reward, number_of_referred_friends, predicted_churn_probability, available_points, pending_points, redeemed_points, expired_points, points_earned, points_awarded, deducted_points, points_onhold, qualified_points, created_time, updated_time, enrollment_date, loyalty_enroll_time, last_interaction_date, first_purchase_date, last_purchase_date, last_points_earned_date, last_points_redeemed_date, conditional_tier_end_date, is_loyalty_user, is_raf_user, has_opted_out, email_subscription_status, or custom_attributes. (see list_member_attributes, which requires the schemas:read scope). Each value is a value (case-sensitive for text), a list of values (any of them), or an object with gt, gte, lt, lte (numbers and dates, for example {"gte": "2026-03-01", "lt": "2026-04-01"}), contains (text, ignoring case) or exists (true or false). For example {"loyalty_level_name": "Silver", "country": "US"}.
fieldsArray<string>argumentOnly return these fields (and the ID) of the members, for example ["member_uid", "referral_code"] to export them. Defaults to everything, like get_member.
order_bystringargumentThe field to sort by. Defaults to created_time.
orderstringascdescargumentDefaults to desc.
pageinteger>= 1argumentDefaults to 1.
page_sizeinteger[1, 1000]argumentDefaults to 25. At most 100, or 1,000 with fields.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "search_members",
"arguments": {
"team_id": 0,
"where": {},
"fields": [
"string"
],
"order_by": "string",
"order": "asc",
"page": 1,
"page_size": 1
}
}
}const result = await client.callTool("search_members", {
"team_id": 0,
"where": {},
"fields": [
"string"
],
"order_by": "string",
"order": "asc",
"page": 1,
"page_size": 1
});result = await session.call_tool("search_members", arguments={
"team_id": 0,
"where": {},
"fields": [
"string"
],
"order_by": "string",
"order": "asc",
"page": 1,
"page_size": 1
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}aggregate_members
read-onlyidempotentCounts the loyalty members (or members) of a team that match the conditions (the same as search_members), with the totals asked for, optionally grouped by up to three fields, each within the previous one. For example, group by "created_time:month" for monthly sign-up cohorts, or by loyalty_level_name for the members of each tier, and sum available_points and pending_points for the outstanding points.
Body
team_idintegerrequiredThe ID of the team, as returned by list_teams.
whereobjectOnly members matching all of these conditions, by field: id (a list of IDs), email, first_name, last_name, member_uid, loyalty_level_id, loyalty_level_name, loyalty_lifetime_level_name, referral_code, referral_url, creation_source, acq_network, churn_status, preferred_language, tags, segments, twitter_handle, profile_url, city, state, country, postal_code, total_revenue, average_order_value, receipt_average_order_value, receipt_purchase_revenue, no_of_purchase, no_of_receipt_purchase, no_of_referral_purchase, no_of_referral_share, no_of_review, no_of_reward, number_of_referred_friends, predicted_churn_probability, available_points, pending_points, redeemed_points, expired_points, points_earned, points_awarded, deducted_points, points_onhold, qualified_points, created_time, updated_time, enrollment_date, loyalty_enroll_time, last_interaction_date, first_purchase_date, last_purchase_date, last_points_earned_date, last_points_redeemed_date, conditional_tier_end_date, is_loyalty_user, is_raf_user, has_opted_out, email_subscription_status, or custom_attributes. (see list_member_attributes, which requires the schemas:read scope). Each value is a value (case-sensitive for text), a list of values (any of them), or an object with gt, gte, lt, lte (numbers and dates, for example {"gte": "2026-03-01", "lt": "2026-04-01"}), contains (text, ignoring case) or exists (true or false). For example {"loyalty_level_name": "Silver", "country": "US"}.
group_byArray<string>Group the members by these fields, each group within the previous one. Dates are grouped by day, week, month, quarter, year, day_of_week, hour_of_day, for example "created_time:month".
sumArray<string>Sum these numbers.
averageArray<string>Average these numbers.
minArray<string>The smallest of these numbers or dates, for example the first date.
maxArray<string>The largest of these numbers or dates, for example the latest date.
distinctArray<string>Count the distinct values of these fields, for example state.
sizeinteger[1, 100]The number of groups to return for each field that isn't a date. Defaults to 10.
order_groups_bystringOrder the groups of fields that aren't dates by this total, for example sum_available_points, instead of by count.
time_zonestringThe time zone of the date groups, for example America/New_York. Defaults to UTC.
clusterobjectInstead of grouping, cluster the values of a field into groups of similar values (k-means), by their number of documents and the totals asked for (sum, average, min, max, distinct) of each value. Clusters the 10000 values with the most documents, and returns the size of each cluster, its average count and totals, and a few of its values. For example {"by": "member_uid", "into": 5} with sum total_revenue and max last_purchase_date.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "aggregate_members",
"arguments": {
"team_id": 0,
"where": {},
"group_by": [
"string"
],
"sum": [
"string"
],
"average": [
"string"
],
"min": [
"string"
],
"max": [
"string"
],
"distinct": [
"string"
],
"size": 1,
"order_groups_by": "string",
"time_zone": "string",
"cluster": {
"by": "string",
"into": 2
}
}
}
}const result = await client.callTool("aggregate_members", {
"team_id": 0,
"where": {},
"group_by": [
"string"
],
"sum": [
"string"
],
"average": [
"string"
],
"min": [
"string"
],
"max": [
"string"
],
"distinct": [
"string"
],
"size": 1,
"order_groups_by": "string",
"time_zone": "string",
"cluster": {
"by": "string",
"into": 2
}
});result = await session.call_tool("aggregate_members", arguments={
"team_id": 0,
"where": {},
"group_by": [
"string"
],
"sum": [
"string"
],
"average": [
"string"
],
"min": [
"string"
],
"max": [
"string"
],
"distinct": [
"string"
],
"size": 1,
"order_groups_by": "string",
"time_zone": "string",
"cluster": {
"by": "string",
"into": 2
}
}){
"team_id": 0,
"where": {},
"group_by": [
"string"
],
"sum": [
"string"
],
"average": [
"string"
],
"min": [
"string"
],
"max": [
"string"
],
"distinct": [
"string"
],
"size": 1,
"order_groups_by": "string",
"time_zone": "string",
"cluster": {
"by": "string",
"into": 2
}
}{
"content": [
{
"type": "text",
"text": "..."
}
]
}get_member
read-onlyidempotentGets a loyalty member (or member) of a team, the same as search_members returns it: their profile, tier, points, purchases, referrals and custom attributes (with the schemas:read scope). Takes their ID or their member UID, which is how most loyalty programs identify their members.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
idstringargumentAs returned by search_members.
member_uidstringargumentReturns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "get_member",
"arguments": {
"team_id": 0,
"id": "string",
"member_uid": "string"
}
}
}const result = await client.callTool("get_member", {
"team_id": 0,
"id": "string",
"member_uid": "string"
});result = await session.call_tool("get_member", arguments={
"team_id": 0,
"id": "string",
"member_uid": "string"
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}list_member_attributes
read-onlyidempotentLists the custom attributes of the loyalty members (or members) of a team: their key, name, description, type and the number of members who have them. Members, search_members and aggregate_members have them by key (custom_attributes.), so use this to find an attribute by name.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_member_attributes",
"arguments": {
"team_id": 0
}
}
}const result = await client.callTool("list_member_attributes", {
"team_id": 0
});result = await session.call_tool("list_member_attributes", arguments={
"team_id": 0
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}create_member_attribute
Early access: this tool is only available to teams in our early access program.
Adds a custom attribute to the loyalty members of a team, which members then have by its key (custom_attributes., see list_member_attributes), for example to segment them or in the conditions of rules. The API and imports set members' values by its name. Attributes can't be deleted, and their type can't change.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
namestringrequiredargumentUnique among the team's member attributes.
descriptionstringargumentfield_typestringtexttextareadropdownmultiselectdatepickernumberrequiredargumentHow the admin edits it, which sets its type: text, textarea and dropdown are strings, multiselect a list, datepicker a date and number a number.
allowed_valuesArray<string>argumentThe choices of dropdown and multiselect attributes.
show_to_membersbooleanargumentWhether members see it on their dashboard.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "create_member_attribute",
"arguments": {
"team_id": 0,
"name": "string",
"description": "string",
"field_type": "text",
"allowed_values": [
"string"
],
"show_to_members": true
}
}
}const result = await client.callTool("create_member_attribute", {
"team_id": 0,
"name": "string",
"description": "string",
"field_type": "text",
"allowed_values": [
"string"
],
"show_to_members": true
});result = await session.call_tool("create_member_attribute", arguments={
"team_id": 0,
"name": "string",
"description": "string",
"field_type": "text",
"allowed_values": [
"string"
],
"show_to_members": true
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}Transactions
search_transactions
read-onlyidempotentSearches the loyalty transactions of a team (the points members earn, redeem, lose or have deducted), newest first by default. Returns up to 100 transactions per page (1,000 with fields) and the total number that match, and can page through the first 10000 of them. Use aggregate_transactions instead to count transactions or compute totals.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
whereobjectargumentOnly transactions (user_id is the ID of the member, see get_member) matching all of these conditions, by field: id (a list of IDs), user_id, user_email, user_first_name, user_last_name, activity_id, activity_name, activity_category, points_status, transaction_type, coupon_code, source, current_loyalty_level_id, rule_id, rule_name, points, points_passed, points_used, points_onhold, points_expired, points_deducted, created_time, updated_time, approved_time, auto_approval_date, points_expiration_date, qualified_points, or additional_data.
fieldsArray<string>argumentOnly return these fields (and the ID) of the transactions. Defaults to everything, like get_transaction.
order_bystringargumentThe field to sort by. Defaults to created_time.
orderstringascdescargumentDefaults to desc.
pageinteger>= 1argumentDefaults to 1.
page_sizeinteger[1, 1000]argumentDefaults to 25. At most 100, or 1,000 with fields.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "search_transactions",
"arguments": {
"team_id": 0,
"where": {},
"fields": [
"string"
],
"order_by": "string",
"order": "asc",
"page": 1,
"page_size": 1
}
}
}const result = await client.callTool("search_transactions", {
"team_id": 0,
"where": {},
"fields": [
"string"
],
"order_by": "string",
"order": "asc",
"page": 1,
"page_size": 1
});result = await session.call_tool("search_transactions", arguments={
"team_id": 0,
"where": {},
"fields": [
"string"
],
"order_by": "string",
"order": "asc",
"page": 1,
"page_size": 1
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}aggregate_transactions
read-onlyidempotentCounts the loyalty transactions of a team that match the conditions (the same as search_transactions), with the totals asked for, optionally grouped by up to three fields, each within the previous one. For example, sum points grouped by transaction_type and "created_time:month" for the points awarded and redeemed each month, count the distinct user_id of redemptions for the number of members who redeemed, group by "created_time:day_of_week" or "created_time:hour_of_day" for when members are active, or group by user_id ordered by sum_points for the members who earned the most.
Body
team_idintegerrequiredThe ID of the team, as returned by list_teams.
whereobjectOnly transactions (user_id is the ID of the member, see get_member) matching all of these conditions, by field: id (a list of IDs), user_id, user_email, user_first_name, user_last_name, activity_id, activity_name, activity_category, points_status, transaction_type, coupon_code, source, current_loyalty_level_id, rule_id, rule_name, points, points_passed, points_used, points_onhold, points_expired, points_deducted, created_time, updated_time, approved_time, auto_approval_date, points_expiration_date, qualified_points, or additional_data.
group_byArray<string>Group the transactions by these fields, each group within the previous one. Dates are grouped by day, week, month, quarter, year, day_of_week, hour_of_day, for example "created_time:month".
sumArray<string>Sum these numbers.
averageArray<string>Average these numbers.
minArray<string>The smallest of these numbers or dates, for example the first date.
maxArray<string>The largest of these numbers or dates, for example the latest date.
distinctArray<string>Count the distinct values of these fields, for example user_id (the number of members).
sizeinteger[1, 100]The number of groups to return for each field that isn't a date. Defaults to 10.
order_groups_bystringOrder the groups of fields that aren't dates by this total, for example sum_points, instead of by count.
time_zonestringThe time zone of the date groups, for example America/New_York. Defaults to UTC.
clusterobjectInstead of grouping, cluster the values of a field into groups of similar values (k-means), by their number of documents and the totals asked for (sum, average, min, max, distinct) of each value. Clusters the 10000 values with the most documents, and returns the size of each cluster, its average count and totals, and a few of its values. For example {"by": "user_id", "into": 6} with sum additional_data.order_info.order_total and max created_time, for personas of the members.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "aggregate_transactions",
"arguments": {
"team_id": 0,
"where": {},
"group_by": [
"string"
],
"sum": [
"string"
],
"average": [
"string"
],
"min": [
"string"
],
"max": [
"string"
],
"distinct": [
"string"
],
"size": 1,
"order_groups_by": "string",
"time_zone": "string",
"cluster": {
"by": "string",
"into": 2
}
}
}
}const result = await client.callTool("aggregate_transactions", {
"team_id": 0,
"where": {},
"group_by": [
"string"
],
"sum": [
"string"
],
"average": [
"string"
],
"min": [
"string"
],
"max": [
"string"
],
"distinct": [
"string"
],
"size": 1,
"order_groups_by": "string",
"time_zone": "string",
"cluster": {
"by": "string",
"into": 2
}
});result = await session.call_tool("aggregate_transactions", arguments={
"team_id": 0,
"where": {},
"group_by": [
"string"
],
"sum": [
"string"
],
"average": [
"string"
],
"min": [
"string"
],
"max": [
"string"
],
"distinct": [
"string"
],
"size": 1,
"order_groups_by": "string",
"time_zone": "string",
"cluster": {
"by": "string",
"into": 2
}
}){
"team_id": 0,
"where": {},
"group_by": [
"string"
],
"sum": [
"string"
],
"average": [
"string"
],
"min": [
"string"
],
"max": [
"string"
],
"distinct": [
"string"
],
"size": 1,
"order_groups_by": "string",
"time_zone": "string",
"cluster": {
"by": "string",
"into": 2
}
}{
"content": [
{
"type": "text",
"text": "..."
}
]
}get_transaction
read-onlyidempotentGets a loyalty transaction of a team, the same as search_transactions returns it: the member, the activity, the points and their status, the rules applied and its custom attributes (with the schemas:read scope).
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
idstringrequiredargumentAs returned by search_transactions.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "get_transaction",
"arguments": {
"team_id": 0,
"id": "string"
}
}
}const result = await client.callTool("get_transaction", {
"team_id": 0,
"id": "string"
});result = await session.call_tool("get_transaction", arguments={
"team_id": 0,
"id": "string"
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}list_transaction_attributes
read-onlyidempotentLists the custom attributes of the loyalty transactions of a team: their key, name, description, type and the number of transactions that have them. Transactions, search_transactions and aggregate_transactions have them by key (custom_attributes.), so use this to find an attribute by name.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_transaction_attributes",
"arguments": {
"team_id": 0
}
}
}const result = await client.callTool("list_transaction_attributes", {
"team_id": 0
});result = await session.call_tool("list_transaction_attributes", arguments={
"team_id": 0
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}create_transaction_attribute
Early access: this tool is only available to teams in our early access program.
Adds a custom attribute to the transactions of an activity or a reward, or of all of them, which transactions then have by its key (custom_attributes., see list_transaction_attributes), for example in the conditions of rules. The API sets transactions' values by its external_id. Attributes can't be deleted, and their type can't change.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
namestringrequiredargumentdescriptionstringargumenttypestringstringnumberlistdaterequiredargumentexternal_idstringrequiredargumentThe ID the API sets it by (lowercase letters, digits, _ and -), unique among the team's transaction attributes.
parentstringactivityrewardall_activitiesall_rewardsallrequiredargumentWhose transactions have it: an activity or a reward (see parent_slug), all activities, all rewards, or all transactions.
parent_slugstringargumentThe slug of the activity or reward, as list_activities or list_rewards return it.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "create_transaction_attribute",
"arguments": {
"team_id": 0,
"name": "string",
"description": "string",
"type": "string",
"external_id": "string",
"parent": "activity",
"parent_slug": "string"
}
}
}const result = await client.callTool("create_transaction_attribute", {
"team_id": 0,
"name": "string",
"description": "string",
"type": "string",
"external_id": "string",
"parent": "activity",
"parent_slug": "string"
});result = await session.call_tool("create_transaction_attribute", arguments={
"team_id": 0,
"name": "string",
"description": "string",
"type": "string",
"external_id": "string",
"parent": "activity",
"parent_slug": "string"
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}Activities
list_activities
read-onlyidempotentLists the activities of the loyalty program of a team, which members earn points for, with the points each one awards, by rank, and whether it's on its storefront (on_storefront): active, shown on the dashboard, and neither a campaign's nor of a feature the team turned off. Its rules may still keep some members from seeing it.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_activities",
"arguments": {
"team_id": 0
}
}
}const result = await client.callTool("list_activities", {
"team_id": 0
});result = await session.call_tool("list_activities", arguments={
"team_id": 0
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}create_activity
Early access: this tool is only available to teams in our early access program.
Adds a form activity to the loyalty program of a team, for teams with form activities: members earn its points once, when they submit the form (see list_forms) from their dashboard. It's created inactive unless active is true. Change it with update_activity and its points with update_default_rule.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
form_idintegerrequiredargumentThe ID of a published form, as returned by list_forms.
namestringrequiredargumentdescriptionstringargumentWhat members see about it.
pointsnumber>= 0requiredargumentactivebooleanargumentReturns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "create_activity",
"arguments": {
"team_id": 0,
"form_id": 0,
"name": "string",
"description": "string",
"points": 0,
"active": true
}
}
}const result = await client.callTool("create_activity", {
"team_id": 0,
"form_id": 0,
"name": "string",
"description": "string",
"points": 0,
"active": true
});result = await session.call_tool("create_activity", arguments={
"team_id": 0,
"form_id": 0,
"name": "string",
"description": "string",
"points": 0,
"active": true
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}update_activity
destructiveidempotentEarly access: this tool is only available to teams in our early access program.
Changes an activity of the loyalty program of a team: its name, descriptions, images, button label, notification text and other texts members see, whether it's active (inactive activities award no points) or shown on the dashboard (to members and visitors alike, but it still awards points), and how its points are approved (immediately, manually, or after a number of days). Members see the changes right away. Use update_default_rule for its points.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
activitystringrequiredargumentThe slug of the activity, as returned by list_activities.
namestringargumentdescriptionstringargumentactivebooleanargumentapprovalstringimmediatemanualafter_daysargumentHow the points of new transactions are approved. after_days takes approval_days.
approval_daysinteger>= 1argumenttile_image_urlstring<uri>argumentThe image of its tile (280 x 280).
icon_image_urlstring<uri>argumentIts icon (58 x 58).
show_on_dashboardbooleanargumentbutton_labelstringargumentThe label of its button. {{POINTS}} shows its points, as in "Earn {{POINTS}} points".
notification_textstringargumentThe text of the notifications members get when they earn its points.
description_htmlstringargumentThe description of how members earn its points, in HTML.
textsobjectargumentOther texts members see (thank you texts, errors, buttons...), by key, which depend on the activity: the result returns its texts, and an unknown key the keys it has. {{POINTS}} shows its points.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "update_activity",
"arguments": {
"team_id": 0,
"activity": "string",
"name": "string",
"description": "string",
"active": true,
"approval": "immediate",
"approval_days": 1,
"tile_image_url": "https://example.com",
"icon_image_url": "https://example.com",
"show_on_dashboard": true,
"button_label": "string",
"notification_text": "string",
"description_html": "string",
"texts": {}
}
}
}const result = await client.callTool("update_activity", {
"team_id": 0,
"activity": "string",
"name": "string",
"description": "string",
"active": true,
"approval": "immediate",
"approval_days": 1,
"tile_image_url": "https://example.com",
"icon_image_url": "https://example.com",
"show_on_dashboard": true,
"button_label": "string",
"notification_text": "string",
"description_html": "string",
"texts": {}
});result = await session.call_tool("update_activity", arguments={
"team_id": 0,
"activity": "string",
"name": "string",
"description": "string",
"active": true,
"approval": "immediate",
"approval_days": 1,
"tile_image_url": "https://example.com",
"icon_image_url": "https://example.com",
"show_on_dashboard": true,
"button_label": "string",
"notification_text": "string",
"description_html": "string",
"texts": {}
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}Rewards
list_rewards
read-onlyidempotentLists the rewards of the loyalty program of a team, which members redeem with their points, by rank.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
slugsArray<string>argumentOnly the rewards with these slugs.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_rewards",
"arguments": {
"team_id": 0,
"slugs": [
"string"
]
}
}
}const result = await client.callTool("list_rewards", {
"team_id": 0,
"slugs": [
"string"
]
});result = await session.call_tool("list_rewards", arguments={
"team_id": 0,
"slugs": [
"string"
]
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}create_reward
Early access: this tool is only available to teams in our early access program.
Adds a reward to the loyalty program of a team, which members redeem with their points for a coupon. It's created inactive: upload its coupon codes in TrueLoyal, then activate it with update_reward. Rewards whose coupons the store creates are set up in TrueLoyal.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
typestringfixed_amount_discountpercentage_discountfree_shippingcustomrequiredargumentnamestringrequiredargumentdescriptionstringrequiredargumentIts description, in the emails and API (the card shows short_description).
short_descriptionstringargumentThe text of its card. {{POINTS}} shows its points, as in "For {{POINTS}} points".
pointsnumberrequiredargumentThe points it costs.
valueinteger>= 1argumentFor fixed_amount_discount and percentage_discount rewards, the discount: 10 for $10 (in the store's currency) or 10% off. Only a label: the discount is the one of its coupons.
tile_image_urlstring<uri>argumentThe image of its card.
hidden_from_guestsbooleanargumentHides it from visitors who aren't signed in.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "create_reward",
"arguments": {
"team_id": 0,
"type": "fixed_amount_discount",
"name": "string",
"description": "string",
"short_description": "string",
"points": 0,
"value": 1,
"tile_image_url": "https://example.com",
"hidden_from_guests": true
}
}
}const result = await client.callTool("create_reward", {
"team_id": 0,
"type": "fixed_amount_discount",
"name": "string",
"description": "string",
"short_description": "string",
"points": 0,
"value": 1,
"tile_image_url": "https://example.com",
"hidden_from_guests": true
});result = await session.call_tool("create_reward", arguments={
"team_id": 0,
"type": "fixed_amount_discount",
"name": "string",
"description": "string",
"short_description": "string",
"points": 0,
"value": 1,
"tile_image_url": "https://example.com",
"hidden_from_guests": true
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}update_reward
destructiveidempotentEarly access: this tool is only available to teams in our early access program.
Changes a reward of the loyalty program of a team: its name, descriptions, points, value, image, the texts members see when they redeem it, whether visitors who aren't signed in see it, and whether it's active (members only see and redeem active rewards, which need unused coupons). Members see the changes right away.
Body
team_idintegerrequiredThe ID of the team, as returned by list_teams.
rewardstringrequiredThe slug of the reward, as returned by list_rewards.
namestringdescriptionstringIts description, in the emails and API (the card shows short_description).
short_descriptionstringThe text of its card. {{POINTS}} shows its points, as in "For {{POINTS}} points".
pointsnumberThe points it costs.
valueinteger>= 1For fixed_amount_discount and percentage_discount rewards, the discount: 10 for $10 (in the store's currency) or 10% off. Only a label: the discount is the one of its coupons.
tile_image_urlstring<uri>The image of its card.
hidden_from_guestsbooleanHides it from visitors who aren't signed in.
activebooleanpost_redemption_htmlstringWhat members see with their coupon code once they redeemed it, in HTML.
textsobjectReturns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "update_reward",
"arguments": {
"team_id": 0,
"reward": "string",
"name": "string",
"description": "string",
"short_description": "string",
"points": 0,
"value": 1,
"tile_image_url": "https://example.com",
"hidden_from_guests": true,
"active": true,
"post_redemption_html": "string",
"texts": {
"redemption_confirmation_text": "string",
"redemption_confirm_button_text": "string",
"redemption_cancel_button_text": "string",
"points_deduction_text": "string",
"redeem_button_text": "string",
"ineligible_rewards_progress_text": "string"
}
}
}
}const result = await client.callTool("update_reward", {
"team_id": 0,
"reward": "string",
"name": "string",
"description": "string",
"short_description": "string",
"points": 0,
"value": 1,
"tile_image_url": "https://example.com",
"hidden_from_guests": true,
"active": true,
"post_redemption_html": "string",
"texts": {
"redemption_confirmation_text": "string",
"redemption_confirm_button_text": "string",
"redemption_cancel_button_text": "string",
"points_deduction_text": "string",
"redeem_button_text": "string",
"ineligible_rewards_progress_text": "string"
}
});result = await session.call_tool("update_reward", arguments={
"team_id": 0,
"reward": "string",
"name": "string",
"description": "string",
"short_description": "string",
"points": 0,
"value": 1,
"tile_image_url": "https://example.com",
"hidden_from_guests": true,
"active": true,
"post_redemption_html": "string",
"texts": {
"redemption_confirmation_text": "string",
"redemption_confirm_button_text": "string",
"redemption_cancel_button_text": "string",
"points_deduction_text": "string",
"redeem_button_text": "string",
"ineligible_rewards_progress_text": "string"
}
}){
"team_id": 0,
"reward": "string",
"name": "string",
"description": "string",
"short_description": "string",
"points": 0,
"value": 1,
"tile_image_url": "https://example.com",
"hidden_from_guests": true,
"active": true,
"post_redemption_html": "string",
"texts": {
"redemption_confirmation_text": "string",
"redemption_confirm_button_text": "string",
"redemption_cancel_button_text": "string",
"points_deduction_text": "string",
"redeem_button_text": "string",
"ineligible_rewards_progress_text": "string"
}
}{
"content": [
{
"type": "text",
"text": "..."
}
]
}list_coupons
read-onlyidempotentEarly access: this tool is only available to teams in our early access program.
Lists the coupon codes of a reward, the most recently used and issued first, with how many it has, how many were issued to members (when they redeemed the reward), are unused, and were used in purchases. Members only see and redeem rewards with unused coupons.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
rewardstringrequiredargumentThe slug of the reward, as returned by list_rewards.
statusstringunusedissuedusedargumentOnly unused coupons, those issued to members, or those used in purchases.
offsetinteger>= 0argumentlimitinteger[1, 1000]argumentDefaults to 100.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_coupons",
"arguments": {
"team_id": 0,
"reward": "string",
"status": "unused",
"offset": 0,
"limit": 1
}
}
}const result = await client.callTool("list_coupons", {
"team_id": 0,
"reward": "string",
"status": "unused",
"offset": 0,
"limit": 1
});result = await session.call_tool("list_coupons", arguments={
"team_id": 0,
"reward": "string",
"status": "unused",
"offset": 0,
"limit": 1
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}create_coupons
idempotentEarly access: this tool is only available to teams in our early access program.
Adds coupon codes to a reward, which members get when they redeem it: create the codes in the store first (for example as Shopify discount codes), since this only uploads them, like Add Coupons in TrueLoyal. Takes up to 10000 codes, and skips those the team already has. Then activate the reward with update_reward if it isn't active.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
rewardstringrequiredargumentThe slug of the reward, as returned by list_rewards.
codesArray<string>requiredargumentReturns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "create_coupons",
"arguments": {
"team_id": 0,
"reward": "string",
"codes": [
"string"
]
}
}
}const result = await client.callTool("create_coupons", {
"team_id": 0,
"reward": "string",
"codes": [
"string"
]
});result = await session.call_tool("create_coupons", arguments={
"team_id": 0,
"reward": "string",
"codes": [
"string"
]
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}Rules
list_rules
read-onlyidempotentEarly access: this tool is only available to teams in our early access program.
Lists the rules of an activity or a reward of the loyalty program of a team, active ones first and the most recently updated first. Activity rules award points (fixed_points and bonus_multiplier), assign tiers (assign_tier) or award none (exclusion) to the members who meet their conditions. Each activity has a default rule, without conditions, which awards its points to every member. Reward rules (exclusion) hide the reward from the members who meet their conditions. For activities, also returns how the team computes points: "rules" (members earn the sum of the points of every active rule they meet, including the default rule, so adding a bonus multiplier of 1 to a default of 1 point per dollar doubles the points) or "activity" (members earn the activity's points, plus the fixed points of the rules they meet, multiplied by their bonus multipliers, so a bonus multiplier of 2 doubles them).
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
activitystringargumentThe slug of the activity, as returned by list_activities.
rewardstringargumentThe slug of the reward, as returned by list_rewards.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_rules",
"arguments": {
"team_id": 0,
"activity": "string",
"reward": "string"
}
}
}const result = await client.callTool("list_rules", {
"team_id": 0,
"activity": "string",
"reward": "string"
});result = await session.call_tool("list_rules", arguments={
"team_id": 0,
"activity": "string",
"reward": "string"
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}create_rule
Early access: this tool is only available to teams in our early access program.
Adds a rule to an activity or a reward of the loyalty program of a team, which applies to members who meet its conditions, from their next transactions (or visits, for rewards). For activities: fixed_points awards points, bonus_multiplier awards points per currency unit spent, assign_tier assigns a tier (except for receipt submissions), and exclusion awards no points (an activity only applies one active exclusion rule). For rewards, exclusion hides the reward. Before adding points, check how the team computes them with list_rules: to double points when rules add up (points_calculation "rules"), add a bonus multiplier equal to the default rule's. Rules with product conditions (such as Product ID) only award points for the products that meet them. Archive rules with update_rule.
Body
team_idintegerrequiredThe ID of the team, as returned by list_teams.
activitystringThe slug of the activity, as returned by list_activities.
rewardstringThe slug of the reward, as returned by list_rewards.
namestringrequiredtypestringfixed_pointsbonus_multiplierexclusionassign_tierrequiredRewards only take exclusion.
valuenumber>= 0The points of fixed_points rules, or the multiplier of bonus_multiplier rules (points per currency unit spent).
tierstringFor assign_tier rules, the name or ID of the tier to assign, often a conditional tier (which members keep for a number of days).
conditionsArray<object>requiredThe conditions members (and their transactions, for activities) must meet. Values: numbers; dates as MM/DD/YYYY, in the time zone of the loyalty program; Between takes "MM/DD/YYYY-MM/DD/YYYY" for dates and "10#100" for numbers; the X day(s) operators take a number of days; On day(s) takes a list of English weekdays; In, Not in and Contain all/any/none of take a list; Is blank and Is not blank take none. User Tier takes tier names or IDs: Equals and one tier for activities, Contain any of or Contain none of and a list for rewards. User Tags take the tags of members (case sensitive) with Contain all/any/none of, Is blank or Is not blank. For members who purchased in the last 30 days, use Last Purchase Date, Less than X day(s) ago, 30.
matchstringallanyWhether the rule applies when members meet all its conditions (the default) or any.
activebooleanDefaults to true.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "create_rule",
"arguments": {
"team_id": 0,
"activity": "string",
"reward": "string",
"name": "string",
"type": "fixed_points",
"value": 0,
"tier": "string",
"conditions": [
{
"attribute": "User Tier",
"operator": "Equals",
"value": "string"
}
],
"match": "all",
"active": true
}
}
}const result = await client.callTool("create_rule", {
"team_id": 0,
"activity": "string",
"reward": "string",
"name": "string",
"type": "fixed_points",
"value": 0,
"tier": "string",
"conditions": [
{
"attribute": "User Tier",
"operator": "Equals",
"value": "string"
}
],
"match": "all",
"active": true
});result = await session.call_tool("create_rule", arguments={
"team_id": 0,
"activity": "string",
"reward": "string",
"name": "string",
"type": "fixed_points",
"value": 0,
"tier": "string",
"conditions": [
{
"attribute": "User Tier",
"operator": "Equals",
"value": "string"
}
],
"match": "all",
"active": true
}){
"team_id": 0,
"activity": "string",
"reward": "string",
"name": "string",
"type": "fixed_points",
"value": 0,
"tier": "string",
"conditions": [
{
"attribute": "User Tier",
"operator": "Equals",
"value": "string"
}
],
"match": "all",
"active": true
}{
"content": [
{
"type": "text",
"text": "..."
}
]
}update_rule
destructiveidempotentEarly access: this tool is only available to teams in our early access program.
Changes a rule of an activity or a reward, as returned by list_rules: its name, value, tier, conditions (which replace its conditions) or whether it's active, or archives it (removing it from list_rules, for good). It can't change a default rule (use update_default_rule) or the type of a rule (archive it and create another). Changes apply from members' next transactions.
Body
team_idintegerrequiredThe ID of the team, as returned by list_teams.
rule_idstringrequiredThe ID of the rule, as returned by list_rules.
namestringvaluenumber>= 0The points of fixed_points rules, or the multiplier of bonus_multiplier rules (points per currency unit spent).
tierstringFor assign_tier rules, the name or ID of the tier to assign, often a conditional tier (which members keep for a number of days).
conditionsArray<object>The conditions members (and their transactions, for activities) must meet. Values: numbers; dates as MM/DD/YYYY, in the time zone of the loyalty program; Between takes "MM/DD/YYYY-MM/DD/YYYY" for dates and "10#100" for numbers; the X day(s) operators take a number of days; On day(s) takes a list of English weekdays; In, Not in and Contain all/any/none of take a list; Is blank and Is not blank take none. User Tier takes tier names or IDs: Equals and one tier for activities, Contain any of or Contain none of and a list for rewards. User Tags take the tags of members (case sensitive) with Contain all/any/none of, Is blank or Is not blank. For members who purchased in the last 30 days, use Last Purchase Date, Less than X day(s) ago, 30.
matchstringallanyWhether the rule applies when members meet all its conditions (the default) or any.
activebooleanarchivedbooleantrueArchives the rule. Ignores the other changes.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "update_rule",
"arguments": {
"team_id": 0,
"rule_id": "string",
"name": "string",
"value": 0,
"tier": "string",
"conditions": [
{
"attribute": "User Tier",
"operator": "Equals",
"value": "string"
}
],
"match": "all",
"active": true,
"archived": true
}
}
}const result = await client.callTool("update_rule", {
"team_id": 0,
"rule_id": "string",
"name": "string",
"value": 0,
"tier": "string",
"conditions": [
{
"attribute": "User Tier",
"operator": "Equals",
"value": "string"
}
],
"match": "all",
"active": true,
"archived": true
});result = await session.call_tool("update_rule", arguments={
"team_id": 0,
"rule_id": "string",
"name": "string",
"value": 0,
"tier": "string",
"conditions": [
{
"attribute": "User Tier",
"operator": "Equals",
"value": "string"
}
],
"match": "all",
"active": true,
"archived": true
}){
"team_id": 0,
"rule_id": "string",
"name": "string",
"value": 0,
"tier": "string",
"conditions": [
{
"attribute": "User Tier",
"operator": "Equals",
"value": "string"
}
],
"match": "all",
"active": true,
"archived": true
}{
"content": [
{
"type": "text",
"text": "..."
}
]
}update_default_rule
destructiveidempotentEarly access: this tool is only available to teams in our early access program.
Sets the points an activity awards every member: the value of its default rule, and the activity's points. For purchases (activities with a bonus multiplier default rule), it's the points per currency unit spent, for example 10 for 10 points per dollar, and otherwise the points each time. Applies from members' next transactions. Rules can award more to some members (see create_rule).
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
activitystringrequiredargumentThe slug of the activity, as returned by list_activities.
valuenumber>= 0requiredargumentReturns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "update_default_rule",
"arguments": {
"team_id": 0,
"activity": "string",
"value": 0
}
}
}const result = await client.callTool("update_default_rule", {
"team_id": 0,
"activity": "string",
"value": 0
});result = await session.call_tool("update_default_rule", arguments={
"team_id": 0,
"activity": "string",
"value": 0
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}Tiers
list_tiers
read-onlyidempotentEarly access: this tool is only available to teams in our early access program.
Lists the tiers of the loyalty program of a team, by their minimum points, with how members reach them: members move up to the highest active tier whose minimum they reach (in points, or spend, see qualification) when they next earn points, and only rules (assign_tier, see create_rule) give them conditional tiers, for a number of days. Only the points of qualifying_activities (their slugs) count toward tiers. Also returns whether the loyalty program is live (launched), which locks its tiers except their names, descriptions and visibility.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_tiers",
"arguments": {
"team_id": 0
}
}
}const result = await client.callTool("list_tiers", {
"team_id": 0
});result = await session.call_tool("list_tiers", arguments={
"team_id": 0
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}create_tier_settings
Early access: this tool is only available to teams in our early access program.
Sets up the tiers of the loyalty program of a team that hasn't yet (see list_tiers: its period is null), so that create_tier can add them: whether they count points or spend (the amounts members spent, in the store's currency), how long those last, and which activities they come from. New members start in the active tier with 0 minimum points, so add one with create_tier. The settings can only be changed in TrueLoyal afterwards.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
qualificationstringpointsspendargumentWhat the minimum points of tiers count: the points members earned, or the amounts they spent. Defaults to points.
periodstringlife_timeperiodrequiredargumentlife_time: all the points (or spend) members ever earned from qualifying_activities count. period: only those of the current period count.
period_monthsinteger13612argumentFor the period type, how many months each period lasts. Defaults to 12.
start_monthinteger[1, 12]argumentFor the period type, the month of the year (1 for January) periods start from. Defaults to 1.
qualifying_activitiesArray<string>requiredargumentThe slugs of the activities whose points (or spend) count toward tiers (see list_activities), such as made_a_purchase. Spend only comes from made_a_purchase and submit_a_receipt activities.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "create_tier_settings",
"arguments": {
"team_id": 0,
"qualification": "points",
"period": "life_time",
"period_months": 1,
"start_month": 1,
"qualifying_activities": [
"string"
]
}
}
}const result = await client.callTool("create_tier_settings", {
"team_id": 0,
"qualification": "points",
"period": "life_time",
"period_months": 1,
"start_month": 1,
"qualifying_activities": [
"string"
]
});result = await session.call_tool("create_tier_settings", arguments={
"team_id": 0,
"qualification": "points",
"period": "life_time",
"period_months": 1,
"start_month": 1,
"qualifying_activities": [
"string"
]
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}create_tier
Early access: this tool is only available to teams in our early access program.
Adds a tier to the loyalty program of a team, unless it's live (see list_tiers). Members who already have its minimum points move up to it when they next earn points, which sends them the tier upgrade email and webhook. A conditional tier has no minimum: rules give it to members (see create_rule) for validity_days.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
namestringrequiredargumentdescriptionstringrequiredargumentWhat members see about the tier.
guest_descriptionstringargumentWhat visitors who aren't signed in see. Defaults to the description.
minimum_pointsnumber>= 0argumentThe points (or spend, see list_tiers) members need, for points-based tiers.
conditionalbooleanargumentWhether only rules give the tier (see create_rule).
validity_daysinteger>= 1argumentFor conditional tiers, how many days members keep the tier.
hiddenbooleanargumentHides the tier from members.
activebooleanargumentDefaults to true. Inactive tiers aren't given to members.
Returns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "create_tier",
"arguments": {
"team_id": 0,
"name": "string",
"description": "string",
"guest_description": "string",
"minimum_points": 0,
"conditional": true,
"validity_days": 1,
"hidden": true,
"active": true
}
}
}const result = await client.callTool("create_tier", {
"team_id": 0,
"name": "string",
"description": "string",
"guest_description": "string",
"minimum_points": 0,
"conditional": true,
"validity_days": 1,
"hidden": true,
"active": true
});result = await session.call_tool("create_tier", arguments={
"team_id": 0,
"name": "string",
"description": "string",
"guest_description": "string",
"minimum_points": 0,
"conditional": true,
"validity_days": 1,
"hidden": true,
"active": true
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}update_tier
destructiveidempotentEarly access: this tool is only available to teams in our early access program.
Changes a tier of the loyalty program of a team: its name, descriptions and visibility and, unless the program is live (see list_tiers), whether it's active and its minimum points (or the validity of a conditional tier). Members keep their tiers: changes apply when they next earn points, and members only move up, so lowering a minimum sends upgrade emails and webhooks. Rules that use an inactive tier stop applying. Tiers can't be deleted.
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
tierstringrequiredargumentThe slug of the tier, as returned by list_tiers.
namestringargumentdescriptionstringargumentguest_descriptionstringargumentminimum_pointsnumber>= 0argumentvalidity_daysinteger>= 1argumenthiddenbooleanargumentactivebooleanargumentReturns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "update_tier",
"arguments": {
"team_id": 0,
"tier": "string",
"name": "string",
"description": "string",
"guest_description": "string",
"minimum_points": 0,
"validity_days": 1,
"hidden": true,
"active": true
}
}
}const result = await client.callTool("update_tier", {
"team_id": 0,
"tier": "string",
"name": "string",
"description": "string",
"guest_description": "string",
"minimum_points": 0,
"validity_days": 1,
"hidden": true,
"active": true
});result = await session.call_tool("update_tier", arguments={
"team_id": 0,
"tier": "string",
"name": "string",
"description": "string",
"guest_description": "string",
"minimum_points": 0,
"validity_days": 1,
"hidden": true,
"active": true
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}Forms
list_forms
read-onlyidempotentEarly access: this tool is only available to teams in our early access program.
Lists the forms of a team, active ones by default, with their fields: the name submissions use for each, its label, type, whether it's required and its options. Members earn points for submitting published forms that have a form activity (see create_activity).
Parameters
team_idintegerrequiredargumentThe ID of the team, as returned by list_teams.
statusstringactivearchivedargumentDefaults to active.
publishedbooleanargumentReturns
Returns MCP content array (text, image, or embedded resource).
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_forms",
"arguments": {
"team_id": 0,
"status": "active",
"published": true
}
}
}const result = await client.callTool("list_forms", {
"team_id": 0,
"status": "active",
"published": true
});result = await session.call_tool("list_forms", arguments={
"team_id": 0,
"status": "active",
"published": true
}){
"content": [
{
"type": "text",
"text": "..."
}
]
}