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 (opens in a new tab) 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 (opens in a new tab) 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 (opens in a new tab) or read more about permissions here.

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 (opens in a new tab) 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.

  

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:

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: