imgix APIsManagement APIOverview

Management API Reference

The imgix Management API enables developers to programmatically configure their Sources and perform other activities related to their assets. The API is REST-based and adheres to the JSON:API specification which provides a helpful and consistent interface for working with JSON resources.

The base URL for the imgix Management API is https://api.imgix.com/.

Authentication

All calls to the imgix Management API require an API key. To create a key, navigate to the API Keys view in your Dashboard. Any user can create an API key, but a user will only be able to create a key that has permissions equal to or less than the user’s own permissions. Account Admins can update user permissions on the Users page or read more about permissions here.

API Key Limit

Please note that each imgix account is limited to 20 API keys.

imgix supports the following permissions for use with the Management API:

  • Account Admin: All permissions
  • Analytics: Get analytics data using the reports API.
  • Sources: Create, list, edit, and deploy imgix Sources.
  • Purge: Remove deleted or out-of-date assets from imgix caches.
  • Asset Manager Browse: List and get all content in the Asset Manager.
  • Asset Manager Edit: Edit image metadata and upload assets to Asset Manager (Note: This permission implicitly includes Asset Manager Browse.)

Authentication is performed by passing a valid API key in the request through the HTTP Authorization header. The API expects an authorization type Bearer followed by the alphanumeric API key in plaintext.

An example of how to authenticate your API request:

curl -H "Authorization: Bearer <your-api-key>" https://api.imgix.com/...

Making Requests

The imgix Management API uses REST with JSON:API structured documents to read and write objects. Depending on the action you are taking, the request structures may vary to match the nature of the action being taken.

For all requests requiring a source_id, you can find this in a few different ways:

  • When making a GET request to the sources endpoint, it will be in the JSON response under the id field.

  • By navigating to any of the Sources found in your source dashboard and copying the 24-character string at the end of the URL.

  • Your source_id can also be found on your Source Configuration page after navigating to a Source.

    Screenshot-Where to find your Source ID

Errors

The API will return JSON-formatted errors when it encounters an unsuccessful operation. Instead of a data attribute that would be returned on successful requests, the API response will instead have an errors attribute. The value of errors will be a List of individual Error objects that contain the following fields:

Error FieldsDescription
detailDetailed description of the error
idUnique identifier of the request. Support may be able to troubleshoot further with this id
statusHTTP Status code (see table below)
titleType of error
Error Status CodeDescription
400Bad request / validation failed (e.g. missing a required field)
401Unauthorized (e.g. your API key or authenication method is invalid)
404Not Found (e.g. requesting a non-existent object)
405Method not allowed (e.g. trying to POST on a GET endpoint)
429Rate limit exceeded. Slow down or contact Support if you need higher limits.
500Internal Server Error

The following example tries to request a non-existent Source:

GET /api/v1/sources/invalid-source HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <api-key>
Content-Type: application/vnd.api+json
Host: api.imgix.com

To perform the request using curl:

curl \
  -X GET \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/vnd.api+json" \
  "https://api.imgix.com/api/v1/sources/invalid-source"

The resulting response document will include a list of errors with details about what went wrong:

HTTP/1.1 404
Content-Length: 384
Content-Type: application/vnd.api+json
Date: Thu, 19 Mar 2020 02:01:43 GMT
 
{
  "errors": [
    {
      "detail": "Resource not found.",
      "id": "56ba72bdd33d4395b464fae69f0d31c7",
      "meta": {},
      "status": "404",
      "title": "NotFound"
    }
  ],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  },
  "server": {
    ...
  }
}

Rate Limits

Our APIs have variable rate limits depending on the endpoint. To ensure that requests complete and do not return a rate limiting error, we recommend throttling requests to the Management API based on the following rate limits provided.

We return a 429 Too Many Requests error to new API requests if the rate limit is exceeded for any given endpoint. Once that happens, we will reject new requests to that endpoint until rate limiting subsides. The rate limits are listed below:

imgix APIRate Limit
default rate limit4 per second
update source60 per hour
create source60 per hour
get asset10 per second
refresh asset10 per minute
upload v12 per second
purge asset10 per second

Premium Feature

Premium customers can contact their account manager to discuss modifying the rate limit for their account. If you do not have a premium plan and require a custom rate limit, please contact our sales team for more information.