Management API

  1. Documentation
  2. imgix APIs
  3. Management API
Management API Reference
Authentication Making Requests Fetching Single Objects Fetching List of Objects Specifying The Fields Returned Paging Lists Of Objects Paging By Page Number and Size Sorting Lists Of Objects Filtering Lists Of Objects Creating Objects Updating Objects Errors
Sources
Source Operations Source Filters Source Sorts Source Attributes Source Deployment Attributes Source Examples
Purges
Purge Operations Purge Attributes Purging Sub-Images Purge Sub-Image Attributes Purge Examples
Asset Manager Assets
Asset Operations Asset Filters Asset Sorts Asset Attributes Paginating through Asset Lists Uploading Assets to a Source Upload Credentials Attributes Adding an Asset Refreshing an Asset Using Upload Sessions Asset Examples
Reports
Report Operations Report Filters Report Sorts Report Attributes Report Types Report Examples

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.

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

The following are examples of valid requests.

Fetching Single Objects

The following is an example HTTP GET request for fetching a single Source object from the API:

GET /api/v1/sources/5d46fb3bd596f100018e123f 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 \
  -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/5d46fb3bd596f100018e123f"

The resulting response document will look similar to:

{
  "data": {
    "attributes": {
      "date_deployed": 1591042615,
      "deployment": {
        "annotation": "New deployment created for source by imgix testing.",
        "cache_ttl_behavior": "respect_origin",
        "cache_ttl_error": 300,
        "cache_ttl_value": 31536000,
        "crossdomain_xml_enabled": false,
        "custom_domains": [],
        "default_params": {},
        "image_error": null,
        "image_error_append_qs": false,
        "image_missing": null,
        "image_missing_append_qs": false,
        "imgix_subdomains": [
          "my-unique-domain"
        ],
        "secure_url_enabled": false,
        "type": "webfolder",
        "webfolder_base_url": "http://my-domain.com/images/"
      },
      "deployment_status": "deployed",
      "enabled": true,
      "name": "New Web Folder Source"
    },
    "id": "5ed56238a04d080001d4a08e",
    "type": "sources"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "authentication": {
      ...
    },
  ...
  }
}

If a corresponding object does not exist for the given resource, a 404 error will be returned. See the Errors section to learn more about error documents.

Fetching List of Objects

To fetch a list of objects, the request is largely the same except that it is making a GET request to a set of objects rather than a single object.

The following is an example HTTP GET request for fetching a list of Source objects from the API:

GET /api/v1/sources 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 \
  -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"

The resulting response will contain zero or more Source objects and some paging metadata:

{
  "data": [
    {
      "attributes": {
        ...
      },
      "id": "5d1e0dc3d596f10001b0221c",
      "type": "sources"
    },
    {
      "attributes": {
        ...
      "id": "5ae509aaf5b98f000169ee72",
      "type": "sources"
    },
  ],
  ...
  "meta": {
    ...
    "pagination": {
      "currentPage": 0,
      "hasNextPage": false,
      "hasPreviousPage": false,
      "nextPage": 0,
      "pageSize": 20,
      "previousPage": 0,
      "totalPages": 1,
      "totalRecords": 2
    },
    ...
  }
}

Specifying The Fields Returned

By default, all available object fields are returned in a response. The developer can control which specific fields are returned on a per-object basis using the fields parameter. The value of this parameter is a comma-delimited list of fields to include. Any unrecognized field names will be ignored. To request a deeply-nested field, use dot notation.

An example of a request limiting the fields of a Source object would look like the following:

GET /api/v1/sources/5d46fb3bd596f100018e123f?fields[sources]=name,deployment_status,deployment.default_params 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 \
  -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/5d46fb3bd596f100018e123f?fields\[sources\]=name,deployment_status,deployment.default_params"

The resulting response will look similar to:

{
  "data": {
    "attributes": {
      "deployment": {
        "default_params": {
          "auto": "compress"
        }
      },
      "deployment_status": "deployed",
      "name": "example-source"
    },
    "id": "5d46fb3bd596f100018e123f",
    "type": "sources"
  },
  ...
}

Paging Lists Of Objects

All list API calls support paging. However, depending on the nature of the object being listed, the paging model may differ. Refer to the object-level documentation to determine what the paging model is for that object type.

In all cases, sensible defaults are in place if you do not supply explicit paging values. Not providing paging values will not result in the entire list of objects being returned. Furthermore, page sizes and cursor limits have maximum values in order to ensure good performance. Therefore, to fetch an entire list of objects, developers will need to chain together multiple API list calls in sequence and collect the results themselves.

Paging By Page Number and Size

The vast majority of objects support paging by page number and size. This is the default behavior when the size of the dataset is easily determined behind the scenes. To request a specific page, developers provide the page[number] and page[size] parameters. Page numbers are zero-indexed. Page sizes must be greater than or equal to 1.

The following is an example HTTP GET request for fetching a list of Source objects, one at a time, from the API:

GET /api/v1/sources?page[number]=0&page[size]=1 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 \
  -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?page\[number\]=0&page\[size\]=1"

The resulting response document will contain one Source object at a time and paging metadata that indicates how to navigate to get the remaining pages:

HTTP/1.1 200
Content-Length: 384
Content-Type: application/vnd.api+json
Date: Thu, 19 Mar 2020 02:01:43 GMT

{
  "data": [
    {
      "attributes": {
        "deployment": {
          ...
        },
        "deployment_status": "deployed",
        "enabled": true,
        "name": "example-source",
        "secure_url_token": ...
      },
      "id": "5d1e0dc3d596f10001b0221c",
      "type": "sources"
    }
  ],
  ...
  },
  ...
  "meta": {
    ...
    "pagination": {
      "currentPage": 0,
      "hasNextPage": true,
      "hasPreviousPage": false,
      "nextPage": 1,
      "pageSize": 1,
      "previousPage": 0,
      "totalPages": 7,
      "totalRecords": 7
    },
    ...
  }
}

Developers should rely on the hasNextPage and nextPage values of the pagination metadata to determine if there is a next page and if there is, what that page number should be. Similarly, they can use the hasPreviousPage and previousPage values to navigate backwards. For direct access to pages, developers can build off of the currentPage and totalPages values.

Sorting Lists Of Objects

Lists of objects may be sorted by a defined subset of their object fields. To sort a list by a specific field or set of fields, developers should provide the sort parameter in the request. The value should be set to a comma-separated list of valid fields of the object type. Fields are sorted ascending by default. To sort a field in descending order, prepend a dash “-” to the field name. When sorting on a Boolean type field, the default sort order is false first, then true. To reverse this order prepend a dash “-” to the field name.

Note that sorting by nested fields (e.g. deployment.type) is not currently supported.

The following is an example HTTP GET request for fetching a list of Source objects that are sorted alphabetically by name:

GET /api/v1/sources?sort=name&fields[sources]=name 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 \
  -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?sort=name&fields[sources]=name"

The resulting response document will contain Source objects sorted by their name in alphabetical order:

HTTP/1.1 200
Content-Length: 384
Content-Type: application/vnd.api+json
Date: Thu, 19 Mar 2020 02:01:43 GMT

{
  "data": [
    {
      "attributes": {
        "name": "Azure Source"
      },
      "id": "5ed8734f6734bf0001ac1145",
      "type": "sources"
    },
    {
      "attributes": {
        "name": "GCS Source"
      },
      "id": "5ed8736e956a8d0001f28424",
      "type": "sources"
    },
    {
      "attributes": {
        "name": "S3 Source"
      },
      "id": "5ed844bc6bde8a0001c08dbf",
      "type": "sources"
    }
  ]
}

Filtering Lists Of Objects

Developers can filter down their lists of objects by using the filter parameter. The filter parameter is an indexed parameter with the index being the name of the field to be filtered by and the value is what to filter. Multiple filter values will be AND’ed together.

Unless noted otherwise, filter fields that take in String values will do substring matching. For example, if filter[name] is set to test, the API will return objects that have name values of test, my test, testing, etc.

Objects can define their own supported filter fields and what the values that they capture actually represent in the filter. Read the object-level documentation to learn more about which fields can be filtered and what the behavior of the values are. Unrecognized filter fields will be ignored.

For example, if a developer wanted to filter a list of Source objects to only include Sources with type s3 and with a name containing staging.

GET /api/v1/sources?filter[name]=staging&filter[deployment.type]=s3 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 \
  -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?filter\[name\]=staging&filter\[deployment.type\]=s3"

The resulting response document will contain Source objects that are type s3 and have names that contain staging.

HTTP/1.1 200
Content-Length: 384
Content-Type: application/vnd.api+json
Date: Thu, 19 Mar 2020 02:01:43 GMT

{
  "data": [
    {
      "attributes": {
        "deployment": {
          ...
          "type": "s3"
        },
        "deployment_status": "deployed",
        "enabled": true,
        "name": "Staging 1"
      },
      "id": "5ed844bc6bde8a0001c08dbf",
      "type": "sources"
    },
    {
      "attributes": {
        "deployment": {
          "type": "s3"
        },
        "deployment_status": "deployed",
        "enabled": true,
        "name": "Staging 2"
      },
      "id": "5ed873349234930001cc74ae",
      "type": "sources"
    },
  ],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "pagination": {
      "currentPage": 0,
      "hasNextPage": false,
      "hasPreviousPage": false,
      "nextPage": 1,
      "pageSize": 20,
      "previousPage": 0,
      "totalPages": 1,
      "totalRecords": 1
    }
  }
}

Creating Objects

To create an object, developers should make an HTTP POST request to the list endpoint of the object. The document posted should include all required attributes and the object type. Optional attributes will be filled with default values. Unless otherwise specified in the object-level documentation, the id field should be left unset as it will be populated during object creation.

The following example creates a new Source object.

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

{
  "data": {
    "attributes": {
      "name": "New Web Folder Source",
      "deployment": {
        "type": "webfolder",
        "webfolder_base_url": "https://my-domain.com/images/",
        "imgix_subdomains": [
          "my-unique-imgix-subdomain"
        ]
      }
    },
  "type": "sources"
  },
  "jsonapi": {
    "version": "1.0"
  }
}

To perform the request using curl:

curl \
  -X POST \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{ "data": { "attributes": { "name": "New Web Folder Source", "deployment": { "type": "webfolder", "webfolder_base_url": "https://my-domain.com/images/", "imgix_subdomains": [ "my-unique-imgix-subdomain" ] } }, "type": "sources"}, "jsonapi": { "version": "1.0" } }' \
  "https://api.imgix.com/api/v1/sources"

The resulting response document will contain a Source with a new id value set. Note that the resulting response code will be 201 Created.

HTTP/1.1 201
Content-Length: 384
Content-Type: application/vnd.api+json
Date: Thu, 19 Mar 2020 02:01:43 GMT

{
  "data": {
    "attributes": {
      "date_deployed": 1594942125,
      "deployment": {
        "annotation": "New deployment created for source by testing-api-docs.",
        "cache_ttl_behavior": "respect_origin",
        "cache_ttl_error": 300,
        "cache_ttl_value": 31536000,
        "crossdomain_xml_enabled": false,
        "custom_domains": [],
        "default_params": {},
        "image_error": null,
        "image_error_append_qs": false,
        "image_missing": null,
        "image_missing_append_qs": false,
        "imgix_subdomains": [
          "my-unique-domain"
        ],
        "secure_url_enabled": false,
        "type": "webfolder",
        "webfolder_base_url": "https://my-website.com/images/"
      },
      "deployment_status": "deploying",
      "enabled": true,
      "name": "New Web Folder Source"
    },
    "id": "5ed5a2b1b4e4940001e29909",
    "type": "sources"
  },
  ...
}

Updating Objects

To update the fields on an existing object, developers should execute an HTTP PATCH request against that object. Fields not included in the provided document will not be updated and will keep their existing values.

The id of the object and the type of the object are always required as part of PATCH requests, as per the JSON:API spec.

Note that when updating fields with values that of types List or Object, an update will replace that entire List or Object. If you would like to keep any previous values you will need to include them in the PATCH request.

The following example updates an existing Source object.

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

{
  "data": {
    "attributes": {
      "name": "New Source Name"
    },
    "id": "5d703ed13f876f000190b31d",
    "type": "sources"
  }
}

To perform the request using curl:

curl \
  -X PATCH \
  -H "Accept: application/vnd.api+json" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{ "data": {"attributes": { "name": "New Source Name" },"id": "5d703ed13f876f000190b31d", "type": "sources" } }' \
  "https://api.imgix.com/api/v1/sources/5d46fb3bd596f100018e123f"

The resulting response document will always include the updated Source record provided that the object exists. Otherwise, it will return a 404 Not Found.

HTTP/1.1 200
Content-Length: 384
Content-Type: application/vnd.api+json
Date: Thu, 19 Mar 2020 02:01:43 GMT

{
  "data": {
    ...
    "name": "New Source Name",
  },
  "id": "5d46fb3bd596f100018e123f",
  "type": "sources"
  },
  ...
}

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 Fields Description
detail Detailed description of the error
id Unique identifier of the request. Support may be able to troubleshoot further with this id
status HTTP Status code (see table below)
title Type of error
Error Status Code Description
400 Bad request / validation failed (e.g. missing a required field)
401 Unauthorized (e.g. your API key or authenication method is invalid)
404 Not Found (e.g. requesting a non-existent object)
405 Method not allowed (e.g. trying to POST on a GET endpoint)
429 Rate limit exceeded. Slow down or contact Support if you need higher limits.
500 Internal 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": {
    ...
  }
}

Sources

Source Operations

Open in Postman

All Source operations require the Sources permission.

Endpoint Method Description
sources GET List all Sources for an account
sources POST Create (and deploy) a new Source
sources/:source_id GET Retrieve details for a single Source by source_id
sources/:source_id PATCH Updates a single Source. Any changes impacting the deployment will automatically trigger a Source deploy. Changes that impact rendering will not take effect until the Source is finished deploying and you may need to purge any previously-rendered derivatives to serve images rendered with the new configurations.

Source Filters

Filter Type Supported Source Types
deployment.azure_bucket String Azure
deployment.bucket_name String S3-Compatible
deployment.custom_domains String All
deployment.gcs_bucket String GCS
deployment.imgix_subdomains String All
deployment.region String S3-Compatible
deployment.s3_bucket String S3
deployment.storage_provider String S3-Compatible
deployment.webfolder_base_url String Web Folder
enabled Boolean All
name String All
type String All. Possible values are azure, gcs, s3, webfolder, webproxy, s3_compatible

Source Sorts

  • date_deployed
  • enabled
  • name

Source Attributes

Field Type Updatable? Description
date_deployed Integer No Unix timestamp of when this Source was deployed.
deployment* Object Yes See Source Deployment tables below.
deployment_status String No Current deployment status. Possible values are deploying, deployed, disabled, and deleted.
enabled Boolean Yes Whether or not a Source is enabled and capable of serving traffic. Disabled Sources will serve a 410 Gone for non-cached assets.
name* String Yes Source display name. Does not impact how assets are served.
secure_url_token String No Signing token used for securing assets. Only present if deployment.secure_url_enabled is true.

*Required for Source creation

Source Deployment Attributes

Source Deployment: All Source Types

Field Type Updatable? Description
allows_upload Boolean No Whether imgix has the right permissions for this Source to upload to origin. Applicable only for azure, gcs, or s3 Source types. See Uploading Assets for more information.
annotation String Yes Any comment on the specific deployment. Defaults to “New deployment created for source by <user>”
cache_ttl_behavior String Yes Policy to determine how the TTL on imgix images is set. Accepted values: respect_origin, override_origin, enforce_minimum. Defaults to respect_origin. More on cache behavior here.
cache_ttl_error Integer Yes TTL (in seconds) for any error image served when unable to fetch a file from origin. Minimum value of 1, maxmum value of 31536000. Defaults to 300. More on cache behavior here.
cache_ttl_value Integer Yes TTL (in seconds) used by whatever cache mode is set by cache_ttl_behavior. Minimum value of 1800, maximum value of 31536000. Defaults to 31536000. More on cache behavior here..
crossdomain_xml_enabled Boolean Yes Whether this Source should serve a Cross-Domain Policy file if requested. More on Cross-Domain Policy files here.
custom_domains List Yes Non-imgix.net domains you want to use to access your images. Custom domains must be unique across all Sources and must be valid domains. Defaults to []. More on custom domains here.
default_params Object Yes Parameters that should be set on all requests to this Source. Object keys are the params and object values are the param values. All keys/values must be valid imgix params/values. Defaults to {}. More on default params here.
image_error String Yes Image URL imgix should serve instead when a request results in an error. Accepted values are valid absolute URLs. Defaults to null. More on error images here.
image_error_append_qs Boolean Yes Whether imgix should pass the parameters on the request that received an error to the URL described in image_error. Defaults to false. More on error images here.
image_missing String Yes Image URL imgix should serve instead when a request results in a missing image. Accepted values are valid absolute URLs. Defaults to null. More on default images here.
image_missing_append_qs Boolean Yes Whether imgix should pass the parameters on the request that resulted in a missing image to the URL described in image_missing. Defaults to false. More on default images here.
imgix_subdomains* List Yes Subdomain you want to use on *.imgix.net to access your images. Domains must be unique across all Sources and must be valid subdomains. Because the imgix.net is implicit, only the subdomain is accepted, e.g. if you want to use foo.imgix.net, you should only pass ["foo"]. At least one subdomain is required.
secure_url_enabled Boolean Yes Whether requests must be signed with the secure_url_token to be considered valid. More on securing images here.
type* String Yes Source type. Accepted values: azure , gcs, s3, webfolder, webproxy. More on Source types here. Note that if you update the Source type you will also need to provide the required parameters for that Source type.

*Required for Source creation

Source Deployment: Amazon S3-specific fields

Field Type Updatable? Description
s3_access_key* String Yes Access Key ID.
s3_bucket* String Yes S3 bucket name.
s3_prefix String Yes The folder prefix prepended to the image path before resolving the image in S3. Defaults to null.
s3_secret_key* String Yes S3 Secret Access Key. Note: Will not be returned on subsequent GET requests.

*Required for Source creation

Source Deployment: Google Cloud Storage-specific fields

Field Type Updatable? Description
gcs_access_key* String Yes GCS Access Key.
gcs_bucket* String Yes GCS bucket name.
gcs_prefix String Yes The folder prefix prepended to the image path before resolving the image in GCS. Defaults to null.
gcs_secret_key* String Yes GCS Secret Access Key. Note: Will not be returned on subsequent GET requests.

*Required for Source creation

Source Deployment: Microsoft Azure-specific fields

Field Type Updatable? Description
azure_account* String Yes Azure storage account name.
azure_bucket* String Yes Azure storage container name.
azure_prefix String Yes The folder prefix prepended to the image path before resolving the image in Azure. Defaults to null.
azure_sas_string* String Yes Azure Shared Access Signature String. Note: Will not be returned on subsequent GET requests.
azure_service_type* String Yes Azure storage type. Accepted values are blob or file.

*Required for Source creation

Source Deployment: Web Folder-specific fields

Field Type Updatable? Description
webfolder_base_url* String Yes The protocol, host, and path information to prepend to the image path when retrieving from origin (such as http://www.yourcompany.com/images/).

*Required for Source creation

Source Deployment: S3 Compatible-specific fields

Field Type Updatable? Description
access_key_id* String Yes S3-Compatible Access Key
bucket_name* String Yes S3-Compatible Bucket Name
endpoint_url* String Yes The digital location where the API receives specific requests for its server.
region* String Yes The physical location where the data center is located.
secret_key* String Yes S3-Compatible Secret Access Key
storage_provider* String Yes The name of your S3-Compatible storage provider. Accepted values are DigitalOcean, Linode, Wasabi.

*Required for Source creation

Source Deployment: Web Proxy-specific fields

There are no Web Proxy-specific fields related to Source Deployment.

Source Examples

Example: Creating a new S3 Source

POST /api/v1/sources
{
  "data": {
    "attributes": {
      "name": "example_test",
      "deployment": {
        "type": "s3",
        "s3_access_key": "$YOUR_S3_ACCESS_KEY",
        "s3_bucket": "$YOUR_S3_BUCKET",
        "s3_secret_key": "$YOUR_S3_SECRET_KEY",
        "imgix_subdomains": [
          "$YOUR_IMGIX_SUBDOMAIN"
        ]
      }
    },
    "type": "sources"
  }
}
{
  "data": {
    "attributes": {
      "date_deployed": 1666823606,
      "deployment": {
        "annotation": "New deployment created for source by imgix.",
        "cache_ttl_behavior": "respect_origin",
        ...
      },
      "deployment_status": "deploying",
      "enabled": true,
      "name": "example_test"
    },
    "id": "6359b5ba8147da20e8edfdd5",
    "type": "sources"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}

Example: Updating your Source's bucket configuration

PATCH /api/v1/sources/6359b5ba8147da20e8edfdd5
{
  "data": {
    "attributes": {
      "name": "example_source",
      "deployment": {
        "cache_ttl_value": 31536000,
        "s3_access_key": "$YOUR_S3_ACCESS_KEY",
        "s3_bucket": "$YOUR_S3_BUCKET",
        "s3_secret_key": "$YOUR_S3_SECRET_KEY",
      }
    },
    "id": "6359b5ba8147da20e8edfdd5",
    "type": "sources"
  }
}
{
  "data": {
    "attributes": {
      "date_deployed": 1666822829,
      "deployment": {
        "annotation": "New deployment created for source by imgix.",
        "cache_ttl_behavior": "respect_origin",
        ...
      },
      ...
    },
    "id": "6359b5ba8147da20e8edfdd5",
    "type": "sources"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}

Example: Creating a new S3 Compatible Source

POST api/v1/sources/source_id

{
    "data": {
        "attributes": {
            "name": "new_source_name",
            "deployment": {
                "type": "s3_compatible",
                "storage_provider": "$YOUR_STORAGE_PROVIDER",
                "access_key_id": "$YOUR_ACCESS_KEY",
                "bucket_name": "$YOUR_BUCKET_NAME",
                "secret_key": "$YOUR_SECRET_KEY",
                "endpoint_url": "$YOUR_ENDPOINT_URL",
                "region": "$YOUR_REGION",
                "imgix_subdomains": [
                    "$YOUR_IMGIX_SUBDOMAIN"
                ]
            }
        },
        "type": "sources"
    },
    "jsonapi": {
        "version": "1.0"
    }
}

Example: Converting a Web Folder Source to an S3 Compatible Source

PATCH api/v1/sources/source_id

 {
     "data": {
       "attributes": {
         "name": "sourceName",
            "deployment": {
                "type": "s3_compatible",
                "storage_provider": "$YOUR_STORAGE_PROVIDER",
                "access_key_id": "$YOUR_ACCESS_KEY",
                "bucket_name": "$YOUR_BUCKET_NAME",
                "secret_key": "$YOUR_SECRET_KEY",
                "endpoint_url": "$YOUR_ENDPOINT_URL",
                "region": "$YOUR_REGION",
                "imgix_subdomains": [
                    "$YOUR_IMGIX_SUBDOMAIN"
                  ]
              }
      },
      "id": "source_id",
      "type": "sources"
    },
      "jsonapi": {
           "version": "1.0"
      }
  }

Purges

For performance reasons, imgix will try to cache your origin assets for as long as possible, but if your asset changes at the origin you may want to purge it so that imgix will fetch the newest version. Click here for an overview on purging.

A successful purge request will return a 200 status code. Purge requests for the same image URL should be spaced at least 10 seconds apart, otherwise a 409 status code may be returned, indicating a duplicate purge request. Purge requests will still be successful regardless of a duplicate request.

Images with a mark or a blend do not need to be purged in any special way unless the image that is being used as the mark or the blend (also called the "sub-image") needs to be updated. In that case, see the section below on Purging Sub-Images.

Purge Operations

Open in Postman

Purge operations require the Purge permission.

Endpoint Method Description
purge POST Purge an asset from the imgix cache

Purge Attributes

Field Type Required? Description
url String Yes Fully qualified URL of the asset to be purged. Any parameters do not need to be passed; purging will remove all derivative copies of the base URL. URL's domain must be one associated with the current account.

Purging Sub-Images

An image that is used as a mark or blend is referred to as a "sub-image" while the image that has the mark or blend applied to it is referred to as the "parent image". If a sub-image is updated at the origin, the sub-image must be purged for the parent image to incorporate the updated sub-image.

Purging a sub-image requires a source_id as well and the sub-image purge will also purge any parent images that use the sub-image as a mark or blend.

Purge Sub-Image Attributes

Field Type Required? Description
url String Yes Fully qualified URL of the sub-image to be purged.
sub_image Boolean Yes Whether or not the url refers to a sub-image. Must be true for a sub-image purge.
source_id String Yes ID of the Source that the parent image of the sub-image is associated to.

Purge Examples

Example: Purging an image asset

POST /api/v1/purge
{
  "data": {
    "attributes": {
      "url": "https://assets.imgix.net/examples/bridge.jpg"
    },
    "type": "purges"
  }
}
{
  "data": {
    "attributes": {
      "purge_id": "a794e260-3776-4efe-9878-35acec6980b6"
    },
    "id": "a794e260-3776-4efe-9878-35acec6980b6",
    "type": "purges"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}

Example: Purging a sub-image

POST /api/v1/purge
{
  "data": {
    "attributes": {
      "url": "https://assets.imgix.net/examples/bridge.jpg",
      "sub_image": true,
      "source_id": "5b81e81539ddc50001a5d955"
    },
    "type": "purges"
  }
}
{
  "data": {
    "attributes": {
      "purge_id": "63bb029f-6d0a-4e46-9d33-7183c7b536ef"
    },
    "id": "63bb029f-6d0a-4e46-9d33-7183c7b536ef",
    "type": "purges"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}

Asset Manager Assets

Note: Some Asset Manager features (and therefore some Asset Manager API Operations) are Enterprise-only and may not be enabled for all accounts. Contact Support or your Account Manager to find out more.

Asset Manager Asset operations are usually tied to a specific Source, specified by source_id.

Asset Operations

Open in Postman

GET Asset operations require the Asset Manager Browse permission. All other Asset operations require the Asset Manager Edit permission.

Endpoint Method Description
sources/:source_id/assets GET Retrieve a list of assets from the Source.
sources/:source_id/assets/:origin_path GET Retrieve details for a single asset in a Source source_id by asset_id.
sources/:source_id/assets/:origin_path PATCH Update a single asset.
sources/:source_id/upload/:origin_path POST Upload a single asset to the source_id Source at origin_path. See Uploading for more details.
sources/:source_id/assets/add/:origin_path POST Adds a single asset to the Asset Manager from the origin. Adding an Asset for more details.
sources/:source_id/assets/refresh/:origin_path POST Refresh, reprocess, and purge a single asset. See Refreshing an Asset for more details.

Asset Filters

Filter Type Notes
categories String
colors String Hex code (minus the #, e.g. 8ca091.
custom:<key> String If no value is passed for this filter it will return results that have the custom key set to any value. If a value is passed, it will return results that have the custom key set to that specific value.
face_count Integer A single integer will return results with exactly that many faces. To filter on a range, use a : (e.g. 1:3 would return results with 1, 2, or 3 faces, 1: would return results with 1 or more faces and :2 would return results with 2 or fewer faces.
has_frames Boolean
keyword String Searches across multiple pre-determined fields, such as origin_path, name, description, etc. Exact behavior is subject to change.
media_kind String Type of asset. Possible values: IMAGE, ANIMATION, DOCUMENT, VECTOR.
origin_path String
tags String
warning_adult Integer Accepted values are 1 through 5 where 1 is least likely and 5 is most likely. To filter on a range, use a : (e.g. 1:3 would return results with values 1, 2, or 3, 3: would return results with values 3 or higher and :2 would return results with values 2 or lower.
warning_medical Integer Behavior is the same as for warning_adult above.
warning_racy Integer Behavior is the same as for warning_adult above.
warning_spoof Integer Behavior is the same as for warning_adult above.
warning_violence Integer Behavior is the same as for warning_adult above.

Asset Sorts

  • date_created
  • date_modified
  • file_size

Asset Attributes

Field Type Updatable? Description
analyzed_content_warnings Boolean No Whether asset has been analyzed for content warnings.
analyzed_faces Boolean No Whether asset has been analyzed for the presence of faces.
analyzed_tags Boolean No Whether asset has been analyzed in order to generate tags.
categories List Yes List of user-added categories to describe or organize the asset (e.g. “Editorial Images” or “Summer Campaign” or “Profile Pictures”.
color_model String No Detected color model (e.g. “RGB” or “CMYK”).
color_profile String No Detected color profile (e.g. “Apple Wide Color Sharing Profile”).
colors Object No Detected dominant colors. Keys are hex codes and values are floating point numbers representing the fraction of the image with that color. The percentage values will not necessarily add up to 1 because not every single color in the image will be returned.
content_type String No Detected content type of the asset (e.g. image/jpeg, image/gif). Unsupported or unknown content types may have value application/octet-stream.
custom_fields Object Yes User-added custom fields and values (e.g. { SKU: 1234 })
date_created Integer No Unix timestamp of the first time this asset was added to the Asset Manager (note that this is often different from the first time an image has been processed by the imgix rendering service).
date_modified Integer No Unix timestamp of the last time this asset was modified, whether by an end-user or by an automated update.
description String Yes User-provided description of asset.
dpi_height Integer No DPI of an image’s height.
dpi_width Integer No DPI of an image’s width.
face_count Integer No Number of faces detected in an image. Only relevant if analyzed_faces is true.
file_size Integer No Asset size in bytes.
has_frames Boolean No true if the asset is an animation (video or gif), false otherwise.
media_height Integer No Pixel height of asset.
media_kind String No Type of asset. Possible values: IMAGE, ANIMATION, DOCUMENT, VECTOR.
media_width Integer No Pixel width of asset.
name String Yes User-provided name of asset. Will not change the origin-path.
origin_path String No Path to the asset relative to the Source’s prefix.
source_id String No ID of the Source this asset is associated with.
tags Object Yes Machine-learning generated tags describing the image. Keys are tag text (e.g. “Dog”) and values are floating point numbers representing confidence level, with 0 being not confident and 1 being 100% confident.
uploaded_by String No ID of the user who uploaded this asset via the Asset Manager UI, if it was uploaded.
uploaded_by_api Boolean No true if the asset was uploaded via an API request, false otherwise.
video_aspect_ratio String No Aspect ratio of a video.
video_audio_channel_layout String No Audio channel layout of a video.
video_duration Integer No Video duration expressed in seconds.
video_error_message String No Error message when unable to process video. null otherwise.
video_has_audio Boolean No true if a video has audio, false otherwise.
video_imgix_status String No Processing status of a video. Possible values:
TRANSCODE_STARTED: The video file is processing
VIDEO_READY: The video is processed and ready for playback
ERRORED: There was an issue with processing the video
video_max_stored_frame_rate Float No Max stored frame rate of a video
video_max_stored_resolution String No Max stored resolution of a video
video_max_stored_resolution_x Integer No Max stored width of a video
video_max_stored_resolution_y Integer No Max stored height of a video
video_playback_url String No Video playback URL
warning_adult Integer No Number from 0 to 5 describing the content warning level. Only relevant if analyzed_content_warnings is true. 0 means unknown and 1 is low likelihood while 5 is high likelihood.
warning_medical Integer No Behavior is the same as for warning_adult above.
warning_racy Integer No Behavior is the same as for warning_adult above.
warning_spoof Integer No Behavior is the same as for warning_adult above.
warning_violence Integer No Behavior is the same as for warning_adult above.

Paginating through Asset Lists

Responses containing lists of assets will also include a cursor that looks like this:

"cursor": {
  "current": "20",
  "hasMore": true,
  "next": "22",
  "totalRecords": "68",
}

current corresponds to the the current page, and next is the cursor value you should pass in to retrieve the next page of results, provided that hasMore is true. totalRecords provides a count of the total records found by the search query; however, it returns a maximum count of 1,001 regardless of how many records actually match the query.

Uploading Assets to a Source

The imgix Management API allows you to upload directly to your cloud-storage-backed Source (Azure, GCS, or S3). The API will upload to the same bucket your Source is configured to read from. Uploading to Web Folder or Web Proxy Sources is not supported.

In order to enable uploading for a Source, you need to provide credentials that enable imgix access to upload to your cloud storage. We will refer to these as your Source’s upload_credentials . The credentials you provided when you first set up your Source and that the imgix rendering service uses to fetch assets from your origin are stored separately, and we will refer to these as your deployment_credentials.

The rendering service does not need write permissions to fetch assets, so we highly recommend that you do not use the same credentials for your upload_credentials and your deployment_credentials.

Upload Credentials Attributes

Field Required? Description
type Yes Accepted values are azure, gcs, and s3.
azure_sas_string Yes Required for azure-type Sources only. Read more on how to create Azure credentials.
gcs_access_key Yes Required for gcs-type Sources only.
gcs_secret_key Yes Required for gcs-type Sources only. Will not be returned once it is provided. Read more on how to create GCS credentials.
s3_access_key Yes Required for s3-type Sources only.
s3_secret_key Yes Required for s3-type Sources only. Will not be returned once it is provided. Read more on how to create S3 credentials.

To provide upload_credentials, make a PATCH request to your Source with the new credentials and Source type inside of an upload_credentials object. The type of the upload_credentials must match the Source type and the provided credentials must be valid and supply write permissions to the Source cloud storage bucket.

Here’s an example request to update an S3 Source with upload credentials:

PATCH /api/v1/sources/5ae507164b595f0001e048bc

{
  "data": {
    "attributes": {
      "upload_credentials": {
        "s3_access_key": "<s3-access-key>",
        "s3_secret_key": "<s3-secret-key>",
        "type": "s3"
      }
    },
  "id": "5ae507164b595f0001e048bc",
  "type": "sources"
  }
}

Once your Source has appropriate upload_credentials, you can upload an asset by making a POST request to api/v1/sources/:source_id/upload/:origin_path with the body being the raw asset data. The response will be the same as a GET request to api/v1/assets/:source_id/:origin_path.

Adding an Asset

The add endpoint queues a path from your origin to be added to the Asset Manager. For an asset to be added successfully:

  • The asset path must exist
  • The asset path must return a 200 response from the origin
  • Your Source must have sufficient read permissions

The add endpoint is useful if you are not using the upload endpoint or the Asset Manager UI to upload an asset, and if you are relying on imgix to regularly crawl your origin for new assets.

To add an asset, issue a POST request to sources/:source_id/assets/add/:origin-path with an empty POST body.

Here’s an example:

POST api/v1/sources/5ae507164b595f0001e048bc/assets/add/marketing/logo.png
{}

This returns a 202 empty response from our server. Note the add endpoint only queues an asset for processing. After you've queued an asset, you can poll the get asset endpoint to get the status of the asset after it has been queued.

Refreshing an Asset

Refreshing an asset is useful when an asset has been updated at origin but the automated refresh process imgix uses (which can take 24-48 hours) has not picked up the change yet. In these cases, making a request to refresh the asset will:

  1. Refetch the asset from the origin.
  2. Reprocess the asset if the ETag has changed since the last time the asset was processed.
    • If the asset has never been pulled into the Asset Manager before, the refresh endpoint will pull the asset into the Asset Manager.
  3. Purge the asset from all imgix caches. Note that you may still have to hard refresh your browser to see any updated assets.

To refresh an asset, issue a POST request to sources/:source_id/assets/refresh/:origin-path with an empty POST body.

Here’s an example:

POST api/v1/sources/5ae507164b595f0001e048bc/assets/refresh/marketing/logo.png
{}

If the ETag of the asset differs from the last time the asset was processed the asset will be reprocessed. The asset will then be purged and the response will be similar to the one returned when issuing a GET request to sources/:source_id/assets/:origin_path.

Using Upload Sessions

We recommend using the upload session flow for uploading assets larger than 50MB, such as videos. This is a multi-part, sequential flow that involves creating a session, uploading a file for that session, and finally closing the session. Note: This is currently supported only for Amazon S3 and Google Cloud Storage sources, and supports file sizes up to 5GB.

Upload Session Flow:

  1. Create an upload session. One session should be created per uploaded file. The session and presigned URL will stay open for 8 hours.
  2. Use the session's presigned URL to perform an HTTP PUT to upload the file
  3. Close the session when the upload is complete. Closing the session is not required, but it will expedite asset processing and is strongly recommended. Unclosed sessions will close after 8 hours.
  4. Check upload status to follow processing states. See below for valid upload session states.

Sessions have the following states to track your asset's upload status:

  • PENDING: The session is open.
  • CLOSED: The uploaded asset is being processed by our system.
  • COMPLETE: Processing has been completed. Note that video assets will require additional time to complete the transcoding process.
  • CANCELED: The session has been canceled.

Python Example of Full Upload Session Flow

import os
import requests


API_KEY = ""
BASE_URL = "https://api.imgix.com/api/v1/"
SOURCE_ID = ""
ORIGIN_PATH = ""
LOCAL_FILE = "/path/to/file"


session = requests.post(
    f"{BASE_URL}sources/{SOURCE_ID}/upload-sessions/{ORIGIN_PATH}",
    headers={"Authorization": f"Bearer {API_KEY}"},
).json()

with open(LOCAL_FILE, "rb") as f:
    requests.put(
        session["data"]["attributes"]["url"],
        f.read(),
        headers={"Content-Type": "image/jpeg"},
    )

session_id = session["data"]["id"]
closed_session = requests.post(
    f"{BASE_URL}sources/{SOURCE_ID}/upload-sessions/{session_id}",
    headers={"Authorization": f"Bearer {API_KEY}"},
).json()

Asset Examples

Example: Retrieving details for a single asset

GET /api/v1/assets/5b81e81539ddc50001a5d955/luke.jpg
{
  "data": {
    "attributes": {
      "analyzed_content_warnings": true,
      "analyzed_faces": false,
      "analyzed_tags": true,
      "categories": [
        "Summer Photos"
      ],
      "color_model": "RGB",
      "color_profile": null,
      "colors": {
        "dominant_colors": {
          "#353237": 0.11076190322637558,
          "#545355": 0.07571428269147873,
          "#65a6fa": 0.08052381128072739,
          "#90c4f8": 0.06638095527887344,
          "#927942": 0.002190476283431053,
          "#a39173": 0.0018095237901434302,
          "#b1e7fe": 0.09242857247591019,
          "#e77abc": 0.005857143085449934,
          "#eebbc0": 0.0033333334140479565,
          "#f8f78e": 0.011857142671942711
        }
      },
      "content_type": "image/jpeg",
      "custom_fields": {
        "Dog name": "Luke"
      },
      "date_created": 1569633867,
      "date_modified": 1596825719,
      "description": null,
      "dpi_height": 300,
      "dpi_width": 300,
      "face_count": 0,
      "file_size": 357679,
      "has_frames": false,
      "media_height": 1825,
      "media_kind": "IMAGE",
      "media_width": 1704,
      "name": null,
      "origin_path": "/luke.jpg",
      "source_id": "5b81e81539ddc50001a5d955",
      "tags": {
        "Canidae": 0.9813780188560486,
        "Carnivore": 0.8667572736740112,
        "Dog": 0.9953705072402954,
        "Dog breed": 0.9838448762893677,
        "Havanese": 1,
        "Mammal": 0.975814163684845,
        "Puppy": 0.8966773748397827,
        "Schnoodle": 0,
        "Sporting Group": 0.8070302605628967,
        "Vertebrate": 0.9851104021072388
      },
      "uploaded_by": null,
      "uploaded_by_api": false,
      "warning_adult": 1,
      "warning_medical": 1,
      "warning_racy": 1,
      "warning_spoof": 2,
      "warning_violence": 1
    },
    "id": "5b81e81539ddc50001a5d955/luke.jpg",
    "type": "assets"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "authentication": {
      "authorized": true,
      "clientId": null,
      "mode": "PUBLIC_APIKEY",
      "modeTitle": "Public API Key",
      "tag": "cindy@ymail.com",
      "user": null
    },
    "server": {
      "commit": "8835d05b",
      "status": {
        "healthy": true,
        "read_only": false,
        "tombstone": false
      },
      "version": "3.120.0"
    }
  }
}

Example: Updating categories and custom fields of an asset

PATCH /api/v1/assets/5b81e81539ddc50001a5d955/luke.jpg

{
  "data": {
    "attributes": {
      "categories": [
        "Summer Photos",
        "Pet Photos"
       ],
       "custom_fields": {
         "Date taken": "August 2020",
         "Photographer": "Molly"
       }
    },
    "type": "assets",
     "id": "5b81e81539ddc50001a5d955/luke.jpg"
    }
}
{
  "data": {
    "attributes": {
      "categories": [
        "Summer Photos",
        "Pet Photos"
       ],
       ...
       "custom_fields": {
         "Date taken": "August 2020",
         "Photographer": "Molly"
       },
       ...
    }
    ...
 }

Example: Retrieving the second page of assets in a Source

GET /api/v1/assets/5b81e81539ddc50001a5d955?page[cursor]=40&page[limit]=20
{
  "data": [
     ...
   ],
   ...
   "cursor": {
     "current": "40",
     "estimatedRecords": null,
     "hasMore": true,
     "next": "60",
     "totalRecords": null
    }
    ...
}

Example: Retrieving assets, filtered by color and sorted by date created, most recent first

GET /api/v1/assets/5b81e81539ddc50001a5d955?filter[colors]=8ca091&sort=-date_created
{
  "data": [
    {
      "attributes": {
      ...
        "colors": {
          "dominant_colors": {
            "#1b181a": 0.08416759222745895,
            "#343235": 0.09766407310962677,
            "#535153": 0.059176862239837646,
            "#a32438": 0.00037078236346133053,
            "#a49d97": 0.039377085864543915,
            "#b19f89": 0.05094549432396889,
            "#c8c1ba": 0.06518353521823883,
            "#d0bfa9": 0.10700778663158417,
            "#efe2cf": 0.06436781585216522,
            "#f7f3ee": 0.2693363130092621
          }
        },
        "content_type": "image/png",
        "custom_fields": null,
        "date_created": 1589337592,
    ...
      },
      "id": "5b81e81539ddc50001a5d955/images/frances.jpg",
      "type": "assets"
    },
    {
      "attributes": {
      ...
        "colors": {
          "dominant_colors": {
            "#160802": 0.11790844798088074,
            "#230a03": 0.009009009227156639,
            "#2f1104": 0.04248843342065811,
            "#6a5340": 0.04790601506829262,
            "#6e4a36": 0.07487216591835022,
            "#8b6c5a": 0.010409058071672916,
            "#907864": 0.11200389266014099,
            "#a4958c": 0.011626491323113441,
            "#af967f": 0.1546749472618103,
            "#c4ae97": 0.0022522523067891598
          }
        },
        "content_type": "image/jpeg",
        "custom_fields": null,
        "date_created": 1587358372,
        ...
      },
      "id": "5b81e81539ddc50001a5d955/images/luke.jpg",
      "type": "assets"
    },
    ...
  ],
  ...
}

Example: Uploading an asset to a Source

POST /api/v1/sources/5b81e81539ddc50001a5d955/upload/marketing/logo.png

<raw binary image file>
{
  "data": {
    "attributes": {
      ...
      "origin_path": "/marketing/logo.png",
      "tags": {
        "Brand": 0.772368848323822,
        "Clip art": 0.5367497801780701,
        "Font": 0.9227379560470581,
        "Graphics": 0.7015061974525452,
        "Line": 0.7984547019004822,
        "Logo": 0.9082068800926208,
        "Text": 0.9606743454933167,
        "Trademark": 0.7562870383262634
      },
      ...
    },
    "id": "5b81e81539ddc50001a5d955/marketing/logo.png",
    "type": "assets"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
   ...
  }
}

Example: Creating an upload session

POST /api/v1/sources/5b81e81539ddc50001a5d955/upload-sessions/create/marketing/logo.png
{
  "data": {
    "attributes": {
      "date_created": 1653506429,
      "date_expires": 1653535229,
      "date_modified": 1653506429,
      "id": "77c0f903-9475-4a6a-9fad-3995a5ad8cfe",
      "origin_path": "/marketing/logo.png",
      "source_id": "5b81e81539ddc50001a5d955",
      "status": "PENDING",
      "url": "$PRESIGNED_UPLOAD_URL"
    },
    "id": "77c0f903-9475-4a6a-9fad-3995a5ad8cfe",
    "type": "asset_uploads"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}

Example: Using the presigned URL to upload an asset, using the `url` from the newly created upload session

curl -XPUT $PRESIGNED_URL -T 'image.jpg'

Example: Retrieving an upload session

GET /api/v1/sources/5b81e81539ddc50001a5d955/upload-sessions/status/77c0f903-9475-4a6a-9fad-3995a5ad8cfe
{
  "data": {
    "attributes": {
      "date_created": 1653506429,
      "date_expires": 1653535229,
      "date_modified": 1653506429,
      "id": "77c0f903-9475-4a6a-9fad-3995a5ad8cfe",
      "origin_path": "/marketing/logo.png",
      "source_id": "5b81e81539ddc50001a5d955",
      "status": "PENDING"
    },
    "id": "77c0f903-9475-4a6a-9fad-3995a5ad8cfe",
    "type": "asset_uploads"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}

Example: Closing an upload session

POST /api/v1/sources/5b81e81539ddc50001a5d955/upload-sessions/close/77c0f903-9475-4a6a-9fad-3995a5ad8cfe
{
  "data": {
    "attributes": {
      ...
      "status": "CLOSED"
    },
    "id": "77c0f903-9475-4a6a-9fad-3995a5ad8cfe",
    "type": "asset_uploads"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}

Example: Canceling an upload session

DELETE /api/v1/sources/5b81e81539ddc50001a5d955/upload-sessions/cancel/77c0f903-9475-4a6a-9fad-3995a5ad8cfe
{
  "data": {
    "attributes": {
      ...
      "status": "CANCELED"
    },
    "id": "77c0f903-9475-4a6a-9fad-3995a5ad8cfe",
    "type": "asset_uploads"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}

Reports

Note: Reports are an Enterprise feature and may not be enabled for all accounts. Contact Support or your Account Manager to find out more.

Reports are updated once per day and are retained for 90 days after being finalized. Reports are finalized at 00:00 UTC and are available via API by 01:00 UTC.

Report Operations

Open in Postman

Report operations require the Analytics permission.

Endpoint Method Description
reports GET Retrieve a list of all available reports
reports/:report_id GET Retrieve a single report by id

Report Filters

Filter Type Notes
completed Boolean Whether report is fully completed or not.
report_type String Report type. See below for supported report types.

Report Sorts

  • period_end
  • period_start
  • report_key
  • report_type

Report Attributes

Field Type Description
completed Boolean Whether the report is complete.
files List List of URLs where each URL is a downloadable report. File sizes are limited to 64MB so if the report is larger than that it may be split into multiple files.
period_end Integer End of the time period covered by the report, expressed as a unix timestamp.
period_start Integer Beginning of the time period covered by the report, expressed as a unix timestamp.
report_key String Human-readable ID for each report, e.g. source_analytics_20201130.
report_type String Report type. See below for supported report types.

Report Types

Type Description
cdn_logs Contains daily logs for requests made to our CDN for your images. Includes information such as referrers, user agents, cache hits/misses per image, and more. Example file.

For the referers and user_agent column, blank values indicate that there was no referer or user-agent data sent to imgix.
image_analytics Contains daily metrics for each Origin Image. Includes the number of requests and errors generated by each Origin Image URL. Example file.
mild_errors Contains data related to 4xx-level errors per image. Example file.
source_analytics Contains cumulative metrics for each Source. Includes information regarding total Origin Images, total bandwidth, average response times, and more. Example file.

Since this report is cumulative, the report generated for July 31 will have Source analytics for that entire month. The report generated for July 15th will have the July Source analytics up to that day.

Report Examples

Example: Retrieve a list of reports

GET /api/v1/reports
{
  "data": [
    {
      "attributes": {
        "completed": true,
        "files": [
          ...
        ],
        "period_end": 1601769600,
        "period_start": 1601769600,
        "report_key": "image_analytics_20201004",
        "report_type": "image_analytics"
      },
      "id": "5f7a6ab42528f162276c5584",
      "relationships": {
        ...
      },
      "type": "reports"
    },
    {
      "attributes": {
        "completed": true,
        "files": [
          ...
        ],
        "period_end": 1601769600,
        "period_start": 1601769600,
        "report_key": "source_analytics_20201004",
        "report_type": "source_analytics"
      },
      "id": "5f7a6b9a2528f16239772ab8",
      "relationships": {
        ...
      },
      "type": "reports"
    },
    ...
  ],
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "authentication": {
      ...
    },
    "pagination": {
      "currentPage": 0,
      "hasNextPage": false,
      "hasPreviousPage": false,
      "nextPage": 0,
      "pageSize": 20,
      "previousPage": 0,
      "totalPages": 1,
      "totalRecords": 16
    },
    "server": {
      ...
    }
  }
}

Example: Retrieve one report by report_id

GET /api/v1/reports/5f7676862528f12b1bfbf65b
{
  "data": {
    "attributes": {
      "completed": true,
      "files": [
          "https://storage.googleapis.com/imgix-reports/..."
      ],
      "period_end": 1601510400,
      "period_start": 1601510400,
      "report_key": "image_analytics_20201001",
      "report_type": "image_analytics"
    },
    "id": "5f7676862528f12b1bfbf65b",
    "relationships": {
      "account": {
        "data": {
          "id": "5ae39a60781cee0001020d8f",
          "type": "accounts"
        }
      }
    },
    "type": "reports"
  },
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}

Example: Retrieve mild_errors report, sorted by most recent first

GET /api/v1/reports?sort=-period_end&fields[reports]=report_key,files&filter[report_type]=mild_errors
{
  "data": [
    {
      "attributes": {
        "files": [
          "https://storage.googleapis.com/imgix-reports/..."
        ],
        "report_key": "mild_errors_20201006"
      },
      "id": "5f7d0f842528f160f103836d",
      "relationships": {},
      "type": "reports"
    },
    {
      "attributes": {
        "files": [
          "https://storage.googleapis.com/imgix-reports/..."
        ],
        "report_key": "mild_errors_20201005"
      },
      "id": "5f7bbec22528f12bbde9db3d",
      "relationships": {},
      "type": "reports"
    },
    {
      "attributes": {
        "files": [
          "https://storage.googleapis.com/imgix-reports/..."
        ],
        "report_key": "mild_errors_20201004"
      },
      "id": "5f7a6bc82528f1623a2fdaf6",
      "relationships": {},
      "type": "reports"
    },
    ...
  ],
  "included": [],
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    ...
  }
}