The Pixlee Content API is designed to allow developers to freely consume and submit content. We expose a flexible and rich amount of media metadata to allow customization of beautiful, personalized experiences full of user-generated photos and videos from fans and customers.

For 95% of use-cases, you will want to be referencing the [Get Approved Media from an Album] (https://developers.pixlee.com/reference#get-approved-content-from-album) endpoint. This will help you get content from albums of your choice or content related to specific products, and is the most commonly used endpoint.

🚧
Limitations
This API is focused on the programmatic consumption and submission of content out of and into Pixlee, respectively, and is intended to be used by advanced users. It is not meant for accessing analytics, documentation for which can be found [here] (ref:analytics-api-about).

Getting Started

Get your keys: Go to the API tab under account settings from inside Pixlee. Your API Key and Secret Key are disclosed there.
Access: Access the API from anywhere. We've enabled CORS so you can access endpoints just as easily with XHR as with cURL.
That's it!

Important Notes

All response objects are accessible under the 'data' key in the response envelope.
POST payloads always include content header "Content-Type: application/json".
By default, endpoints under distillery.pixlee.co are CDN cached by their full URL, with an expiry of 2 minutes. This helps to ensure speedy responses while keeping data relatively fresh.
A timestamp parameter can be added to refresh this cache on demand, using the parameter &unique_id=NUMERIC_TIMESTAMP.

Authentication

All POSTs will need to be accompanied with an HMAC-SHA1 signature. To generate the signature, run your payload through HMAC-SHA1, using your secret key to sign (this can be found in your Pixlee account settings), convert to Base64, and send the result in the header "Signature": "result".

Generally your payload will be in JSON. When calculating the signature for the payload, convert your payload to JSON, which removes unnecessary spaces and line breaks. Our signature calculation is given below in Scala:

private def calculateSignature (secret: String, toEncode: String): String = {
    /**
      * Calculate the HMAC for the specified data and the supplied secret
    */
    val HMACSHA1 = "HmacSHA1"
    val signingKey = new SecretKeySpec(secret.getBytes(), HMACSHA1)
    val mac = Mac.getInstance(HMACSHA1)
    mac.init(signingKey)
    val rawHmac = mac.doFinal(toEncode.getBytes())
    new String(Base64.encodeBase64(rawHmac))
  }

You can sanity check your key generation with https://www.liavaag.org/English/SHA-Generator/HMAC/

As an example, say that your JSON payload looks like

{
  "album_id": 12345,
  "title": "Testing Photo Upload",
  "approved": true,
  "email": "test@example.com",
  "username": "Submitter Person",
  "photo_uri": "https://example.com/test.jpg"
}

After JSON formatting, it will look like

{"album_id":12345,"title":"Testing Photo Upload","approved":true,"email":"test@example.com","username":"Submitter Person","photo_uri":"https://example.com/test.jpg"}

Given a secret key of "ABCDEFG", submitting this string here: https://www.liavaag.org/English/SHA-Generator/HMAC/ and choosing Input type TEXT, Key type TEXT, SHA-1 variant, and Base-64 output gives:

epBvDlHbQho/rNDdQVJowWMtGsg=

As our final signature output.

Then your final cURL will look like:

curl -X POST \
                              'https://distillery.pixlee.co/api/v2/media?api_key=<MY_PRIVATE_API_KEY>' \
                              -H 'Content-Type: application/json' \
                              -H 'Signature: epBvDlHbQho/rNDdQVJowWMtGsg=' \
                              -d '{"album_id":12345,"title":"Testing Photo Upload","approved":true,"email":"test@example.com","username":"Submitter Person","photo_uri":"https://example.com/test.jpg"}'

❗️
WARNING
If you are using this API to create widget/display experiences on your website, you must also make sure to implement the engagement section of the conversion analytics.
Not doing so will cause conversion analytics to become inaccurate, as people may deserve to be attributed with Pixlee engagement, but will not.
The guide for doing so is available [here] (/docs/analytics-events-tracking-pixel-guide)

API Rate Limiting

API Rate Limiting serves the crucial function of optimizing the utilization of system resources and safeguarding the overall system performance against negative impacts caused by excessive usage.

API Rate Limiting sets a default limit of 3600 requests per minute for each API key, allowing for up to 3600 GET method requests and up to 3600 non-GET method requests (such as POST, PUT, and DELETE) per minute. This approach ensures efficient use of system resources and prevents excessive usage that could negatively impact the overall system performance.

If a user exceeds the API rate limit of 3600 requests per minute for either GET or non-GET methods, a HTTP response code of 429 (Too Many Requests) will be returned. This mechanism helps maintain a fair and stable API service for all users by preventing resource overuse and ensuring a consistent experience for everyone.