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.

Purging 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

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": {
    ...
  }
}

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": {
    ...
  }
}

Assets Reports