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/`).
`username`	String	Yes	Username used for sending Basic Auth headers to Origin. Output as `Basic {base64encode(username:password)}`. Can not contain `:` or any control characters (opens in a new tab)
`password`	String	Yes	Password used for sending Basic Auth headers to Origin. Output as `Basic {base64encode(username:password)}`. Can not contain `:` or any control characters (opens in a new tab)
`password_encrypted`	String	No	Encrypted password value for Basic Auth headers. Sent in `GET` requests for Sources
`request_handshake`	String	Yes	32 latin-1 character string used for Custom Header Authentication Origin authentication.
`request_handshake_encrypted`	String	No	Encrypted `request_handshake` value for Origin Authentication. Sent in `GET` requests for Sources
`request_signing_key`	String	Yes	32 latin-1 character string used for Per-Request Signing Origin authentication.
`request_signing_key_encrypted`	String	No	Encrypted `request_signing_key` value for Origin Authentication. Sent in `GET` requests for Sources

*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

Field	Type	Updatable?	Description
`username`	String	Yes	Username used for sending Basic Auth headers to Origin. Output as `Basic {base64encode(username:password)}`. Cannot contain `:` or any control characters (opens in a new tab)
`password`	String	Yes	Password used for sending Basic Auth headers to Origin. Output as `Basic {base64encode(username:password)}`. Cannot contain `:` or any control characters (opens in a new tab)
`password_encrypted`	String	No	Encrypted password value for Basic Auth headers. Sent in `GET` requests for Sources
`request_handshake`	String	Yes	32 latin-1 character string used for Custom Header Authentication Origin authentication.
`request_handshake_encrypted`	String	No	Encrypted `request_handshake` value for Origin Authentication. Sent in `GET` requests for Sources
`request_signing_key`	String	Yes	32 latin-1 character string used for Per-Request Signing Origin authentication.
`request_signing_key_encrypted`	String	No	Encrypted `request_signing_key` value for Origin Authentication. Sent in `GET` requests for Sources

Source Examples

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

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

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"
    }
}

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"
  }
}

Reports