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

Using Extras for Fine-Tuning API Usage

The Buzz API supports path-based extras as well as the options parameter, each of which modify the behavior of the API. These are optional and can be used to debug or fine-tune your API usage.


Extras change the behavior of the API in fundamental ways and are mutually exclusive (only one per API request).

Extras are utilized by including the extra name in the path of the request as shown in the cURL example below where the strict extra is included:

curl -X GET "[host]/rest/advertiser/strict" -b cookies.txt 
	-d '{"advertiser_name":"advertiser", "active":1}'

Supported Extras and their behavior are shown below:

extraexecutes API call?Functionality
fieldsNoReturns a JSON representation of the fields of the object being requested, along with whether the field is required or searchable.
helpNoReturns custom help for the object. (Note, this is not widely implemented at this point)
strictYesTreats the JSON request strictly, throwing errors if there are extra, non-valid fields within the request and throwing a 409-Conflict error when any WARNINGs are incurred.
uploadYesAllows for file uploads, when supported by the API object (usually Creative Assets)
validationNoValidates whether the request is valid but does not execute.
viewsNoReturns an array of available views for the object as well as the fields and metadata for that view. Useful for creating a UI on Buzz.


Every API request to Buzz may include an extra parameter, options that modifies the response from the server. Options may be combined with each other, as well as with Extras.

In the example below we are using both the time and compact options. Options should be passed as a list, though for convenience when passing a single option a string is allowed.

curl -X GET "[host]/rest/advertiser/strict" -b cookies.txt 
	-d '{"advertiser_name":"advertiser", "active":1, "options":["time","compact"]}'
timeAdds an extra field in the response showing the execution time of the request in milliseconds.Formerly the time parameter was an Extra, which is now deprecated.
prettyAPI response will be padded with whitespace to make it easier for human readability (opposite of compact).Based on your system setup, either pretty or compact may be your default. You can have this switched as required.
compactAPI response will have all whitespace removed to reduce filesize (opposite of pretty)Same as above.


By default all API requests are returned in the Account-level timezone, generally America/New_York. API users can force all date fields to be in another timezone for convenience by adding the X-Timezone header to the API request with a valid timezone.

#Request all dates in UTC
curl -X GET "https://canary.api.beeswax.com/rest/advertiser" -b cookies.txt 
	-d '{"rows":1}' -H "X-Timezone: UTC"

#Request all dates in Los Angeles
curl -X GET "https://canary.api.beeswax.com/rest/advertiser" -b cookies.txt 
	-d '{"rows":1}' -H "X-Timezone: America/Los_Angeles"