Getting started with BYOA API for Custom Brain

Described below are the steps needed to get started and build, upload BYOA models and configure campaigns to evaluate bid opportunities using those models.

1. Login to MediaMath Platform API

In order to use BYOA the user needs to get an access token from MediaMath Platform. Calls to MediaMath Platform must include a client_id and client_secret. Please reach out to developers@mediamath.com so support can work with you to create these credentials for you to access the MediaMath API.

Example login using cURL

 $ curl --request POST \
  --url https://auth.mediamath.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{
  "grant_type":"password",
  "username":"email@example.com",
  "password":"<password>",
  "audience":"https://api.mediamath.com",
  "client_id":"<client_id>",
  "client_secret":"<cient_secret>"
}'

Example login using Python

data = {'grant_type': 'password',
        'username': username,
        'password': password,
        "audience": "https://api.mediamath.com/",
        "scope": "read:sample",
        'client_id': "<client_id>",
        'client_secret': "<client_secret>"}

response = requests.post('http://auth.mediamath.com/oauth/token', data=json.dumps(data), headers={'Content-Type': 'application/json'})

1.1 Login response

The following section describes how to obtain the oauth_access_token parameter referenced in the above documentation. Please reach out to developers@mediamath.com so we can work with you to create the Client ID and Client Secret for you to access the MediaMath API.

1. Login to MediaMath T1 API

   $curl --request POST \
   --url https://auth.mediamath.com/oauth/token \
   --header 'content-type: application/json' \
   --data '{
     "grant_type":"password",
     "username":"<username>",
     "password":"<password>",
     "audience":"https://api.mediamath.com/",
     "scope":"",
     "client_id":"<client_id>",
     "client_secret":"<client_secret>"
     }'

2. Verify the response contains the access token that will be used in all future requests to the T1 API.

   {
       "access_token": "<oauth_access_token>",
       "expires_in": 86400,
       "token_type": "Bearer"
   }

3. Optionally verify the expiration date of the access token by decoding the JWT or calling the session endpoint of MediaMath T1 API

   $ curl --request GET \
     --url https://api.mediamath.com/api/v2.0/session \
     --header 'Accept:application/vnd.mediamath.v1+json' \
     --header 'Authorization:"Bearer <oauth_access_token>"'

   {
     "data" : {
         "session" : {
           "current_time" : "2001-01-01T12:00:00",
           "sessionid" : "<sessionid>",
           "expires" : "2001-01-01T13:00:00"
         },
         "entity_type" : "user",
         "name" : "email@example.com",
         "id" : 21370
     },
     "meta" : {
         "status" : "ok"
     }
   }

In order to avoid unexpected errors, please pre-validate the expiration of the token

2 Uploading Model

After the user has derived a logistic model, it needs to be encoded using the flatbuffer schema. Once a model has been built and serialized, it can then be uploaded using the BYOA API. We recommend a model naming format that helps you uniquely identify the model:

Details on the model schema and approach for encoding the model using the flatbuffer compiler are provided in a dedicated section.

Example Model Names shown in following table using UNIX epoch time as a means to provide version identification.

Example model upload using cURL

curl -D -X PUT -d@./ACMECo_999999_1569332672_a.bin https://api.byoa.mediamath.com/data/<OrganizationID>/models/ACMECo_999999_1569332672_a \
  -H 'authorization: Bearer <oauth_access_token>'

3. Configuring a Campaign with a selected Model

A model can be applied to evaluate all bid opportunities across all strategies of a campaign or a single strategy of a campaign. These two scenarios are shown as examples below on how to use the BYOA API to achieve this.

Additionally, A/B split testing is available for comparing model performance across the same campaign or strategy and this advanced feature is discussed in detail in a dedicated section.

3.1 Example configuration for a Campaign using cURL

$ curl -X PUT "https://api.byoa.mediamath.com/campaign_settings/999999" \
  -d '{
    "settings": [
      {
        "executor_id": 2,
        "high": 99,
        "low": 0,
        "model_id": "<ModelName>",
        "namespace": "<OrganizationID>"
      }
    ],
    "uuid_type": "UUID"
  }' \
  -H 'authorization: Bearer <oauth_access_token>'

Note that executor_id must be set to 2. This refers to the current version of the MediaMath BYOA Model executor.

3.2 Example configuration for a Strategy using cURL

curl -X PUT "https://api.byoa.mediamath.com/campaign_settings/999999/strategies/888888" \
  -d '{
    "settings": [
      {
        "executor_id": 2,
        "high": 99,
        "low": 0,
        "model_id": "<ModelName>",
        "namespace": "<OrganizationID>"
      }
    ],
    "uuid_type": "UUID"
  }' \
  -H 'authorization: Bearer <oauth_access_token>'

Note that executor_id must be set to 2. This refers to the current version of the MediaMath BYOA Model executor.