Create connector

Available in VPC

Create a connector.

Note

Only 1 connector can be created per topic.

Request

This section describes the request format. The method and URI are as follows:

Method	URI
POST	/api/v1/topics/{topicId}/connectors

Request headers

For information about the headers common to all Data Stream APIs, see Data Stream request headers.

Request path parameters

You can use the following path parameters with your request:

Field	Type	Required	Description
`topicId`	String	Required	Topic ID See Get topic list.

Request body

You can include the following data in the body of your request:

Field	Type	Required	Description
`description`	String	Optional	Connector description (up to 200 characters)
`consumerSpec`	String	Required	Consumer specifications (connector processing performance) `SMALL` \| `MEDIUM` `SMALL`: It supports up to 250 Kbytes per second per partition with a single container. `MEDIUM`: It supports up to 500 Kbytes per second per partition with 2 containers.
`exportType`	String	Required	Connector type `OBJECT_STORAGE` (valid value)
`location`	String	Required	Storage path Enter in `s3a://{bucket}/{path}` format.
`includeTopicInPath`	Boolean	Required	Whether to create a topic name directory in the storage path `true` \| `false` `true`: Create `false`: Not create
`dateFormat`	String	Required	Whether to use date formatting for sub-storage paths `NONE` \| `YEAR` \| `MONTH` \| `DAY` \| `HOUR` `NONE`: Not use `YEAR`: Use year={yyyy}/ `MONTH`: Use year={yyyy}/month={MM}/ `DAY`: Use year={yyyy}/month={MM}/day={dd}/ `HOUR`: Use year={yyyy}/month={MM}/day={dd}/hour={HH}/
`roleNrn`	String	Required	Resource identification value for the role of the Data Stream service used to access the connector
`flushInterval`	Number	Optional	File creation interval when recording messages to storage (minute) 1-10 (default: 10)
`flushCount`	Number	Optional	Stored message count when recording messages to storage (count) 20-100 (default: 100)

Request example

The request example is as follows:

curl --location --request POST 'https://datastream.apigw.ntruss.com/api/v1/topics/mgNWA*****/connectors' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--data '{
  "description": "Connector",
  "consumerSpec": "SMALL",
  "exportType": "OBJECT_STORAGE",
  "location": "s3a://datastream001",
  "includeTopicInPath": false,
  "dateFormat": "NONE",
  "roleNrn": "nrn:PUB:IAM::****:Role/********-36d4-11f0-a3f1-246e966ebeb4",
  "flushInterval": 10,
  "flushCount": 100,
}'

Response

This section describes the response format.

Response body

The response body includes the following data:

Field	Type	Required	Description
`id`	String	-	Connector ID
`topicId`	String	-	Topic ID
`status`	String	-	Connector status `RUNNING` \| `FAILED` `RUNNING`: Normal operation (active) `FAILED`: Operation error If the bucket is deleted after setting up the connector If you access the bucket is unavailable because access control is set on it after setting up the connector If the bucket is set as a locked bucket after setting up the connector
`connectorName`	String	-	Connector name
`description`	String	-	Connector description
`consumerSpec`	String	-	Consumer specifications (connector processing performance) `SMALL` \| `MEDIUM` `SMALL`: It supports up to 250 Kbytes per second per partition with a single container. `MEDIUM`: It supports up to 500 Kbytes per second per partition with 2 containers.
`location`	String	-	Storage path
`locationWithTopicName`	String	-	Storage path containing the topic name directory
`objectStorageLocation`	String	-	Object Storage path
`dateFormat`	String	-	Whether to use date formatting for sub-storage paths `NONE` \| `YEAR` \| `MONTH` \| `DAY` \| `HOUR` `NONE`: Not use `YEAR`: Use year={yyyy}/ `MONTH`: Use year={yyyy}/month={MM}/ `DAY`: Use year={yyyy}/month={MM}/day={dd}/ `HOUR`: Use year={yyyy}/month={MM}/day={dd}/hour={HH}/
`exportType`	String	-	Connector type `OBJECT_STORAGE` (valid value)
`includeTopicInPath`	Boolean	-	Whether to create a topic name directory in the storage path `true` \| `false` `true`: Create `false`: Not create
`createdDate`	String	-	Connector creation date and time ISO 8601 format `YYYY-MM-DDThh:mm:ssZ`
`roleNrn`	String	-	Resource identification value for the role of the Data Stream service used to access the connector
`flushInterval`	Number	-	File creation interval when recording messages to storage (minute) 1-10 (default: 10)
`flushCount`	Number	-	Stored message count when recording messages to storage (count) 20-100 (default: 100)
`groupId`	String	-	Connector group ID

Response status codes

For information about the HTTP status codes common to all Data Stream APIs, see Data Stream response status codes.

Response example

The response example is as follows:

{
    "id": "xlThN*****",
    "topicId": "mgNWA*****",
    "status": "RUNNING",
    "connectorName": "connector-h4j6l-ds001",
    "description": "Connector",
    "consumerSpec": "SMALL",
    "location": "s3a://datastream001/ds002",
    "locationWithTopicName": "s3a://datastream001/ds002",
    "objectStorageLocation": "https://console.ncloud.com/objectStorage/objectStorageList?bucketName=datastream001&folderPrefix=ds002",
    "dateFormat": "NONE",
    "exportType": "OBJECT_STORAGE",
    "includeTopicInPath": false,
    "createdDate": "2025-06-05T12:56:45Z",
    "roleNrn": "nrn:PUB:IAM::****:Role/********-36d4-11f0-a3f1-246e966ebeb4",
    "flushInterval": 10,
    "flushCount": 100,
    "groupId": "connect-h4j6l-ds001"
}