The Amplify API allows users to interact with the Outbrain Amplify product, facilitating content promotion and advertising. This API enables developers and partners to integrate Amplify into their systems and manage campaigns, budgets, and performance reporting efficiently. For more information about Amplify, please visit our website: http://www.outbrain.com/amplify.

Amplify API Beta

Currently, the Amplify API is available for a select number of partners by request. If you are interested in participating in the beta program, please register here.

Troubleshooting

If you encounter any issues or difficulties while using the Amplify API, we encourage you to seek help through our community.

Please post a new topic in our Google group: https://groups.google.com/forum/#!forum/outbrain-amplifyapi. When posting, remember to attach the “AMPLIFY-REQUEST-ID” header from the response you received. This unique identifier helps us identify your specific request and assists us in providing a quicker and more efficient response.

Reference

The Amplify API follows RESTful conventions and is organized around the following core entities:

• Marketer: Represents a customer account.
• Budget: Contains money allocated for one or more campaigns.
• Campaign: A collection of promoted links.
• PromotedLink: A single piece of promoted content.
• PerformanceBy*: A set of analytics entities to retrieve various metrics.

The API allows various operations on these entities, such as reading, creating, and updating.

HTTP Requests

HTTP methods are used to determine the type of action requested:

• 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 JSON data, please include the “Content-Type: application/json” header in the request.

HTTP Status Code Replies

The Amplify API uses standard HTTP status codes to indicate the result of a request. Here are some of the common codes:

• 200 OK: The request was successful.
• 400 Bad Request: The request could not be understood or was missing the required parameters.
• 401 Unauthorized: Authentication failed, or the user has no permission for the requested operation.
• 403 Forbidden: Access is denied.
• 404 Not Found: The requested resource was not found.
• 429 Too Many Requests: The request exceeded rate limits.

In case of an error, the API will return a JSON object describing the error for easier troubleshooting.

Authentication Token

Obtaining a token is the first step in using the Amplify API. You must include the token in the HTTP Header “OB-TOKEN-V1” for all subsequent requests. Tokens are valid for 30 days, and expired tokens will not grant access to the API. You can generate multiple tokens, and generating a new token does not invalidate older ones.

There are two ways to obtain a token:

1. Via Web Interface: Visit your Amplify API Token Page, enter your password, and click “generate” to get your token. If you can’t see the Amplify API Token form, your username may not have access to the Amplify API. To be considered for the private beta, please register for the beta plan.
2. Via API: you can also obtain a new token using the Amplify API itself. This API transaction is the only one in which you need to supply your Outbrain credentials. Your credentials should be sent using Basic Authentication. This means that the HTTP Request should include a header: named Authorization value: BASIC BASE-64-ENC(YOUR_OUTBRAIN_USER_NAME:YOUR_OUTBRAIN_PASSWORD)
   
   You can try it using curl command (add -v to actually see the Authorization HTTP header:
   curl -u YOUR_OUTBRAIN_USER_NAME:YOUR_OUTBRAIN_PASSWORD https://api.outbrain.com/amplify/v0.1/login

Please ensure your environment supports TLS version 1.2 (TLS 1.2) for secure communication with the Amplify API.

Rate Limits

The Amplify API enforces rate limits to ensure fair usage. Here are the rate limits:

• Authentication requests (/login) are limited to 2 requests per hour per user.
• Usage of a single token is limited to 30 requests per second for the entire API.
• Each marketer is limited to 10 requests per minute for the entire performance reporting API.
• Each marketer is limited to 50 requests per minute for the entire real-time performance reporting API.

In case of a rate limit violation, the API will respond with a status code of 429 (Too Many Requests). The response will also include the “rate-limit-msec-left” header, indicating the remaining milliseconds left in which the rate limit will be in effect.

We recommend managing tokens by storing an active token and periodically updating it since each token is valid for 30 days.

For any further assistance or inquiries, please feel free to contact us through our Google group.