Crosstalk Programmatic API

Last updated: August 6 2018

Overview

The Crosstalk-API allows you to programmatically interact with the RTB4FREE bidding system, and the campaigns/creatives loaded within it using JSON based HTTP POST access. The commands are simple JSON objects, and, the returned values are also JSON.

The paradigm is transactional - you issue a command, and then a response is returned to you. All commands are done via POST. Each command requires a separate username and password token. With the API you can query the RTB bidders (individually or collectively) for their status, and what campaigns are loaded within each bidder.

You can also stop and start selected bidders, or all the bidders collectively. The API also allows you to dynamically change prices within campaign/creatives, load new campaigns, or delete campaigns. The API can also be used to find out the current spending limits on campaigns, and you can set new spending limits.

The default port for Crosstalk-API is 8100.

System Status

The System status commands are used to determine the health of the Crosstalk system and of the bidders on the network.

Ping Crosstalk

This command will ping the Crosstalk server. It simply responds with the current time on successful return. If Crosstalk does not answer within 5 minutes then the command will time out.

The form of the command is:

{ "username:" "xxx", "password": "yyy", "type": "Ping#"}
									 

An example command response might look like this:

{"error":false,"timestamp":1490805236618,"type":"Ping#"}

The key fields are error, which here indicates no error, and timestamp, which is the UTC of the response.

Get Crosstalk Status

The GetStatus command will return the operational status of the bidder and all of the campaigns loaded within them. There are 2 forms of the command. GetStatus for all the bidders, and, GetStatus for an individual bidder.

The form of the get all bidders status is:

{ "username:" "xxx", "password": "yyy", "type": "GetStaus#"}
									

The return will show the status of all the bidders the Crosstalk system knows about. Here's an example:

{
	"error": false,
	"message": "ok",
	"timestamp": 1490805520438,
	"refreshList": [{
		"bidder": "carbon-x1:8080",
		"stopped": false,
		"message": "undefined",
		"campaigns": ["7"]
	},{
		"bidder": "raspberryPI:8080",
		"stopped": false,
		"message": "undefined",
		"campaigns": ["7"]
	}],
	"type": "GetStatus#"
}									
									

Here we see the refreshList contains an array of bidder statuses. There are 2 bidders, each loaded with Campaign 7. Bith are in run mode (bidding)

The form of the command for getting the status of a single bidder is:

{ "username:" "xxx", "password": "yyy", "bidder": "bidder1:8080", "type": "GetStaus#"}
									

All you need to do is simply add the "bidder" target to get the status for all the bidders. The example command is:

{"username":"ben","password":"xyz","bidder":"carbon-x1:8080","type":"GetStatus#"}
									

Here is the response:

{
	"error": false,
	"timestamp": 1490805520438,
	"refreshList": [{
		"bidder": "carbon-x1:8080",
		"stopped": false,
		"message": "undefined",
		"campaigns": ["7"]
	}],
	"type": "GetStatus#"
}									

Get Bidders Status

This command will return the performance characteristics of all the bidders controlled by this crosstalk, as an array of hashmaps, one for each bidder.

The form of the command is:

{ "username:" "xxx", "password": "yyy", "type": "GetBiddersStatus#"}
									 

An example command response might look like this:

TBD
									 

The key fields are error, which here indicates no error, and timestamp, which is the UTC of the response.

Future Command

Some forms of the Crosstalk API have asynchronous forms, such as Update and Refresh. These commands may take some time to execute, so you can add a field "async": true to the JSON of these commands. When the async flag is present and the value is true, then the command will execute but immediately return with a status value in the response called 'asyncid'.

The asyncid is used with the Future command. Sending a Future command with the asyncid will return either the value of the command that executed with that id, or it will return a Future response stating the status is not completed. Here's an example transaction:

First we send the Refresh command with the async flag turned on:

{"timestamp":1492815502992,"async":true,"type":"Refresh#"}

The Refresh responds with a Future asyncid:

{"timestamp":1492815096600,"async":true,"asyncid":-889275714,"type":"Refresh#"}

Sometime later we issue the Future command:

{"asyncid":-889275714,"type":"Future#"]}

And the future command returns the completed command value:

{"timestamp":1492815502992,"async":true,"asyncid":-889275714,"type":"Refresh#","updated":["6","3"]}

Bidder Control

The bidder control commands are StartBidder and StopBidder. You can stop and start all the bidders on the network, or, you can issue the commands to an individual bidder.

Start Bidder

The Start Bidder command tells Crosstalk to start previously stopped bidders. A stopped bidder is still running, but it will not bid on any requests. You can start a particular bidder, all bidders, or use a wildcard to start a subset of bidders. The following will start any bidder on the network that has previously been stopped:

{ "username:" "xxx", "password": "yyy", "type": "StartBidder#"}

To start a particular bidder add the bidder parameter. For example to start bidder3 use:

{ "username:" "xxx", "password": "yyy", "bidder": "bidder3", "type": "StartBidder#"}

To start a subset of bidders, use a JAVA regular expression. See the wildcard section for details.

Stop Bidder

The Stop Bidder command tells Crosstalk to stop running bidders. A running bidder is capable of bidding, unless it is stopped. You can stop a particular bidder, all bidders, or use a wildcard to stop a subset of bidders. The following will stop any bidder on the network:

{ "username:" "xxx", "password": "yyy", "type": "StopBidder#"}

To start a particular bidder add the bidder parameter. For example to start bidder3 use:

{ "username:" "xxx", "password": "yyy", "bidder": "bidder3", "type": "StopBidder#"}

To start a subset of bidders, use a JAVA regular expression. See the wildcard section for details.

Refresh Campaigns

The Refresh command tells Crosstalk to check SQL for new, deleted or updated commands. Normally Crosstalk looks for updates once a minute, but this command makes it scan the SQL tables immediately. The following is an example of the Refresh:

{ "username:" "xxx", "password": "yyy", "type": "Refresh#"}
									

The command can take awhile to complete execution. You can add an async flag: "async":true to the command and the command will immediately return with a future asyncid that you can use with the Future command to retrieve the complete status later, The following shows the interaction using the async flag.

{ "username:" "xxx", "password": "yyy", "type": "Refresh#","async:"true}

The response will look something like:

{"timestamp":1492815502992,"async":true,"asyncid":-889275714,"type":"Refresh#"}

Use the asyncid in a Future command to retrieve the results of this command later.

Update Campaign

The Update command tells Crosstalk to add a campaign to the bidders. This is unlike the Refresh command that loads all eligible campaigns into the bidders.

{ "username:" "xxx", "password": "yyy", "type": "Update#", "campaign":"14"}
									

The command can take awhile to complete execution. You can add an async flag: "async":true to the command and the command will immediately return with a future asyncid that you can use with the Future command to retrieve the complete status later, The following shows the interaction using the async flag.

{ "username:" "xxx", "password": "yyy", "type": "Update#","async:"true}

The response will look something like:

{"timestamp":1492815502992,"async":true,"asyncid":-889275794,"type":"Update#"}

Use the asyncid in a Future command to retrieve the results of this command later.

Price Control

You can retrieve the current price for a campaign/creative using the GetPrice command. You can dynamically change the price of a campaign/creative using SetPrice. SetPrice immediately changes the price of the Campaign/Creative in all the bidders on the network.

Get Price

The Get Price command is used to query the current price of an indicated Campaign and Creative. The following is the form of the command:

{ "username:" "xxx", "password": "yyy", "campaign" "7", "creative": "9", "type": GetPrice#"}

An example response is shown below:

{"error":false,"timestamp":1490809798570,"type":"GetPrice#","campaign":"7","creative":"9","price":1.0}

Sometimes you might see no price, but you do see an array of deals with a list of ids and prices. These are all deals for a private auction. Sometimes you might see a price and an array of deals. This is a preferred auction. Here's an example of a preferred deal:

{"error":false,"timestamp":1490809798570,"type":"GetPrice#","campaign":"7","creative":"9","price":1.0, "deals":[{"id":""36663", "price": .001}]}

Set Price

The Set Price command is used to dynamically change the price in the Bidders for an indicated Campaign/Creative. Note, this command does not update the SQL tables. This is a real time update only. Note, a change to the same Campaign in SQL will over-write the price. With this command you designate the Campaign, Creative and new Price. Optionally you can designate which bidder is to receive the command, otherwise all bidders are instructed to make the price change, if the campaign is loaded in the indicated bidder. The following is the form of the command:

{ "username:" "xxx", "password": "yyy", "campaign" "5", "creative": "9", "price": .223, "type": SetPrice#"}

An example response is shown below:

{"error":false,"timestamp":1490809798570,"type":"SetPrice#","campaign":"7","creative":"9","price":.223}

If the campaign/creative is only participating in a private auction, you may set the price of the private deal. You cannot add an open auction price or add a deal that does not already exist. Here's an example of changing a deal "22321" to a price of 2.1:

{ "username:" "xxx", "password": "yyy", "campaign" "5", "creative": "9", "deal": "22321", "price": .223, "type": SetPrice#"

If you are changing multiple deal prices, it takes multiple API calls, one for each deal. If you are changing the public auction price, you need to make a separate call for that too.

After you set the price, for it to take effect in the bidders, you must issue an Update command.

Campaign Management

The Campaign Management system allows you to read and write the JSON based campaign definitions in the bidders. Note, this is outside of the Campaign Manager User Interface provided through Crosstalk. Usually, one would use one or the other of these systems to manage campaigns, but, not both simultaneously. Otherwise this would cause confusion.

List Campaigns

This command allows you to get list of running campaigns in the system. It returns a list of campaigns as an array of strings that denote the campaign ids. Note, this is not necesarially all the campaigns defined in the SQL database of the Campaign Manager..

{ "username": "xxx", "password:: "yyy", "campaign": "10",  "type": "ListCampaigns#"}
									

The following shows an example of the list campaigns command response:

{
	"error": false,
	"timestamp": 1490822451851,
	"type": "ListCampaigns#",
	"campaigns": ["7", "9", "12", "32"]
}

If an error occurs, there will be an "error": true attribute, and an error "message" attribute to document the error

Get Reason

This command reports on the reason why a campaign is not loadable into the bidder, for one reason or another. This command is useful when you think a Campaign should load from the campaign manager, but it won't. Use this command to find out why.

There are two forms of the command, one to list the reason for a single campaign, and one to list the reasons for all campaigns.

Get the reason for a single campaign, id number 10:

{ "username": "xxx", "password:: "yyy", "campaign": "10", "type": "GetReason#"}
									

The following shows an example of the GetReason command response:

{
	"error": false,
	"timestamp": 1490822451851,
	"type": "GetReason#",
	"reason": "Hourly budget exceeded"
}

If you provide a campaign id unknown to Crosstalk it will return "Unknown campaign" as the reason.

To get all the unloadable campaigns and their reasons, simply omit the campaign, like this:

{ "username": "xxx", "password:: "yyy", "type": "GetReason#"}
									

The command will return a "reasons" array of objects. Each object is a campaign and a reason. Here is a sample output

{
	"error": false,
	"timestamp": 1490822451851,
	"type": "GetReason#",
	"reasons": [
		{ "10": "Hourly budget exceeded" },
		{ "20": "Start time expired" },
		{ "30": "No creatives"}
	]
}

If an error occurs, there will be an "error": true attribute, and an error "message" attribute to document the error

Add Campaign

This command will add a new campaign to the bidders, loaded from the MySQL database (As defined by the Campaign Manager). This does not add a new campaign to the database. Note, if the campaign already exists in the bidders, it is replaced.

{ "username": "xxx", "password:: "yyy", "campaign": "10", "type": "AddCampaign#"}
									

The following is an example of the AddCampaign response after it was added

{
	"error": false,
	"timestamp": 1490822451851,
	"type": "AddCampaign#",
	"campaign": "7",
	"updated": "Campaign 7 loaded ok"
}

If an error occurs, there will be an "error": true attribute, and an error "message" attribute to document the error

Delete Campaign

This command deletes a campaign from the bidders.

{ "username": "xxx", "password:: "yyy", "campaign": "10",  "type": "DeleteCampaign#"}
									

The following shows an example of the command response.

{
	"error": false,
	"timestamp": 1490822451851,
	"type": "DeleteCampaign#",
	"campaign": "7",
	"updated": "Campaign 7 deleted ok"
}

If an error occurs, there will be an "error": true attribute, and an error "message" attribute to document the error

Get Budget

This command will get the budgets currently allocated to the campaign and for the creatives assigned to it.

Th campaign has a budget, and each creative has a budget too. If you don't specify a creative, the campaign budget is returned. Passing the campaign and the creative returns the budget for the creative.

{"username":"ben","password":"xyz","type":"GetBudget#","campaign":"7"}

The return values will look similar to this:

{
	"error": false,
	"timestamp": 1490822451851,
	"type": "GetBudget#",
	"campaign": "7",
	"budget_limit_daily": 1000.0,
	"budget_limit_hourly": 1000.0,
	"total_budget": 10000.0
}

Here is a response for a GetBudget for campaign 7, creative 9:

{
	"error": false,
	"timestamp": 1490823345863,
	"type": "GetBudget#",
	"campaign": "7",
	"creative": "9",
	"budget_limit_daily": 1000.0,
	"budget_limit_hourly": 1000.0,
	"total_budget": 10000.0
}									
									

If an error occurs, there will be an "error": true attribute, and an error "message" attribute to document the error

Set Budget

Use this command to update the budget currently allocated to a campaign and the creatives assigned to it,

If you do not specify a creative, the campaign budget is updated, otherwise the campaign's creative budget is updated.


									

If an error occurs, there will be an "error": true attribute, and an error "message" attribute to document the error

Get Budget Values

This command retrieves the current camapgign or campaign/creative current running budget values. If you specify just the campaign, the campaign's current spend is shown. Otherwise, if the campaign and creative are both specified, the campaign's creative current spend is displayed.


									

If an error occurs, there will be an "error": true attribute, and an error "message" attribute to document the error

Get Budget Values

This command sets the current campgaign or campaign/creative current running budget values. If you specify just the campaign, the campaign's current spend is modified. Otherwise, if the campaign and creative are both specified, the campaign's creative current spend is displayed.


									

If an error occurs, there will be an "error": true attribute, and an error "message" attribute to document the error

Symbol Management

Symbols are loaded from S3 as data sets. You can list symbols, add symbols and delete symbols.

List Symbols

This command allows you to get list of running campaigns in the system. It returns a list of campaigns as an array of strings that denote the campaign ids. Note, this is not necesarially all the campaigns defined in the SQL database of the Campaign Manager..

{ "username": "xxx", "password:: "yyy", "campaign": "10",  "type": "ListSmbols#"}
									

The following shows an example of the list campaigns command response:

{
	"error": false,
	"timestamp": 1490822451851,
	"type": "ListSymbols#"
}

If an error occurs, there will be an "error": true attribute, and an error "message" attribute to document the error

Load Symbol

The ConfigureAwsObject command tells the bidders to load an S3 object into memory.

{ "username": "xxx", "password:: "yyy", "campaign": "10",  "type": "ConfigureAws#"}
									

The following shows an example of the list campaigns command response:

{
	"error": false,
	"timestamp": 1490822451851,
	"type": "ConfigureAws#",
	"message": "AWS Object loaded ok"
}

If an error occurs, there will be an "error": true attribute, and an error "message" attribute to document the error

Remove Symbol

This command allows you to delete a symbol name from the system.

{ "username": "xxx", "password:: "yyy", "campaign": "10",  "type": "RemoveSymbol#", "symbol": "$blocked_ips"}
									

The following shows an example of the remove symbol command response:

{
	"error": false,
	"timestamp": 1490822451851,
	"type": "RemoveSymbol#",
	"message": "OK"
}

If an error occurs, there will be an "error": true attribute, and an error "message" attribute to document the error

Wildcard Addresses

In all commands of the Crosstalk API there is an optional bidder field. Leaving this field off means the command is directed to all bidders on the network. Specifying a bidder name means just that bidder is addressed.

However, you can address a subset of bidders using the JAVA REGEX expressions. To understand JAVA regex, here is a good resource.

If you had 3 bidders, bidder1, bidder2 and bidder3 and wanted to send a command to just bidders 1 and 3 you could send 2 separate commands to bidder1 and bidder3, or you could use a wildcard like this:

bidder[13]

Alternatively you could use:

bidder[^2]

Here's an example SetPrice command using one of the modifiers to load all bidders except bidder2:

{ "username:" "xxx", "password": "yyy", "bidder": "bidder[^2]",
	"campaign": "10", "creative": "23", "price": 1.23, 
	"type": "SetPrice#"}
									

If an error occurs, there will be an "error": true attribute, and an error "message" attribute to document the error

Examples

The following are examples on how to use the Crosstalk API using Curl, Javascript/JQuery and JAVA. An example SetPrice command is shown using all three technologies.

For example purposes, the address of the Crosstalk-API will be http://crosstalk-api:8100/api. The username we will use is dorothy. The password we will use is ihatemedicalschool. There are three bidders on the network, named bidder1, bidder2, and bidder3

Curl

First make sure you have CURL installed on your system. You will be using an external file to hold the command, since the CURL command will do a POST.

Now make a file, called setprice.json with the following contents:

{ "username:" "dorothy", "password": "ihatemedicalschool", "campaign": "10", "creative": "23", "price": 1.23, "type": "SetPrice#"}									
									

Now you can execute the curl command as follows:

$curl -X POST -d @./setprice.json http://crosstalk-api:8100/api --header "Content-Type:application/json"
									

JQuery

<head> <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script> ... </head> ... <script> $.ajax({ type: 'POST', url: 'http://crosstalk-api:8100/api', data: '{ "username:" "dorothy", "password": "ihatemedicalschool", "campaign": "10", "creative": "23", "price": 1.23, "type": "SetPrice#"}', success: function(data, textStatus, request){ console.log(JSON.stringify(data, null, 2)); }, error: function (request, textStatus, errorThrown) { alert(textStatus); }}) </script>

JAVA

import com.xrtb.crosstalk.api.GetStatusCmd; ... SetPriceCmd newPrice = new SetPriceCmd("dorothy","ihatemedicalschool","10","23", 1.23); SetPriceCmd response = newPrice.execute(); System.out.println(response);

Shell tools/api

A Shell command called tools/api is provided to allow you to send Crosstalk-API commands. The basic form of the cmmand is:

tools/api http://yourhost:8100    [options]
									

The options depend on the command. The following are examples of the various command formats.

Python Tool

A python script called crosstalk.py is available to send commands to a Crosstalk system. The control flow is you first set a crosstalk host, and then you can issue the commands. Look in the crosstalk.py file for further details, but heres a sample use:

$python
>>> import crosstalk
>>> crosstalk.SetHost('192.92.68.4')
>>> crosstalk.Ping()
crosstalk.Ping()
(200, 'OK')
{"timestamp":1492814063497,"type":"Ping#"}

>>> crosstalk.GetPrice('6','8')
(200, 'OK')
{"timestamp":1492819832600,"type":"GetPrice#","campaign":"6","creative":"8","price":0.5}

>>> crosstalk.GetPrice('6',''8')
(200, 'OK')
{"timestamp":1492819842754,"type":"GetPrice#","campaign":"6","creative":"8","price":0.123}

>>> crosstalk.RefreshA()
(200, 'OK')
{"timestamp":1492814688573,"async":true,"asyncid":-889275714,"type":"Refresh#"}

>>> crosstalk.Future(-889275714)
{"timestamp":1492815502992,"async":true,"asyncid":-889275714,"type":"Refresh#","updated":["6","3"]}
				
>>>