Getting Started with the Buzz API

The Buzz API uses a REST interface over https 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 syntaxes for a Buzz request using cURL are shown below.


Migration Notes

The Buzz 2.0 API differs significantly from the previous version. Please read the Migration Guide for details.

GET syntax

#GETs must include parameters on the path in URL-encoded form
curl -X GET [endpoint]/[path]/[resource]?[parameters] -b cookies.txt

POST with JSON payload

#JSON POST example
curl -X {POST/PUT/DELETE} [endpoint]/[path]/[resource]
	-b cookies.txt
	-d '{"param1":"value1","param2":"value2"}'
	-H "Content-Type: application/json"

PUT, DELETE syntax with JSON payload

#PUTs, PATCHes and DELETEs must include the ID in the path 

#JSON example
curl -X {POST/PUT/DELETE} [endpoint]/[path]/[resource]/[id]
	-b cookies.txt
	-d '{"param1":"value1","param2":"value2"}'
	-H "Content-Type: application/json"

PUT, DELETE syntax with urlencoded payload

#URLencoded example
curl -X {POST/PUT/DELETE} [endpoint]/[path]/[resource]/[id]
	-b cookies.txt
	-d 'param1=value1&param2=value2'
	-H "Content-Type: application/x-www-form-urlencoded"

cURL Example

[endpoint]Each Beeswax customer gets a unique endpoint based on their Buzz Key. The complete endpoint to the API will be in the form:

[path]The path for resources always starts with /rest/v2/

In some cases this may be extended with a collection of resources such as /rest/v2/ref/
[resource]Corresponds to the object you wish to manipulate, examples include users, advertisers, line-items, etc. Resource names are plural, lowercase, and words are separated with a hyphen. 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 [payload]The payload should contain whatever data needs to be sent to the API for completing the request.

Returning CSV or Excel Responses

By default all API responses are returned as JSON objects. It can be useful to return results in CSV or Excel formats, especially on GET responses with many results. To do so, add an Accept header to the API request as shown below:

Desired Response FormatAccept Header
Comma-separated (CSV)Accept: text/csv
Microsoft Excel (XSLS)Accept: application/xlsx

Note, highly nested objects may be difficult to work with if exported to a flattened format such as Excel.