Management API
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 thesources
endpoint, it will be in the JSON response under theid
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.
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
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
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
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 processingVIDEO_READY : The video is processed and ready for playbackERRORED : 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:
- Refetch the asset from the origin.
- 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.
- 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:
- Create an upload session. One session should be created per uploaded file. The session and presigned URL will stay open for 8 hours.
- Use the session's presigned URL to perform an HTTP PUT to upload the file
- 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.
- 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
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": {
...
}
}