Create Destination

5min

Create Destination
Create a Destination to upload Collection Result Sets to on completion.
Destinations are created by making an  HTTP POST  to the  /destinations  endpoint. POST parameters can be either supplied as  x-www-form-urlencoded  parameters or by POST'ing a JSON  object.
﻿
Example
﻿POST  /destination
To create a new Amazon S3 Destination the request would be as shown below:
Verifying your Destination
Whenever you create a new  enabled  Destination, or enable a previous disabled Destination, or update an existing Destination's credentials, RedCircle API will upload and then delete a small test file to the Destination to verify connectivity. If this connectivity test fails then the create/update operation itself fails.
Curl
Node.js
Python
PHP
$ curl "https://api.redcircleapi.com/destinations?api_key=demo" \
  -d name="My First S3 Destination" \
  -d type="s3" \
  -d enabled=true \
  -d s3_access_key_id="my_access_key_id" \
  -d s3_secret_access_key="my_secret_access_key" \
  -d s3_bucket_name="MyS3Bucket" \
  -d s3_path_prefix="my_path_prefix"
$ curl "https://api.redcircleapi.com/destinations?api_key=demo" \
  -d name="My First S3 Destination" \
  -d type="s3" \
  -d enabled=true \
  -d s3_access_key_id="my_access_key_id" \
  -d s3_secret_access_key="my_secret_access_key" \
  -d s3_bucket_name="MyS3Bucket" \
  -d s3_path_prefix="my_path_prefix"
﻿
RedCircle API responds with the following JSON confirming the Destination has been successfully created.
JSON
{
  "request_info": {
    "success": true
  },
  "destination": {
    "id": "ABCDEFG"
  }
}
{
  "request_info": {
    "success": true
  },
  "destination": {
    "id": "ABCDEFG"
  }
}
﻿
﻿
Destination Parameters
﻿POST  /destinations
The following parameters can be used when creating a Destination. The  api_key  parameter should be supplied as a querystring parameter on the request URL.
Parameters pther than  api_key  should be supplied in either  x-www-form-urlencoded  or  JSON  format, in the request body.
Parameter
Required
Description
api_key
required
The API key for your account, should be supplied on the request querystring, i.e. api_key=demo
name
required
The name of the Destination.
enabled
required
Determines whether the Destination is enabled or not. Disabled Destinations do not have Collection Result Sets uploaded to them, even if the Destination is set of a Collection.
Parameter Values
true
Destination is enabled
﻿
false
Destination is disabled
type
required
Determines the type of Destination.
Parameter Values
s3
Specifies that this Destination is for an Amazon S3 bucket.
﻿
gcs
Specifies that this Destination is for a Google Cloud Storage bucket.
﻿
azure
Specifies that this Destination is for Microsoft Azure Blob Storage.
﻿
oss
Specifies that this Destination is for a Alibaba Cloud OSS bucket.
﻿
s3compatible
Specifies that this Destination is an S3 compatible object storage provider. Note that when type=s3compatible an S3-compatible endpoint must be supplied in the s3_endpoint parameter.
s3_access_key_id
required
Applies only when type=s3 or type=s3compatible 
The Amazon S3 Access Key ID. We strongly recommend you set up credentials specifically for RedCircle API to use.
s3_secret_access_key
required
Applies only when type=s3 or type=s3compatible 
The Amazon S3 Secret Access Key. We strongly recommend you set up credentials specifically for RedCircle API to use.
s3_bucket_name
required
Applies only when type=s3 or type=s3compatible 
The Amazon S3 bucket name to use.
s3_path_prefix
optional
Applies only when type=s3 or type=s3compatible 
The Amazon S3 path prefix to prepend to Collection Result Set files when they are uploaded to your bucket.  
The text tokens %COLLECTION_ID% , %COLLECTION_NAME% , %RESULT_SET_ID% and %DATE% will be replaced with the Collection ID, Collection name, Result Set ID and UTC date (in the form YYYY_MM_DD) respectively when the files are uploaded.
s3_endpoint
required
Applies only when type=s3compatible 
The Endpoint to use when connecting to S3 compatible storage (i.e. when type=s3compatible ) For example https://ams3.digitaloceanspaces.com
s3_region
optional
Applies only when type=s3compatible 
The region to use when connecting to S3 compatible storage (i.e. when type=s3compatible ) For example eu-west-1 , us-east-1 , auto , etc
gcs_access_key
required
Applies only when type=gcs 
The interoperable storage access key to use when connecting to Google Cloud Storage. We strongly recommend you set up credentials specifically for RedCircle API to use.
gcs_secret_key
required
Applies only when type=gcs 
The interoperable storage secret key used when connecting to Google Cloud Storage. We strongly recommend you set up credentials specifically for RedCircle API to use.
gcs_bucket_name
required
Applies only when type=gcs 
The Google Cloud Storage bucket name to use.
gcs_path_prefix
optional
Applies only when type=gcs 
The Google Cloud Storage path prefix to prepend to Collection Result Set files when they are uploaded to your bucket.  
The text tokens %COLLECTION_ID% , %COLLECTION_NAME% , %RESULT_SET_ID% and %DATE% will be replaced with the Collection ID, Collection name, Result Set ID and UTC date (in the form YYYY_MM_DD) respectively when the files are uploaded.
azure_account_name
required
Applies only when type=azure 
The storage account name to use when connecting to Microsoft Azure Blob Storage. We strongly recommend you set up credentials specifically for RedCircle API to use.
azure_account_key
required
Applies only when type=azure 
The account key used when connecting to Microsoft Azure Blob Storage. We strongly recommend you set up credentials specifically for RedCircle API to use.
azure_container_name
required
Applies only when type=azure 
The Microsoft Azure Blob Storage container name to use.
azure_path_prefix
optional
Applies only when type=azure 
The Microsoft Azure Blob Storage path prefix to prepend to Collection Result Set files when they are uploaded to your bucket.  
The text tokens %COLLECTION_ID% , %COLLECTION_NAME% , %RESULT_SET_ID% and %DATE% will be replaced with the Collection ID, Collection name, Result Set ID and UTC date (in the form YYYY_MM_DD) respectively when the files are uploaded.
oss_access_key
required
Applies only when type=oss 
The RAM user access key to use when connecting to Alibaba Cloud OSS. We highly recommend creating a new Alibaba Cloud RAM user specifically for RedCircle API to use. You can do so in your Alibaba Cloud console﻿
oss_secret_key
required
Applies only when type=oss 
The RAM user secret key used when connecting to Alibaba Cloud OSS. We highly recommend creating new Alibaba Cloud RAM user specifically for RedCircle API to use. You can do so in your Alibaba Cloud console﻿
oss_bucket_name
required
Applies only when type=oss 
The Alibaba Cloud OSS bucket name to use.
oss_region_id
required
Applies only when type=oss 
The Alibaba Cloud OSS Region ID to use when connecting to your bucket.
oss-cn-hangzhou - China (Hangzhou)
oss-cn-shanghai - China (Shanghai)
oss-cn-qingdao - China (Qingdao)
oss-cn-beijing - China (Beijing)
oss-cn-zhangjiakou - China (Zhangjiakou)
oss-cn-huhehaote - China (Hohhot)
oss-cn-wulanchabu - China (Ulanqab)
oss-cn-shenzhen - China (Shenzhen)
oss-cn-heyuan - China (Heyuan)
oss-cn-guangzhou - China (Guangzhou)
oss-cn-chengdu - China (Chengdu)
oss-cn-hongkong - China (Hong Kong)
oss-us-west-1 - US (Silicon Valley)
oss-us-east-1 - US (Virginia)
oss-ap-southeast-1 - Singapore
oss-ap-southeast-2 - Australia (Sydney)
oss-ap-southeast-3 - Malaysia (Kuala Lumpur)
oss-ap-southeast-5 - Indonesia (Jakarta)
oss-ap-northeast-1 - Japan (Tokyo)
oss-ap-south-1 - India (Mumbai)
oss-eu-central-1 - Germany (Frankfurt)
oss-eu-west-1 - UK (London)
oss-me-east-1 - UAE (Dubai)
oss_path_prefix
optional
Applies only when type=oss 
The Alibaba Cloud OSS path prefix to prepend to Collection Result Set files when they are uploaded to your bucket.  
The text tokens %COLLECTION_ID% , %COLLECTION_NAME% , %RESULT_SET_ID% and %DATE% will be replaced with the Collection ID, Collection name, Result Set ID and UTC date (in the form YYYY_MM_DD) respectively when the files are uploaded.
﻿
Next Steps
     List Destinations
     Update Destination﻿

Parameter	Required	Description
api_key	required	The API key for your account, should be supplied on the request querystring, i.e. api_key=demo
name	required	The name of the Destination.
enabled	required	Determines whether the Destination is enabled or not. Disabled Destinations do not have Collection Result Sets uploaded to them, even if the Destination is set of a Collection. Parameter Values true Destination is enabled false Destination is disabled
type	required	Determines the type of Destination. Parameter Values s3 Specifies that this Destination is for an Amazon S3 bucket. gcs Specifies that this Destination is for a Google Cloud Storage bucket. azure Specifies that this Destination is for Microsoft Azure Blob Storage. oss Specifies that this Destination is for a Alibaba Cloud OSS bucket. s3compatible Specifies that this Destination is an S3 compatible object storage provider. Note that when type=s3compatible an S3-compatible endpoint must be supplied in the s3_endpoint parameter.
s3_access_key_id	required	Applies only when type=s3 or type=s3compatible The Amazon S3 Access Key ID. We strongly recommend you set up credentials specifically for RedCircle API to use.
s3_secret_access_key	required	Applies only when type=s3 or type=s3compatible The Amazon S3 Secret Access Key. We strongly recommend you set up credentials specifically for RedCircle API to use.
s3_bucket_name	required	Applies only when type=s3 or type=s3compatible The Amazon S3 bucket name to use.
s3_path_prefix	optional	Applies only when type=s3 or type=s3compatible The Amazon S3 path prefix to prepend to Collection Result Set files when they are uploaded to your bucket. The text tokens %COLLECTION_ID% , %COLLECTION_NAME% , %RESULT_SET_ID% and %DATE% will be replaced with the Collection ID, Collection name, Result Set ID and UTC date (in the form YYYY_MM_DD) respectively when the files are uploaded.
s3_endpoint	required	Applies only when type=s3compatible The Endpoint to use when connecting to S3 compatible storage (i.e. when type=s3compatible ) For example https://ams3.digitaloceanspaces.com
s3_region	optional	Applies only when type=s3compatible The region to use when connecting to S3 compatible storage (i.e. when type=s3compatible ) For example eu-west-1 , us-east-1 , auto , etc
gcs_access_key	required	Applies only when type=gcs The interoperable storage access key to use when connecting to Google Cloud Storage. We strongly recommend you set up credentials specifically for RedCircle API to use.
gcs_secret_key	required	Applies only when type=gcs The interoperable storage secret key used when connecting to Google Cloud Storage. We strongly recommend you set up credentials specifically for RedCircle API to use.
gcs_bucket_name	required	Applies only when type=gcs The Google Cloud Storage bucket name to use.
gcs_path_prefix	optional	Applies only when type=gcs The Google Cloud Storage path prefix to prepend to Collection Result Set files when they are uploaded to your bucket. The text tokens %COLLECTION_ID% , %COLLECTION_NAME% , %RESULT_SET_ID% and %DATE% will be replaced with the Collection ID, Collection name, Result Set ID and UTC date (in the form YYYY_MM_DD) respectively when the files are uploaded.
azure_account_name	required	Applies only when type=azure The storage account name to use when connecting to Microsoft Azure Blob Storage. We strongly recommend you set up credentials specifically for RedCircle API to use.
azure_account_key	required	Applies only when type=azure The account key used when connecting to Microsoft Azure Blob Storage. We strongly recommend you set up credentials specifically for RedCircle API to use.
azure_container_name	required	Applies only when type=azure The Microsoft Azure Blob Storage container name to use.
azure_path_prefix	optional	Applies only when type=azure The Microsoft Azure Blob Storage path prefix to prepend to Collection Result Set files when they are uploaded to your bucket. The text tokens %COLLECTION_ID% , %COLLECTION_NAME% , %RESULT_SET_ID% and %DATE% will be replaced with the Collection ID, Collection name, Result Set ID and UTC date (in the form YYYY_MM_DD) respectively when the files are uploaded.
oss_access_key	required	Applies only when type=oss The RAM user access key to use when connecting to Alibaba Cloud OSS. We highly recommend creating a new Alibaba Cloud RAM user specifically for RedCircle API to use. You can do so in your Alibaba Cloud console
oss_secret_key	required	Applies only when type=oss The RAM user secret key used when connecting to Alibaba Cloud OSS. We highly recommend creating new Alibaba Cloud RAM user specifically for RedCircle API to use. You can do so in your Alibaba Cloud console
oss_bucket_name	required	Applies only when type=oss The Alibaba Cloud OSS bucket name to use.
oss_region_id	required	Applies only when type=oss The Alibaba Cloud OSS Region ID to use when connecting to your bucket. oss-cn-hangzhou - China (Hangzhou) oss-cn-shanghai - China (Shanghai) oss-cn-qingdao - China (Qingdao) oss-cn-beijing - China (Beijing) oss-cn-zhangjiakou - China (Zhangjiakou) oss-cn-huhehaote - China (Hohhot) oss-cn-wulanchabu - China (Ulanqab) oss-cn-shenzhen - China (Shenzhen) oss-cn-heyuan - China (Heyuan) oss-cn-guangzhou - China (Guangzhou) oss-cn-chengdu - China (Chengdu) oss-cn-hongkong - China (Hong Kong) oss-us-west-1 - US (Silicon Valley) oss-us-east-1 - US (Virginia) oss-ap-southeast-1 - Singapore oss-ap-southeast-2 - Australia (Sydney) oss-ap-southeast-3 - Malaysia (Kuala Lumpur) oss-ap-southeast-5 - Indonesia (Jakarta) oss-ap-northeast-1 - Japan (Tokyo) oss-ap-south-1 - India (Mumbai) oss-eu-central-1 - Germany (Frankfurt) oss-eu-west-1 - UK (London) oss-me-east-1 - UAE (Dubai)
oss_path_prefix	optional	Applies only when type=oss The Alibaba Cloud OSS path prefix to prepend to Collection Result Set files when they are uploaded to your bucket. The text tokens %COLLECTION_ID% , %COLLECTION_NAME% , %RESULT_SET_ID% and %DATE% will be replaced with the Collection ID, Collection name, Result Set ID and UTC date (in the form YYYY_MM_DD) respectively when the files are uploaded.

Updated 08 Aug 2024

Did this page help you?

Overview

List Destinations