Following the deprecation announcement back in October 2020 for legacy imgix API keys, we are on schedule to deprecate the use of legacy APIs on March 31, 2021.
Note that this applies only to the API for retrieving reports and for purging images. The API to render images is unaffected and will continue to function as it does today.
If you are still using imgix’s legacy API, you must migrate to imgix’s new API to ensure calls to the imgix service will remain successful. To do so, follow the guide below to migrate to imgix’s new API.
How To Tell If You Will Be Impacted
The easiest way to tell if you’re using the imgix legacy API is to examine the endpoints currently being used.
If you are using any of these endpoints, you must migrate over to the new API:
You can also check your authentication method. The legacy API uses Basic authentication, while the new API uses Bearer authentication.
Note that we’re deprecating only these two API endpoints. The rendering API is not affected by this deprecation date.
If you are still using the legacy API, continue reading to learn how to migrate over to the new API.
Generating New API Keys
All legacy API keys will be invalidated in March 2021. Before then, you will need to create new keys in order to authenticate calls to the service.
To do this, access the API keys logging into your dashboard in your dashboard and clicking your account at the top right to navigate to the API Keys page.
The new API keys allow for scoped permissions depending on the type of API access you want to grant. For the purging API, you must have purging permissions. For the reporting API, you must have analytics permissions.
The permissions a user can grant an API key will depend on the permissions they have on their own user role. If you are lacking the right permissions, contact an account administrator to add permissions to your user account. The tutorial for adding users can be found here.
Note that generating new API keys will not invalidate your existing legacy API keys, so feel free to create new API keys for testing before you migrate over to the new API.
Convert Your Authentication Method
The legacy authentication method used a combination of basic authentication and a base64 encoded version of your legacy API token. You can see an example of the legacy authentication method below:
The new API uses bearer authentication and no longer requires that you base64 encode the API key.
Here’s an example authentication request using the new API:
Accept header values have also changed. You must now specify
Content-Type: application/vnd.api+json when sending making requests to our API.
The legacy API uses the endpoint endpoint
https://api.imgix.com/v2/ for API requests.
The new API uses this endpoint:
https://api.imgix.com/api/v1. The paths for the purging and reporting endpoint have also changed, so continue reading to learn how to migrate both of those endpoints.
Why we are changing from
The new migration is more than an upgrade, it’s a completely new set of endpoints to interact with a broader range of services that imgix offers. Because of that, we decided to refresh our endpoint version by restarting with
The purging API has been upgraded to include sub-image purging. It has also been standardized to require more data in order complete purge requests.
To compare, here’s an example of purging an image using the legacy API:
The new purging API specifies the image to purge using the
The new purging API also supports purging sub-images. To do this, read the sub-image purging section in our Management API documentation.
The reporting API has a few changes concerning sorting, filtering and result limiting.
To compare, here is an example request using the legacy API:
Here is that same request using the new reporting API:
Legacy Sorting Method
Previously, you could sort reports in descending order by using either
New Sorting Method
The new API specifies sorting by defaulting to ascending order. To reverse order, prepend
- to the sort value. The following example sorts by
report_key in descending order by using the new API:
Legacy Pagination Method
The new API introduces pagination, which replaces the legacy
limit functionality in the previous reporting API.
Here is an example of limiting results by using the legacy API:
New Pagination Method
The example below returns exactly one result from page 1 of the response:
With the new API, there are two new parameters to use to limit the size of the response. These are:
page[number] will specify the page of the results to return. For example, if the full response is 6 pages long,
page[number]=3 will return page 3 of the results.
page[size] specifies the size of the results on each page. Using a value such as
page[size]=1 will return exactly 1 result per page.
The documentation for using pagination can be found in the management API documentation.
Are you looking to explore the new functionality offered by imgix’s new API? If you have Postman downloaded, you can import the imgix API collection into Postman for an organized list of imgix API examples to try out. Download it here.
The collection uses variables to help you get up and running with testing. After you import the collection to Postman, you can insert your Source ID, API key and other values by using Postman’s variables feature.
Still Need Help?
Still having trouble with migrating to the new API? If so, contact email@example.com and we will be happy to guide you.