
Treatment Management
This document provides a guide and overview for the InsertTreatment and UpdateTreatment RPCs, which allow you to insert and update treatments directly via API.
Entities
TreatmentPb
message TreatmentPb {
// Required.
string project_id = 1;
// Required.
string treatment_id = 2;
// Required.
TreatmentTypePb treatment_type = 3;
// Required.
string name = 4;
string description = 5;
// Required.
repeated TreatmentVersionPb versions = 6;
// Status of the treatment.
// Note: It's a readonly field.This value is derived from the status of the associated treatment versions.
Status status = 7;
enum Status {
STATUS_UNSPECIFIED = 0;
// If there is any version which is live and being served.
LIVE = 1;
// If there is only one version and that is in draft.
DRAFT = 2;
// If there is only one version and that is scheduled to be served in future.
SCHEDULED = 3;
// If the last LIVE version has crossed the end_timestamp of it's lifetime.
ARCHIVED = 4;
// If the treatment has been paused manually.
PAUSED = 5;
}
string last_modified_by = 8;
.google.protobuf.Timestamp last_modified_timestamp = 9;
ModificationSource modification_source = 10;
enum ModificationSource {
MODIFICATION_SOURCE_UNSPECIFIED = 0;
AUXIA_CONSOLE = 1;
API = 2;
}
// Optional.
// External Treatment Id, that is a primary key in the customer's system.
string external_treatment_id = 11;
// Optional.
optional MutualExclusionGroupPb mutual_exclusion_group = 12;
}
TreatmentVersionPb
message TreatmentVersionPb {
// Note: It's a readonly field. Status is calculated as per the launch config details.
Status status = 1;
repeated TagPb tags = 2;
.google.protobuf.Timestamp start_timestamp = 3;
.google.protobuf.Timestamp end_timestamp = 4;
ContentPb content = 5;
enum Status {
STATUS_UNSPECIFIED = 0;
LIVE = 1;
DRAFT = 2;
SCHEDULED = 3;
ARCHIVED = 4;
}
EligibilityRulesListPb eligibility_rules = 6;
// Removed Surfaces associated with this treatment version.
RemovedSurfacesListPb removed_surfaces = 7;
TargetActionPb target_action = 8;
}
TagPb
message TagPb {
string name = 1;
}
ContentPb
// Treatment content.
message ContentPb {
repeated ContentByLanguagePb content_by_language = 1;
repeated TreatmentContentFieldPb language_agnostic_content_fields = 2;
message ContentByLanguagePb {
LanguageCodePb language_code = 1;
repeated TreatmentContentFieldPb content_fields = 2;
}
message TreatmentContentFieldPb {
// Note: It has to be one of the fields from associated treatment type. Otherwise, error would be thrown.
string field_name = 1;
oneof field_value {
string string_value = 2;
}
}
message LanguageCodePb {
// Note: It has to be one of the supported language codes. Otherwise,error would be thrown.
string language_code = 1;
}
}
TargetActionPb
message TargetActionPb {
int64 event_id = 1;
}
EligibilityRulesPb
message EligibilityRulesListPb {
repeated EligibilityRulePb rules = 1;
}
MutualExclusionGroupPb
message MutualExclusionGroupPb {
int64 project_id = 1;
int64 mutual_exclusion_group_id = 2;
string name = 3;
}
message RemovedSurfacesListPb {
repeated SurfacePb surfaces = 1;
}
TreatmentTypePb
// Treatment Type defines the content fields and restrictions for the treatment.
message TreatmentTypePb {
// Project ID to which this treatment type belongs to.
// Required.
string project_id = 1;
// Name of the treatment type.
// Required.
string name = 2;
// Field to specify the delivery mode of this treatment type
// Required.
DeliveryType delivery_type = 3;
// List of language specific content fields.
// Required.
repeated TreatmentContentFieldTypePb language_specific_content_field_types = 4;
// List of language agnostic content fields. For example, cta_link, image_url.
// Required.
repeated TreatmentContentFieldTypePb language_agnostic_content_field_types = 5;
// List of surfaces where this treatment type can be displayed.
repeated SurfacePb surfaces = 6;
}
message SurfacePb {
// Required.
string name = 1;
}
message TreatmentContentFieldTypePb {
// Name of the content field.
// Required.
string field_name = 1;
// Allowed length of the content field.
// Required.
int32 value_length_limit = 2;
// Data type of the content field.
// Required.
ContentFieldDataType data_type = 3;
}
enum ContentFieldDataType {
CONTENT_FIELD_DATA_TYPE_UNSPECIFIED = 0;
STRING = 1;
}
enum DeliveryType {
DELIVERY_TYPE_UNSPECIFIED = 0;
EMAIL = 1;
IN_APP = 2;
NOTIFICATION = 3;
}
EligibilityRulePb
message EligibilityRulePb {
// Required.
int64 data_field_id = 1;
// Required.
Condition condition = 2;
// Required.
string rhs_value = 3;
}
enum Condition {
UNSPECIFIED_CONDITION = 0;
LESS_THAN = 1;
LESS_THAN_OR_EQUALS = 2;
GREATER_THAN = 3;
GREATER_THAN_OR_EQUALS = 4;
EQUALS = 5;
NOT_EQUALS = 6;
}
DataFieldParams
message DataFieldParams {
// Required
oneof params {
UserAttributeDataFieldParams user_attribute_data_field_params = 1;
TreatmentDataFieldParams treatment_data_field_params = 2;
EventDataFieldParams event_data_field_params = 3;
}
// User Attribute Params
message UserAttributeDataFieldParams{
// Required
string property_name = 1;
}
// Treatment Interaction Metrics Params
message TreatmentDataFieldParams {
// Required
TreatmentInteractionType treatment_interaction_type = 1;
// Optional
oneof aggregate_by {
string treatment_id = 2;
string surface_id = 3;
}
bool is_distinct_interaction = 4;
// Required
oneof aggregation {
DailyCountAggregation daily_count_aggregation = 5;
FirstTimestampAggregation first_timestamp_aggregation = 6;
LatestTimestampAggregation latest_timestamp_aggregation = 7;
DaysSinceFirstTimestampAggregation days_since_first_timestamp_aggregation = 8;
DaysSinceLastTimestampAggregation days_since_last_timestamp_aggregation = 9;
}
enum TreatmentInteractionType {
TREATMENT_INTERACTION_TYPE_UNSPECIFIED = 0;
SENT = 1;
VIEWED = 2;
CLICKED = 3;
SNOOZED = 4;
DISMISSED = 5;
CTA_COMPLETED = 6;
SWIPE = 7;
}
}
// Event Metric Params
message EventDataFieldParams {
// Required
string event_schema_name = 1;
// Optional
map<string, PropertyValuePb> property_value_by_property_name = 2;
// Required
oneof aggregation {
DailyCountAggregation daily_count_aggregation = 3;
FirstTimestampAggregation first_timestamp_aggregation = 4;
LatestTimestampAggregation latest_timestamp_aggregation = 5;
DaysSinceFirstTimestampAggregation days_since_first_timestamp_aggregation = 6;
DaysSinceLastTimestampAggregation days_since_last_timestamp_aggregation = 7;
}
}
// Property Value
message PropertyValuePb {
oneof property_value {
int64 long_value = 1;
double double_value = 2;
string string_value = 3;
bool boolean_value = 4;
google.protobuf.Timestamp timestamp_value = 5;
}
}
}
message FirstTimestampAggregation {}
message LatestTimestampAggregation {}
message DaysSinceFirstTimestampAggregation {}
message DaysSinceLastTimestampAggregation {}
ResolvedDataFieldPb
message ResolvedDataFieldPb {
int64 data_field_id = 1;
DataFieldParams data_field_params = 2;
string data_field_type = 3;
}
InsertTreatment
API to create a new treatment
message InsertTreatmentRequest {
// Required.
string project_id = 1;
// Required.
// Metadata of the treatment.
string name = 2;
// Required.
string description = 3;
// Optional.
optional TargetActionPb target_action = 15;
// Required.
string treatment_type_name = 4;
// Optional.
// Surfaces which should be ineligible for the treatment.
// Values in removed_surfaces must exactly match surface names.
optional RemovedSurfacesListPb removed_surfaces = 14;
// Required.
string last_modified_by = 5;
// Required.
// Details related to treatment launch like start time and end time of the treatment.
// Start time of the treatment.
.google.protobuf.Timestamp start_timestamp = 6;
// Optional.
// End time of the treatment. If this field is unset, treatment will never end.
.google.protobuf.Timestamp end_timestamp = 7;
// Required.
// Content of the treatment.
ContentPb content = 8;
// Optional.
// Tags to be linked to this treatment.
repeated TagPb tags = 9;
// Optional.
// External Treatment Id, that is a primary key in the customer's system.
optional string external_treatment_id = 10;
// Optional.
// If true, it publishes the treatments.
optional bool should_publish = 11;
// Optional.
// Note: If eligibility_rules is unset, the existing rules remain unchanged.
// If set (even as an empty list), it replaces any previously stored rules for this treatment.
optional EligibilityRulesListPb eligibility_rules = 12;
// Optional.
// Note: Sending an empty string would overwrite and clear mutual_exclusion_group
// from this treatment.
optional string mutual_exclusion_group = 13;
}
message InsertTreatmentResponse {
TreatmentPb treatment = 1;
}
Sample cURL Request
curl --location --request POST 'https://apis.auxia.io/v1/InsertTreatment' \
--header 'Content-Type: application/json' \
--header 'x-api-key: TEST_API_KEY' \
--data-raw '{
"project_id": "PROJECT_ID",
"name": "CCB treatment",
"description": "Treatment to promote books category",
"treatment_type_name": "IN_APP_CONTENT",
"last_modified_by": "USER_EMAIL",
"start_timestamp": "2017-01-15T01:30:15.010Z",
"end_timestamp": "2027-01-15T01:30:15.010Z",
"content": {
"content_by_language": [
{
"language_code": {
"language_code": "en"
},
"content_fields": [
{
"field_name": "title",
"string_value": "50% off"
}
]
}
],
"language_agnostic_content_fields": []
},
"tags": [
{
"name": "christmas_coupons"
}
],
"external_treatment_id": "EXTERNAL_TREATMENT_ID",
"should_publish": true,
"target_action": {
"event_id": 123
},
"eligibility_rules": {
"rules": [
{
"data_field_id": 1,
"condition": "GREATER_THAN",
"rhs_value": "18"
},
{
"data_field_id": 2,
"condition": "EQUALS",
"rhs_value": "US"
}
]
},
"mutual_exclusion_group": "MUTUAL_EXCLUSION_GROUP",
"removed_surfaces": {
"surfaces": [
{
"name": "SURFACE"
}
]
}
}'
Sample Response
{
"treatment": {
"projectId": "PROJECT_ID",
"treatmentId": "TREATMENT_ID",
"treatmentType": {
"projectId": "PROJECT_ID",
"name": "IN_APP_CONTENT_CARD",
"deliveryType": "IN_APP",
"languageSpecificContentFieldTypes": [
{
"fieldName": "title",
"valueLengthLimit": 50,
"dataType": "STRING"
},
{
"fieldName": "cta_name",
"valueLengthLimit": 100,
"dataType": "STRING"
},
{
"fieldName": "body",
"valueLengthLimit": 100,
"dataType": "STRING"
}
],
"languageAgnosticContentFieldTypes": [
{
"fieldName": "cta_link",
"valueLengthLimit": 100,
"dataType": "STRING"
},
{
"fieldName": "image_link",
"valueLengthLimit": 200,
"dataType": "STRING"
}
],
"surfaces": [
{
"name": "SURFACE"
}
]
},
"name": "Coupon treatment",
"description": "Coupons for Christmas",
"versions": [
{
"status": "DRAFT",
"tags": [
{
"name": "christmas_coupons"
}
],
"start_timestamp": "2017-01-15T01:30:15.010Z",
"end_timestamp": "2027-01-15T01:30:15.010Z",
"content": {
"contentByLanguage": [
{
"languageCode": {
"languageCode": "en"
},
"contentFields": [
{
"fieldName": "title",
"stringValue": "50% off"
}
]
}
]
},
"eligibilityRules": {
"rules": [
{
"dataFieldId": 1,
"condition": "GREATER_THAN",
"rhsValue": "18"
},
{
"dataFieldId": 2,
"condition": "EQUALS",
"rhsValue": "US"
}
]
},
"removedSurfaces": {
"surfaces": [
{
"name": "SURFACE"
}
]
},
"targetAction": {
"eventId": "123"
}
}
],
"status": "LIVE",
"external_treatment_id": "EXTERNAL_TREATMENT_ID",
"lastModifiedBy": "USER_EMAIL",
"lastModifiedTimestamp": "2025-05-30T11:32:44.279Z",
"modificationSource": "API",
"mutualExclusionGroup": {
"projectId": "PROJECT_ID",
"mutualExclusionGroupId": "62",
"name": "MUTUAL_EXCLUSION_GROUP"
}
}
}
UpdateTreatment
API to update an existing treatment.
message UpdateTreatmentRequest {
// Required.
string project_id = 1;
// Required.
string treatment_id = 2;
// Optional.
optional string name = 3;
// Optional.
optional string description = 4;
// Optional.
optional TargetActionPb target_action = 15;
// Optional.
// Specifies surfaces that should be ineligible for the treatment.
// Values in removed_surfaces must exactly match surface names.
optional RemovedSurfacesListPb removed_surfaces = 14;
// Required.
string last_modified_by = 5;
// Optional.
.google.protobuf.Timestamp start_timestamp = 6;
// Optional.
.google.protobuf.Timestamp end_timestamp = 7;
// Optional.
// Content of the treatment.
optional ContentPb content = 8;
// Optional.
// Tags to be linked to this treatment.
// Note: Sending an empty list of tags would overwrite and clear all tags from this treatment.
repeated .io.auxia.decision.model.TagPb tags = 9;
// Optional.
// Either treatment_id or external_treatment_id are required.
// External Treatment Id, that is a primary key in the customer's system.
optional string external_treatment_id = 10;
// Optional.
// If true, it publishes the treatments.
optional bool should_publish = 11;
// Optional.
// Note: If eligibility_rules is unset, the existing rules remain unchanged.
// If set (even as an empty list), it replaces any previously stored rules for this treatment.
optional EligibilityRulesListPb eligibility_rules = 12;
// Optional.
// Note: Sending an empty string would overwrite and clear mutual_exclusion_group
// from this treatment.
optional string mutual_exclusion_group = 13;
}
message UpdateTreatmentResponse {
TreatmentPb treatment = 1;
}
Sample cURL Request
curl --location --request POST 'https://apis.auxia.io/v1/UpdateTreatment' \
--header 'Content-Type: application/json' \
--header 'x-api-key: TEST_API_KEY' \
--data-raw '{
"project_id": "PROJECT_ID",
"treatment_id": "TREATMENT_ID",
"last_modified_by": "USER_EMAIL",
"name": "Coupon treatment",
"description": "Coupons for Christmas",
"tags": [
{
"name": "christmas_coupons"
}
],
"content": {
"content_by_language": [
{
"language_code": {
"language_code": "en"
},
"content_fields": [
{
"field_name": "title",
"string_value": "50% off"
}
]
}
],
"language_agnostic_content_fields": [
{
"field_name": "cta_link",
"string_value": "http://cta_link"
}
]
},
"target_action": {
"event_id": 123
},
"eligibility_rules": {
"rules": [
{
"data_field_id": 1,
"condition": "GREATER_THAN",
"rhs_value": "18"
},
{
"data_field_id": 2,
"condition": "EQUALS",
"rhs_value": "US"
}
]
},
"mutual_exclusion_group": "MUTUAL_EXCLUSION_GROUP",
"removed_surfaces": {
"surfaces": [
{
"name": "SURFACE"
}
]
}
}'
Sample Respone
{
"treatment": {
"projectId": "PROJECT_ID",
"treatmentId": "TREATMENT_ID",
"treatmentType": {
"projectId": "PROJECT_ID",
"name": "IN_APP_CONTENT_CARD",
"deliveryType": "IN_APP",
"languageSpecificContentFieldTypes": [
{
"fieldName": "title",
"valueLengthLimit": 50,
"dataType": "STRING"
},
{
"fieldName": "cta_name",
"valueLengthLimit": 100,
"dataType": "STRING"
},
{
"fieldName": "body",
"valueLengthLimit": 100,
"dataType": "STRING"
}
],
"languageAgnosticContentFieldTypes": [
{
"fieldName": "cta_link",
"valueLengthLimit": 100,
"dataType": "STRING"
},
{
"fieldName": "image_link",
"valueLengthLimit": 200,
"dataType": "STRING"
}
],
"surfaces": [
{
"name": "SURFACE"
}
]
},
"name": "Coupon treatment",
"description": "Coupons for Christmas",
"versions": [
{
"status": "DRAFT",
"tags": [
{
"name": "christmas_coupons"
}
],
"start_timestamp": "2017-01-15T01:30:15.010Z",
"end_timestamp": "2027-01-15T01:30:15.010Z",
"content": {
"contentByLanguage": [
{
"languageCode": {
"languageCode": "en"
},
"contentFields": [
{
"fieldName": "title",
"stringValue": "50% off"
}
]
}
],
"languageAgnosticContentFields": [
{
"fieldName": "cta_link",
"stringValue": "http://cta_link"
}
]
},
"eligibilityRules": {
"rules": [
{
"dataFieldId": 1,
"condition": "GREATER_THAN",
"rhsValue": "18"
},
{
"dataFieldId": 2,
"condition": "EQUALS",
"rhsValue": "US"
}
]
},
"removedSurfaces": {
"surfaces": [
{
"name": "SURFACE"
}
]
},
"targetAction": {
"eventId": "123"
}
}
],
"status": "DRAFT",
"external_treatment_id": "EXTERNAL_TREATMENT_ID",
"lastModifiedBy": "USER_EMAIL",
"lastModifiedTimestamp": "2025-05-30T11:32:44.279Z",
"modificationSource": "API",
"mutualExclusionGroup": {
"projectId": "PROJECT_ID",
"mutualExclusionGroupId": "1",
"name": "MUTUAL_EXCLUSION_GROUP"
}
}
}
GetDataFields
API to get DataField Parameters
message GetDataFieldsByParamsRequest {
// Required
string project_id = 1;
// Required
repeated DataFieldParams data_field_params = 2;
}
message GetDataFieldsByParamsResponse {
repeated ResolvedDataFieldPb data_fields = 1;
}
Sample cURL Request
curl --location --request POST 'https://apis.auxia.io/v1/GetDataFields' \
--header 'Content-Type: application/json' \
--header 'x-api-key: API_KEY' \
--data-raw '{
"project_id": "PROJECT_ID",
"data_field_params": [
{
"treatment_data_field_params": {
"treatmentId": "TREATMENT_ID",
"treatment_interaction_type": "VIEWED",
"daily_count_aggregation": {
"window_name": "LAST_1D"
}
}
},
{
"event_data_field_params": {
"eventSchemaName": "Stream Finished",
"propertyValueByPropertyName": {
"duration_seconds": {
"long_value": 1800
},
"daily_count_aggregation": {
"window_name": "LAST_14D"
}
}
},
{
"user_attribute_data_field_params": {
"property_name": "signup_completed_timestamp_seconds"
}
}
]
}'
Sample Response
{
"dataFields": [
{
"dataFieldId": "1",
"dataFieldParams": {
"treatmentDataFieldParams": {
"treatmentInteractionType": "VIEWED",
"treatmentId": "TREATMENT_ID",
"dailyCountAggregation": {
"windowName": "LAST_1D"
}
}
},
"dataFieldType": "INTEGER"
},
{
"dataFieldId": "2",
"dataFieldParams": {
"eventDataFieldParams": {
"eventSchemaName": "Stream Finished",
"propertyValueByPropertyName": {
"duration_seconds": {
"longValue": 1800
}
},
"dailyCountAggregation": {
"windowName": "LAST_14D"
}
}
},
"dataFieldType": "INTEGER"
},
{
"dataFieldId": "3",
"dataFieldParams": {
"userAttributeDataFieldParams": {
"propertyName": "signup_completed_timestamp_seconds"
}
},
"dataFieldType": "TIMESTAMP_SECONDS"
}
]
}