AWS Documentation » Amazon CloudFront » API Reference » Actions on Download Distributions » POST Distribution	« Previous Next »
	Did this page help you? Yes \| No \| Tell us about it...

POST Distribution

Topics

Description

This action creates a new download distribution. By default, you can create a combined total of up to 100 download and streaming distributions per AWS account. To request a higher limit, fill out the form at http://aws.amazon.com/cloudfront-request/.

To create a new download distribution, you do a POST on the 2012-07-01/distribution resource. The request body must include an XML document with a DistributionConfig element. The response echoes the DistributionConfig element and returns other information about the distribution.

To get the status of your request, use the GET Distribution API action. When the value of the Enabled element is true and the value of the Status element is Deployed, your distribution is ready. A distribution usually deploys in less that 15 minutes. For more information, see GET Distribution.

For more information about download distributions, go to Working with Download Distributions in the Amazon CloudFront Developer Guide.

Important

Beginning with the 2012-05-05 version of the CloudFront API, we made substantial changes to the format of the XML document that you include in the request body when you create or update a download distribution or a streaming distribution, and when you invalidate objects. With previous versions of the API, we discovered that it was too easy to accidentally delete one or more values for an element that accepts multiple values, for example, CNAMEs and trusted signers. Our changes for the 2012-05-05 release are intended to prevent these accidental deletions and to notify you when there's a mismatch between the number of values you say you're specifying in the Quantity element and the number of values you're actually specifying.

Requests

Syntax

POST /2012-07-01/distribution HTTP/1.1
Host: cloudfront.amazonaws.com
Authorization: AWS authentication string
Date: time stamp
Other required headers

<?xml version="1.0" encoding="UTF-8"?>
<DistributionConfig xmlns="http://cloudfront.amazonaws.com/doc/2012-07-01/">
   <CallerReference>unique description for this
      distribution config</CallerReference>
   <Aliases>
      <Quantity>number of CNAME aliases</Quantity>
      <!-- Optional. Omit when Quantity = 0. -->
      <Items>
         <CNAME>CNAME alias</CNAME>
      </Items>
   </Aliases>
   <DefaultRootObject>URL for default root object</DefaultRootObject>
   <Origins>
      <Quantity>number of origins</Quantity>
      <Items>
         <Origin>
            <Id>unique identifier for this origin</Id>
            <DomainName>domain name of origin</DomainName>
            <!-- Include the S3OriginConfig element only if 
               you use an Amazon S3 origin for your distribution. -->
            <S3OriginConfig>
               <OriginAccessIdentity>origin-access-identity/
                  cloudfront/ID</OriginAccessIdentity>
            </S3OriginConfig>
            <!-- Include the CustomOriginConfig element only if 
               you use a custom origin for your distribution. -->
            <CustomOriginConfig>
               <HTTPPort>HTTP port that the custom origin 
                  listens on</HTTPPort>
               <HTTPSPort>HTTPS port that the custom origin 
                  listens on</HTTPSPort>
               <OriginProtocolPolicy>http-only | 
                  match-viewer</OriginProtocolPolicy>
            </CustomOriginConfig>
         </Origin>
      </Items>
   </Origins>
   <DefaultCacheBehavior>
      <TargetOriginId>ID of the origin that the default cache behavior 
         applies to</TargetOriginId>
      <ForwardedValues>
         <QueryString>true | false</QueryString>
         <Cookies>
            <Forward>all | whitelist | none</Forward>
            <!-- Required when Forward = whitelist, 
               omitted otherwise. -->
            <WhitelistedNames>
               <Quantity>number of cookie names to 
                  forward to origin</Quantity>
               <Items>
                  <Name>name of a cookie to forward to 
                     the origin</Name>
               </Items>
            </WhitelistedNames>
         </Cookies>
      </ForwardedValues>
      <TrustedSigners>
         <Enabled>true | false</Enabled>
         <Quantity>number of trusted signers</Quantity>
         <!-- Optional. Omit when Quantity = 0. -->
         <Items>
            <AwsAccountNumber>self | AWS account that can create 
               signed URLs</AwsAccountNumber>
         </Items>
      </TrustedSigners>
      <ViewerProtocolPolicy>allow-all | 
         https-only</ViewerProtocolPolicy>
      <MinTTL>minimum TTL in seconds</MinTTL>
   </DefaultCacheBehavior>
   <CacheBehaviors>
      <Quantity>number of cache behaviors</Quantity>
      <!-- Optional. Omit when Quantity = 0. -->
      <Items>
         <CacheBehavior>
            <PathPattern>pattern that specifies files that this 
               cache behavior applies to</PathPattern>
            <TargetOriginId>ID of the origin that this cache behavior 
               applies to</TargetOriginId>
            <ForwardedValues>
               <QueryString>true | false</QueryString>
               <Cookies>
                  <Forward>all | whitelist | none</Forward>
                  <!-- Required when Forward = whitelist, 
                     omitted otherwise. -->
                  <WhitelistedNames>
                     <Quantity>number of cookie names to forward 
                        to origin</Quantity>
                     <Items>
                        <Name>name of a cookie to forward to 
                           the origin</Name>
                     </Items>
                  </WhitelistedNames>
               </Cookies>
            </ForwardedValues>
            <TrustedSigners>
               <Enabled>true | false</Enabled>
               <Quantity>number of trusted signers</Quantity>
               <!-- Optional. Omit when Quantity = 0. -->
               <Items>
                  <AwsAccountNumber>self | AWS account that can create 
                     signed URLs</AwsAccountNumber>
               </Items>
            </TrustedSigners>
            <ViewerProtocolPolicy>allow-all | 
               https-only</ViewerProtocolPolicy>
            <MinTTL>minimum TTL in seconds for files 
               specified by PathPattern</MinTTL>
         </CacheBehavior>
      </Items>
   </CacheBehaviors>
   <Comment>comment about the distribution</Comment>
   <Logging>
      <Enabled>true | false</Enabled>
      <IncludeCookies>true | false</IncludeCookies>
      <Bucket>Amazon S3 bucket to save logs in</Bucket>
      <Prefix>prefix for log filenames</Prefix>
   </Logging>
   <PriceClass>maximum price class for the distribution</PriceClass>
   <Enabled>true | false</Enabled>
</DistributionConfig>

Headers

The request must include the headers required in all CloudFront requests. For more information, see Common REST Headers.

Elements

Name Description

Name	Description
`DistributionConfig`	The distribution's configuration information. For more information, see DistributionConfig Complex Type. Type: `DistributionConfig` complex type Default: None

DistributionConfig

The distribution's configuration information. For more information, see DistributionConfig Complex Type.

Type: DistributionConfig complex type

Default: None

Responses

Syntax

201 Created
Location: URI of new distribution
x-amz-request-id: Request ID

<?xml version="1.0" encoding="UTF-8"?>
<Distribution xmlns="http://cloudfront.amazonaws.com/doc/2012-07-01/">
   <Id>ID for the distribution</Id>
   <Status>Deployed | InProgress</Status>
   <LastModifiedTime>creation date and time in 
      ISO 8601 format</LastModifiedTime>
   <InProgressInvalidationBatches>number of invalidation batches being 
      processed for this distribution</InProgressInvalidationBatches>
   <DomainName>CloudFront domain name assigned to the 
      distribution</DomainName>
   <ActiveTrustedSigners>
      <Enabled>true | false</Enabled>
      <Quantity>number of unique trusted signers from 
         all cache behaviors</Quantity>
      <Items>
         <Signer>
            <AwsAccountNumber>self | AWS account number</AwsAccountNumber>
            <KeyPairIds>
               <Quantity>number of active key pairs for 
                  AwsAccountNumber</Quantity>
               <Items>
                  <KeyPairId>active key pair associated with 
                     AwsAccountNumber</KeyPairId>
               </Items>
            </KeyPairIds>
         </Signer>
      </Items>
   </ActiveTrustedSigners>
   <DistributionConfig>
      <CallerReference>unique description for this
         distribution config</CallerReference>
      <Aliases>
         <Quantity>number of CNAME aliases</Quantity>
         <!-- Optional. Omitted when Quantity = 0. -->
         <Items>
            <CNAME>CNAME alias</CNAME>
         </Items>
      </Aliases>
      <DefaultRootObject>URL for default root object</DefaultRootObject>
      <Origins>
         <Quantity>number of origins</Quantity>
         <Items>
            <Origin>
               <Id>unique identifier for this origin</Id>
               <DomainName>domain name of origin</DomainName>
               <!-- CloudFront returns the S3OriginConfig element 
                  only if you use an Amazon S3 origin. --> 
               <S3OriginConfig>
                  <OriginAccessIdentity>origin-access-identity/
                     cloudfront/ID</OriginAccessIdentity>
               </S3OriginConfig>
               <!-- CloudFront returns the CustomOriginConfig element 
                  only if you use a custom origin. -->
               <CustomOriginConfig>
                  <HTTPPort>HTTP port that the custom origin 
                     listens on</HTTPPort>
                  <HTTPSPort>HTTPS port that the custom origin 
                     listens on</HTTPSPort>
                  <OriginProtocolPolicy>http-only | 
                     match-viewer</OriginProtocolPolicy>
               </CustomOriginConfig>
            </Origin>
         </Items>
      </Origins>
      <DefaultCacheBehavior>
         <TargetOriginId>ID of the origin that the default cache behavior 
            applies to</TargetOriginId>
         <ForwardedValues>
            <QueryString>true | false</QueryString>
            <Cookies>
               <Forward>all | whitelist | none</Forward>
               <!-- Required when Forward = whitelist, omitted otherwise. -->
               <WhitelistedNames>
                  <Quantity>number of cookie names to 
                     forward to origin</Quantity>
                  <Items>
                     <Name>name of a cookie to forward to the origin</Name>
                  </Items>
               </WhitelistedNames>
            </Cookies>
         </ForwardedValues>
         <TrustedSigners>
            <Enabled>true | false</Enabled>
            <Quantity>number of trusted signers</Quantity>
            <!-- Optional. Omitted when Quantity = 0. -->
            <Items>
               <AwsAccountNumber>self | AWS account that can create 
                  signed URLs</AwsAccountNumber>
            </Items>
         </TrustedSigners>
         <ViewerProtocolPolicy>allow-all | 
            https-only</ViewerProtocolPolicy>
         <MinTTL>minimum TTL in seconds</MinTTL>
      </DefaultCacheBehavior>
      <CacheBehaviors>
         <Quantity>number of cache behaviors</Quantity>
         <!-- Optional. Omitted when Quantity = 0. -->
         <Items>
            <CacheBehavior>
               <PathPattern>pattern that specifies files that this 
                  cache behavior applies to</PathPattern>
               <TargetOriginId>ID of the origin that this cache behavior 
                  applies to</TargetOriginId>
               <ForwardedValues>
                  <QueryString>true | false</QueryString>
                  <Cookies>
                     <Forward>all | whitelist | none</Forward>
                     <!-- Required when Forward = whitelist, 
                        omitted otherwise. -->
                     <WhitelistedNames>
                        <Quantity>number of cookie names to 
                           forward to origin</Quantity>
                        <Items>
                           <Name>name of a cookie to forward to 
                              the origin</Name>
                        </Items>
                     </WhitelistedNames>
                  </Cookies>
               </ForwardedValues>
               <TrustedSigners>
                  <Enabled>true | false</Enabled>
                  <Quantity>number of trusted signers</Quantity>
                  <!-- Optional. Omitted when Quantity = 0. -->
                  <Items>
                     <AwsAccountNumber>self | AWS account that can create 
                        signed URLs</AwsAccountNumber>
                  </Items>
               </TrustedSigners>
               <ViewerProtocolPolicy>allow-all | 
                  https-only</ViewerProtocolPolicy>
               <MinTTL>minimum TTL in seconds for files 
                  specified by PathPattern</MinTTL>
            </CacheBehavior>
         </Items>
      </CacheBehaviors>
      <Comment>comment about the distribution</Comment>
      <Logging>
         <Enabled>true | false</Enabled>
         <IncludeCookies>true | false</IncludeCookies>
         <Bucket>Amazon S3 bucket to save logs in</Bucket>
         <Prefix>prefix for log filenames</Prefix>
      </Logging>
      <PriceClass>maximum price class for the distribution</PriceClass>
      <Enabled>true | false</Enabled>
   </DistributionConfig>
</Distribution>

Headers

Name Description

Name	Description
`Location`	The fully qualified URI of the new distribution resource just created, for example, `https://cloudfront.amazonaws.com/2012-07-01/distribution/EDFDVBD6EXAMPLE` Type: String

Location

The fully qualified URI of the new distribution resource just created, for example, https://cloudfront.amazonaws.com/2012-07-01/distribution/EDFDVBD6EXAMPLE

Type: String

Elements

Name Description

Name	Description
`Distribution`	The distribution's information. For more information, see Distribution Complex Type. Type: `Distribution` datatype

Distribution

The distribution's information. For more information, see Distribution Complex Type.

Type: Distribution datatype

Special Errors

The following table lists the special errors returned in addition to the common errors all actions return. For more information, see Errors.

Error	Description	HTTP Status Code
`CNAMEAlreadyExists`	One or more of the CNAMEs you provided are already associated with a different distribution.	409
`DistributionAlreadyExists`	The caller reference you attempted to create the distribution with is associated with another distribution.	409
`InvalidOrigin`	The Amazon S3 origin server specified does not refer to a valid Amazon S3 bucket.	400
`InvalidOriginAccessIdentity`	The origin access identity is not valid or doesn't exist.	400
`InvalidRequiredProtocol`	This operation requires the HTTPS protocol. Ensure that you specify the HTTPS protocol in your request, or omit the `RequiredProtocols` element from your distribution configuration.	400
`MissingBody`	This operation requires a body. Ensure that the body is present and the Content-Type header is set.	400
`TooManyDistributionCNAMEs`	Your request contains more CNAMEs than are allowed per distribution.	400
`TooManyDistributions`	Processing your request would cause you to exceed the maximum number of distributions allowed.	400
`TooManyTrustedSigners`	Your request contains more trusted signers than are allowed per distribution.	400
`TrustedSignerDoesNotExist`	One or more of your trusted signers do not exist.	400

Example

The following example request creates a new download distribution that has two origins: an Amazon S3 bucket and a custom origin. The request includes a CNAME alias and enables logging.

Sample Request

POST /2012-07-01/distribution HTTP/1.1
Host: cloudfront.amazonaws.com
Authorization: AWS authentication string
Date: Thu, 17 May 2012 19:37:58 GMT
Other required headers

<?xml version="1.0" encoding="UTF-8"?>
<DistributionConfig xmlns="http://cloudfront.amazonaws.com/doc/2012-07-01/">
   <CallerReference>example.com2012-04-11-5:09pm</CallerReference>
   <Aliases>
      <Quantity>1</Quantity>
      <Items>
         <CNAME>www.example.com</CNAME>
      </Items>
   </Aliases>
   <DefaultRootObject>index.html</DefaultRootObject>
   <Origins>
      <Quantity>2</Quantity>
      <Items>
         <Origin>
            <Id>example-Amazon S3-origin</Id>
            <DomainName>myawsbucket.s3.amazonaws.com</DomainName>
            <S3OriginConfig>
               <OriginAccessIdentity>origin-access-identity/cloudfront/E74FTE3AEXAMPLE</OriginAccessIdentity>
            </S3OriginConfig>
         </Origin>
         <Origin>
            <Id>example-custom-origin</Id>
            <DomainName>example.com</DomainName>
            <CustomOriginConfig>
               <HTTPPort>80</HTTPPort>
               <HTTPSPort>443</HTTPSPort>
               <OriginProtocolPolicy>match-viewer</OriginProtocolPolicy>
            </CustomOriginConfig>
         </Origin>
      </Items>
   </Origins>
   <DefaultCacheBehavior>
      <TargetOriginId>example-Amazon S3-origin</TargetOriginId>
      <ForwardedValues>
         <QueryString>true</QueryString>
         <Cookies>
            <Forward>whitelist</Forward>
            <WhitelistedNames>
               <Quantity>1</Quantity>
               <Items>
                  <Name>example-cookie</Name>
               </Items>
            </WhitelistedNames>
         </Cookies>
      </ForwardedValues>
      <TrustedSigners>
         <Enabled>true</Enabled>
         <Quantity>3</Quantity>
         <Items>
            <AwsAccountNumber>self</AwsAccountNumber>
            <AwsAccountNumber>111122223333</AwsAccountNumber>
            <AwsAccountNumber>444455556666</AwsAccountNumber>
         </Items>
      </TrustedSigners>
      <ViewerProtocolPolicy>https-only</ViewerProtocolPolicy>
      <MinTTL>0</MinTTL>
   </DefaultCacheBehavior>
   <CacheBehaviors>
      <Quantity>1</Quantity>
      <Items>
         <CacheBehavior>
            <PathPattern>*.jpg</PathPattern>
            <TargetOriginId>example-custom-origin</TargetOriginId>
            <ForwardedValues>
               <QueryString>false</QueryString>
               <Cookies>
                  <Forward>all</Forward>
               </Cookies>
            </ForwardedValues>
            <TrustedSigners>
               <Enabled>true</Enabled>
               <Quantity>2</Quantity>
               <Items>
                  <AwsAccountNumber>self</AwsAccountNumber>
                  <AwsAccountNumber>111122223333</AwsAccountNumber>
               </Items>
            </TrustedSigners>
            <ViewerProtocolPolicy>allow-all</ViewerProtocolPolicy>
            <MinTTL>86400</MinTTL>
         </CacheBehavior>
      </Items>
   </CacheBehaviors>
   <Comment>example comment</Comment>
   <Logging>
      <Enabled>true</Enabled>
      <IncludeCookies>true</IncludeCookies>
      <Bucket>myawslogbucket.s3.amazonaws.com</Bucket>
      <Prefix>example.com.</Prefix>
   </Logging>
   <PriceClass>PriceClass_All</PriceClass>
   <Enabled>true</Enabled>
</DistributionConfig>

Sample Response

201 Created
Location: https://cloudfront.amazonaws.com/2012-07-01/distribution/EDFDVBD6EXAMPLE
x-amz-request-id: request_id

<?xml version="1.0" encoding="UTF-8"?>
<Distribution xmlns="http://cloudfront.amazonaws.com/doc/2012-07-01/">
   <Id>EDFDVBD6EXAMPLE</Id>
   <Status>Deployed</Status>
   <LastModifiedTime>2012-05-19T19:37:58Z</LastModifiedTime>
   <InProgressInvalidationBatches>1</InProgressInvalidationBatches>
   <DomainName>d111111abcdef8.cloudfront.net</DomainName>
   <ActiveTrustedSigners>
      <Quantity>3</Quantity>
      <Items>
         <Signer>
            <AwsAccountNumber>self</AwsAccountNumber>
            <KeyPairIds>
               <Quantity>1</Quantity>
               <Items>
                  <KeyPairId>APKA9ONS7QCOWEXAMPLE</KeyPairId>
               </Items>
            </KeyPairIds>
         </Signer>
         <Signer>
            <AwsAccountNumber>111122223333</AwsAccountNumber>
            <KeyPairIds>
               <Quantity>2</Quantity>
               <KeyPairId>APKAI72T5DYBXEXAMPLE</KeyPairId>
               <KeyPairId>APKAU72D8DYNXEXAMPLE</KeyPairId>
            </KeyPairIds>
         </Signer>
         <Signer>
            <AwsAccountNumber>444455556666</AwsAccountNumber>
            <KeyPairIds>
               <Quantity>0</Quantity>
            </KeyPairIds>
         </Signer>
      </Items>
   </ActiveTrustedSigners>
   <DistributionConfig>
      <CallerReference>example.com2012-04-11-5:09pm</CallerReference>
      <Aliases>
         <Quantity>1</Quantity>
         <Items>
            <CNAME>www.example.com</CNAME>
         </Items>
      </Aliases>
      <DefaultRootObject>index.html</DefaultRootObject>
      <Origins>
         <Quantity>2</Quantity>
         <Items>
            <Origin>
               <Id>example-Amazon S3-origin</Id>
               <DomainName>myawsbucket.s3.amazonaws.com</DomainName>
               <S3OriginConfig>
                  <OriginAccessIdentity>origin-access-identity/cloudfront/E74FTE3AEXAMPLE</OriginAccessIdentity>
               </S3OriginConfig>
            </Origin>
            <Origin>
               <Id>example-custom-origin</Id>
               <DomainName>example.com</DomainName>
               <CustomOriginConfig>
                  <HTTPPort>80</HTTPPort>
                  <HTTPSPort>443</HTTPSPort>
                  <OriginProtocolPolicy>match-viewer</OriginProtocolPolicy>
               </CustomOriginConfig>
            </Origin>
         </Items>
      </Origins>
      <DefaultCacheBehavior>
         <TargetOriginId>example-Amazon S3-origin</TargetOriginId>
         <ForwardedValues>
            <QueryString>true</QueryString>
            <Cookies>
               <Forward>whitelist</Forward>
               <WhitelistedNames>
                  <Quantity>1</Quantity>
                  <Items>
                     <Name>example-cookie</Name>
                  </Items>
               </WhitelistedNames>
            </Cookies>
         </ForwardedValues>
         <TrustedSigners>
            <Enabled>true</Enabled>
            <Quantity>3</Quantity>
            <Items>
               <AwsAccountNumber>self</AwsAccountNumber>
               <AwsAccountNumber>111122223333</AwsAccountNumber>
               <AwsAccountNumber>444455556666</AwsAccountNumber>
            </Items>
         </TrustedSigners>
         <ViewerProtocolPolicy>https-only</ViewerProtocolPolicy>
         <MinTTL>0</MinTTL>
      </DefaultCacheBehavior>
      <CacheBehaviors>
         <Quantity>1</Quantity>
         <Items>
            <CacheBehavior>
               <PathPattern>*.jpg</PathPattern>
               <TargetOriginId>example-custom-origin</TargetOriginId>
               <ForwardedValues>
                  <QueryString>false</QueryString>
                  <Cookies>
                     <Forward>all</Forward>
                  </Cookies>
               </ForwardedValues>
               <TrustedSigners>
                  <Enabled>true</Enabled>
                  <Quantity>2</Quantity>
                  <Items>
                     <AwsAccountNumber>self</AwsAccountNumber>
                     <AwsAccountNumber>111122223333</AwsAccountNumber>
                  </Items>
               </TrustedSigners>
               <ViewerProtocolPolicy>allow-all</ViewerProtocolPolicy>
               <MinTTL>86400</MinTTL>
            </CacheBehavior>
         </Items>
      </CacheBehaviors>
      <Comment>example comment</Comment>
      <Logging>
         <Enabled>true</Enabled>
         <IncludeCookies>true</IncludeCookies>
         <Bucket>myawslogbucket.s3.amazonaws.com</Bucket>
         <Prefix>example.com.</Prefix>
      </Logging>
      <PriceClass>PriceClass_All</PriceClass>
      <Enabled>true</Enabled>
   </DistributionConfig>
</Distribution>

Related Actions

Document Conventions	« Previous Next »
Terms of Use	Did this page help you? Yes \| No \| Tell us about it...