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¶m2=value2'
-H "Content-Type: application/x-www-form-urlencoded"
cURL Example
Component | Description |
---|---|
[endpoint] | Each Beeswax customer gets a unique endpoint based on their Buzz Key. The complete endpoint to the API will be in the form:https://<buzz-key>.api.beeswax.com/ |
[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.txt | Tells 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 Format | Accept 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.
Updated 6 months ago