# PutDestination Creates or updates a destination. This operation is used only to create destinations for cross-account subscriptions. A destination encapsulates a physical resource (such as an Amazon Kinesis stream). With a destination, you can subscribe to a real-time stream of log events for a different account, ingested using [PutLogEvents](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutLogEvents.html). Through an access policy, a destination controls what is written to it. By default, `PutDestination` does not set any access policy with the destination, which means a cross-account user cannot call [PutSubscriptionFilter](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutSubscriptionFilter.html) against this destination. To enable this, the destination owner must call [PutDestinationPolicy](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDestinationPolicy.html) after `PutDestination`. To perform a `PutDestination` operation, you must also have the `iam:PassRole` permission. ## Request Syntax ``` { "destinationName": "string", "roleArn": "string", "tags": { "string" : "string" }, "targetArn": "string" } ``` ## Request Parameters For information about the parameters that are common to all actions, see [Common Parameters](CommonParameters.md). The request accepts the following data in JSON format. ** [destinationName](#API_PutDestination_RequestSyntax) ** A name for the destination. Type: String Length Constraints: Minimum length of 1. Maximum length of 512. Pattern: `[^:*]*` Required: Yes ** [roleArn](#API_PutDestination_RequestSyntax) ** The ARN of an IAM role that grants CloudWatch Logs permissions to call the Amazon Kinesis `PutRecord` operation on the destination stream. Type: String Length Constraints: Minimum length of 1. Required: Yes ** [tags](#API_PutDestination_RequestSyntax) ** An optional list of key-value pairs to associate with the resource. For more information about tagging, see [Tagging AWS resources](https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html) Type: String to string map Map Entries: Maximum number of 50 items. Key Length Constraints: Minimum length of 1. Maximum length of 128. Key Pattern: `^([\p{L}\p{Z}\p{N}_.:/=+\-@]+)$` Value Length Constraints: Maximum length of 256. Value Pattern: `^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$` Required: No ** [targetArn](#API_PutDestination_RequestSyntax) ** The ARN of an Amazon Kinesis stream to which to deliver matching log events. Type: String Length Constraints: Minimum length of 1. Required: Yes ## Response Syntax ``` { "destination": { "accessPolicy": "string", "arn": "string", "creationTime": number, "destinationName": "string", "roleArn": "string", "targetArn": "string" } } ``` ## Response Elements If the action is successful, the service sends back an HTTP 200 response. The following data is returned in JSON format by the service. ** [destination](#API_PutDestination_ResponseSyntax) ** The destination. Type: [Destination](API_Destination.md) object ## Errors For information about the errors that are common to all actions, see [Common Error Types](CommonErrors.md). ** InvalidParameterException ** A parameter is specified incorrectly. HTTP Status Code: 400 ** OperationAbortedException ** Multiple concurrent requests to update the same resource were in conflict. HTTP Status Code: 400 ** ServiceUnavailableException ** The service cannot complete the request. HTTP Status Code: 500 ## Examples ### To create or update a destination The following example creates the specified destination. #### Sample Request ``` POST / HTTP/1.1 Host: logs.. X-Amz-Date: Authorization: AWS4-HMAC-SHA256 Credential=, SignedHeaders=content-type;date;host;user-agent;x-amz-date;x-amz-target;x-amzn-requestid, Signature= User-Agent: Accept: application/json Content-Type: application/x-amz-json-1.1 Content-Length: Connection: Keep-Alive X-Amz-Target: Logs_20140328.PutDestination { "destinationName": "my-destination", "targetArn": "arn:aws:kinesis:us-east-1:123456789012:stream/my-kinesis-stream", "roleArn": "arn:aws:iam::123456789012:role/my-subscription-role" } ``` #### Sample Response ``` HTTP/1.1 200 OK x-amzn-RequestId: Content-Type: application/x-amz-json-1.1 Content-Length: Date: { "destination": [ { "destinationName": "my-destination", "targetArn": "arn:aws:kinesis:us-east-1:123456789012:stream/my-kinesis-stream", "roleArn": "arn:aws:iam::123456789012:role/my-subscription-role", "arn": "arn:aws:logs:us-east-1:123456789012:destination:my-destination", "creationTime": 1437584472382 } ] } ``` ## See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: + [AWS Command Line Interface V2](https://docs.aws.amazon.com/goto/cli2/logs-2014-03-28/PutDestination) + [AWS SDK for .NET V4](https://docs.aws.amazon.com/goto/DotNetSDKV4/logs-2014-03-28/PutDestination) + [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/goto/SdkForCpp/logs-2014-03-28/PutDestination) + [AWS SDK for Go v2](https://docs.aws.amazon.com/goto/SdkForGoV2/logs-2014-03-28/PutDestination) + [AWS SDK for Java V2](https://docs.aws.amazon.com/goto/SdkForJavaV2/logs-2014-03-28/PutDestination) + [AWS SDK for JavaScript V3](https://docs.aws.amazon.com/goto/SdkForJavaScriptV3/logs-2014-03-28/PutDestination) + [AWS SDK for Kotlin](https://docs.aws.amazon.com/goto/SdkForKotlin/logs-2014-03-28/PutDestination) + [AWS SDK for PHP V3](https://docs.aws.amazon.com/goto/SdkForPHPV3/logs-2014-03-28/PutDestination) + [AWS SDK for Python](https://docs.aws.amazon.com/goto/boto3/logs-2014-03-28/PutDestination) + [AWS SDK for Ruby V3](https://docs.aws.amazon.com/goto/SdkForRubyV3/logs-2014-03-28/PutDestination)