Overview
Base URL, core entities, HTTP conventions, and error handling for the Amplify API.
This API describes the interfaces for interacting with the Outbrain Amplify product. More information about Amplify can be found on our website: http://www.outbrain.com/amplify.
To request access to the Amplify API, please complete this form.
If you have any questions, issues, feature requests as well as if you're interested in announcements of new features, please join our Google group:
https://groups.google.com/forum/#!forum/outbrain-amplifyapi
API URL
The base url for all API end-points is https://api.outbrain.com/amplify/v0.1/
Troubleshooting
If you're experiencing any issues or any other difficulties, please post a new topic in our Google group: https://groups.google.com/forum/#!forum/outbrain-amplifyapi
Please attach to your post the AMPLIFY-REQUEST-ID header from the returned response. This header allows us to identify your unique request and helps us to reply quicker and more efficiently.
Core entities
The API is RESTful and is structured into the following core entities:
- Marketer: A customer account.
- Budget: A budget that contains money to be spent on one or more campaigns.
- Campaign: A collection of promoted links.
- PromotedLink: A single piece of promoted content.
- PerformanceBy*: A variety of analytics entities to retrieve metrics.
The following operations may be performed via this API:
| Entity | Function |
|---|---|
| Marketer | Read |
| Budget | Read, Create, Update |
| Campaign | Read, Create, Update |
| PromotedLink | Read, Create, Update |
| Performance* | Read |
Performance* refers to the many entities that represent reporting data. For example, here are a few of our 9 different reporting endpoints:
- Performance for a Marketer per day
- Performance for a Campaign per day
- Performance for a PromotedLink per day
HTTP Requests
We follow RESTful conventions of using HTTP methods to determine the type of action requested:
| HTTP Method | Action |
|---|---|
GET | Retrieve a resource or a list of resources |
POST | Create a resource. |
PUT | Update a resource. |
When issuing a POST/PUT request that includes a json of the created/updated entitiy
the following header must be included in the request:
Content-Type: application/jsonHTTP Status Code Replies
| HTTP Status Code | Meaning | Description |
|---|---|---|
| 200 | OK | The request was successful. |
| 400 | Bad Request | The request could not be understood or was missing required parameters |
| 401 | Unauthorized | Authentication failed or user doesn't have permissions for requested operation |
| 403 | Forbidden | Access denied |
| 404 | Not Found | Resource was not found |
| 429 | Too Many Requests | Request exceeded rate limits |
Error Handling
When the API returns a status code indicating an error (400, 401, 403, 404, 429) it will also include the JSON describing the error. For example:
{
"moreInfo" : "get-budget",
"errorMessage" : "access denied"
}