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 |
deploymeny.type | String | All. Possible values are azure , gcs , s3 , webfolder , webproxy , s3_compatible |
deployment.webfolder_base_url | String | Web Folder |
enabled | Boolean | All |
name | String | All |
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 , s3_compatible . 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"
}
}