"docs.beeswax.com" has a new address: "api-docs.freewheel.tv/beeswax." Please update your bookmarks accordingly.

Getting Started with the Buzz API

The Buzz API uses a REST interface over http to view, create, update and delete objects. For a complete reference of API endpoints, visit the API Reference section of these docs,

You can access the REST API on the command line using cURL or through a client built in whichever language you prefer. Throughout this documentation we show examples using cURL. The typical syntax for a Buzz request using cURL is:

curl -X [method] [path]/rest/[object_name] -b cookies.txt -d '{JSON payload}'

Explanation of the cURL command:

-XTells CURL to use the [method] instead of defaulting to GET
[method]GET = gets object
POST = writes new object
PUT = updates existing object
DELETE = deletes object
[object_name]Corresponds to the object you wish to manipulate, examples include user, advertiser, line_item, etc. Object names are lowercase and words are separated with an underscore. A complete list of objects is in the API Reference section.
-b cookies.txtTells curl to read session cookies from a file called cookies.txt, more on this in Authentication.
-d '{JSON payload}'The JSON payload should contain whatever data needs to be sent to the API for querying the system, pushing new data, etc.

Getting Help

To get help on the command line and see all available objects use the "help" object:
curl -X GET "[path]/buzz/rest/help"

Working with Modules

The API is also used to work with modules that define Targeting, Creative Attributes, and Bidding Strategies. Each of these can have many different modules installed in Buzz, and as a developer you will need to GET available fields from them, and validate whether your inputs are acceptable.

The chart below summarizes these modules:

Module TypeWhat is it?Example API Request
TargetingAvailable targeting criteria for use with a Targeting Template.curl -X [method] [path]/rest/targeting/[module_name] -b cookies.txt -d '{JSON payload}'
Creative AttributesAttributes associated with a Creative to allow proper matching with available inventory.curl -X [method] [path]/rest/attributes/[module_name] -b cookies.txt -d '{JSON payload}'
Bidding StrategiesInstructions for the ad server/bidding agent to determine the proper delivery (bid) of the adcurl -X [method] [path]/rest/bidding/[module_name] -b cookies.txt -d '{JSON payload}'