Create connector

Save an external data source connector in the current workspace. Creating only saves connection information and does not start importing or exporting data.

POST https://moi.matrixorigin.cn/newmoi/connectors

Preparation before calling

First select the data source and purpose in Data Source Type Description, then use Validate connector configuration to check the current connection details. Prepare a personal access token and target workspace ID that can access the target workspace.

The example below uses:

• $AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.

• $WORKSPACE_ID: The workspace ID of the connector to be created, passed through the X-Workspace-ID Header.

• $CONNECTOR_NAME: New connector name.

• $S3_ENDPOINT: Target standard S3 service address.

• $S3_ACCESS_KEY_ID: Access key ID for target standard S3.

• $S3_ACCESS_KEY_SECRET: Access key for target standard S3.

• $S3_BUCKET_NAME: The name of the bucket to access.

• $S3_REGION: The region where the target bucket is located.

config Nested by data source type. source_type of standard S3 is 5, and its connection configuration must be written in config.s3; do not place the configuration field directly under config.

Request example

curl -X POST "https://moi.matrixorigin.cn/newmoi/connectors" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d "{
    \"name\": \"$CONNECTOR_NAME\",
    \"source_type\": 5,
    \"usage_type\": [1],
    \"config\": {
      \"s3\": {
        \"endpoint\": \"$S3_ENDPOINT\",
        \"access_key_id\": \"$S3_ACCESS_KEY_ID\",
        \"access_key_secret\": \"$S3_ACCESS_KEY_SECRET\",
        \"bucket_name\": \"$S3_BUCKET_NAME\",
        \"region\": \"$S3_REGION\"
      }
    }
  }"

Request body

When you create a connector, you also specify a name, data source type, purpose, and connection configuration for that type.

Field	Type	Is it required	Description
name	string	Yes	Connector name.
source_type	integer	Yes	Data source type code. See Data Source Type Description for available type and usage combinations.
usage_type	integer or integer[]	Yes	Connector purpose, bitmask. Values: 1 = import, 2 = export. A single integer or an array of integers can be passed, with the same semantics: 1 and [1] are both import-only, 2 and [2] are export-only, and 3 and [1, 2] support both import and export. 0 and [] are illegal. The available values ​​are limited by source_type, and not all data sources support all uses; Langfuse uses [1] in the creation form and does not display the use selection.
config	object	Yes	Type-specific connection configuration. The top-level key must correspond to source_type; standard S3 uses s3. Do not log the passwords or keys contained therein.

[] after a type denotes an array. [] in a field path denotes each item in an array.

Configuration type correspondence

The connector types in the current creation form are as follows. When creating, use the corresponding top-level key in config based on the selected source_type; do not mix configuration fields of different types.

source_type	Connector Type	config Top Key
3	MatrixOne	mo
4	Alibaba Cloud OSS	oss
5	Standard S3	s3
7	HDFS	hdfs
8	Hive	hive
9	MySQL	mysql
10	SQL Server	sqlserver
11	Oracle	oracle
12	PostgreSQL	postgresql
13	MongoDB	mongodb
14	Langfuse	langfuse

Type-specific configuration fields

The following fields are located in the corresponding config top-level keys.

MatrixOne (source_type: 3)

Parameters	Type	Is it required	Description
config.mo.host	string	Yes	MatrixOne service address.
config.mo.port	integer	Yes	MatrixOne service port.
config.mo.username	string	Yes	Login user name.
config.mo.password	string	Yes	Login password.
config.mo.database	string	No	Default database name.

Alibaba Cloud OSS (source_type: 4)

Parameters	Type	Is it required	Description
config.oss.endpoint	string	Yes	OSS Endpoint. The console’s Region selection writes to this field.
config.oss.access_key_id	string	Yes	AccessKey ID.
config.oss.access_key_secret	string	Yes	AccessKey Secret.
config.oss.bucket_name	string	Yes	Bucket name, or <bucket-name>/<prefix>. When a prefix is included, the service treats the content before the first / as the bucket and the remaining content as the file prefix.

Standard S3 (source_type: 5)

Parameters	Type	Is it required	Description
config.s3.endpoint	string	No	S3 service Endpoint.
config.s3.access_key_id	string	Yes	Access key ID.
config.s3.access_key_secret	string	Yes	Access key.
config.s3.bucket_name	string	Yes	Bucket name, or <bucket-name>/<prefix>. When a prefix is included, the service treats the content before the first / as the bucket and the remaining content as the file prefix.
config.s3.region	string	No	The region where the bucket is located.
config.s3.session_token	string	No	Session token for temporary credentials.
config.s3.path_style	boolean	No	Use the path-style S3 request address when true.

HDFS（source_type: 7）

Parameters	Type	Is it required	Description
config.hdfs.address	string	Yes	NameNode address. Can be prefixed with hdfs://.
config.hdfs.auth_type	integer	Yes	Authentication type: Simple for 0, Kerberos for 1.
config.hdfs.username	string	Required for Simple authentication	HDFS username for Simple authentication.
config.hdfs.kerberos_principal	string	Yes	Principal used to authenticate to HDFS with Kerberos.
config.hdfs.keytab_file	string	Required if Kerberos	Keytab file path; used when keytab_content is not provided.
config.hdfs.keytab_content	string (Base64)	Condition required for Kerberos	Keytab content; takes precedence over keytab_file when provided.
config.hdfs.krb5_conf_file	string	Required for Kerberos	krb5.conf file path; used when krb5_conf_content is not provided.
config.hdfs.krb5_conf_content	string (Base64)	Condition required for Kerberos	krb5.conf content; takes precedence over krb5_conf_file when provided.
config.hdfs.proxy_user	string	No	Proxy user after Kerberos authentication.
config.hdfs.file_path	string	No	The base path for connector access.

Hive（source_type: 8）

Parameters	Type	Is it required	Description
config.hive.addresses	string[]	Yes	HiveServer2 addresses, up to three, in the format of host:port.
config.hive.auth_type	integer	Yes	Authentication type: LDAP for 0, Kerberos for 1.
config.hive.username	string	Yes for LDAP authentication	LDAP user name.
config.hive.password	string	Required for LDAP	LDAP password.
config.hive.client_principal	string	Required for Kerberos	Client Kerberos principal.
config.hive.service_principal	string	Required for Kerberos	HiveServer2 service principal.
config.hive.keytab_data	string (Base64)	Required for Kerberos	Keytab content.
config.hive.krb5_conf_data	string (Base64)	Required for Kerberos	krb5.conf content.

The current connector page only provides two Hive authentication methods, LDAP and Kerberos, and does not provide the NONE authentication option.

MySQL (source_type: 9) and SQL Server (source_type: 10)

Parameters	Type	Is it required	Description
config.mysql.host	string	Yes	MySQL database host address.
config.sqlserver.host	string	Yes	SQL Server database host address.
config.mysql.port	integer	Yes	MySQL database port.
config.sqlserver.port	integer	Yes	SQL Server database port.
config.mysql.username	string	Yes	MySQL login user name.
config.sqlserver.username	string	Yes	SQL Server login user name.
config.mysql.password	string	Yes	MySQL login password.
config.sqlserver.password	string	Yes	SQL Server login password.
config.mysql.database	string	No	MySQL default database name.
config.sqlserver.database	string	No	SQL Server default database name.

Oracle（source_type: 11）

Parameters	Type	Is it required	Description
config.oracle.host	string	Yes	Oracle host address.
config.oracle.port	integer	Yes	Oracle port.
config.oracle.username	string	Yes	Login user name.
config.oracle.password	string	Yes	Login password.
config.oracle.service_name	string	Yes	Oracle Service Name.

PostgreSQL (source_type: 12)

Parameters	Type	Is it required	Description
config.postgresql.host	string	Yes	PostgreSQL host address.
config.postgresql.port	integer	Yes	PostgreSQL port.
config.postgresql.username	string	Yes	Login user name.
config.postgresql.password	string	Yes	Login password.
config.postgresql.database	string	Yes	Database name.

MongoDB (source_type: 13)

Parameters	Type	Is it required	Description
config.mongodb.host	string	Yes	MongoDB host address.
config.mongodb.port	integer	Yes	MongoDB port.
config.mongodb.authMode	string	Yes	Authentication method: userpass or none.
config.mongodb.user	string	Yes for userpass	Login user name.
config.mongodb.password	string	Yes for userpass	Login password.
config.mongodb.authSource	string	Required for userpass	Authentication database.
config.mongodb.replicaSet	string	No	Replica set name.
config.mongodb.readPreference	string	No	Read preference.
config.mongodb.readConcern	string	No	Read concern level. Optional majority or snapshot.

Langfuse（source_type: 14）

Parameters	Type	Is it required	Description
config.langfuse.host	string	Yes	Langfuse service address.
config.langfuse.public_key	string	Yes	Langfuse Public Key.
config.langfuse.secret_key	string	Yes	Langfuse Secret Key. This value is only used for submission and verification and will not be returned in subsequent detailed responses.
config.langfuse.pull_mode	string	No	Pull mode. Optional langfuse_v1 or langfuse_v2; when omitted, langfuse_v1 is used.

When creating a Langfuse connector, provide fields within these boundaries:

• Connector usage: The creation form does not offer a usage selector; submit import usage.

• Service-managed fields: secret_key_ref, database_name, and target_table are maintained by the service and must not be passed.

The request below uses standard S3 as an example. Other types retain the same outer request structure and replace the source_type, config top-level keys and type-specific fields with the corresponding values ​​in the above table.

Successful response

The connector is saved when code in the response is OK. Record data.id, which is required for subsequent import or export tasks. Successful creation does not mean that subsequent data transmission will be successful.

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "conn_01",
    "name": "s3-orders-import",
    "source_type": 5,
    "created_at": 1735632000,
    "updated_at": 1735632000,
    "status": "active",
    "username": "user_01",
    "related_task_ids": [],
    "usage_type": [1],
    "config": {
      "s3": {
        "endpoint": "https://s3.example.com",
        "bucket_name": "orders",
        "region": "us-east-1"
      }
    }
  }
}

The response fields are as follows.

Field	Type	Description
code	string	OK on success.
msg	string	OK on success.
data.id	string	New connector ID.
data.name	string	Saved connector name.
data.source_type	integer	Saved data-source type code.
data.created_at	integer	Creation time as a Unix timestamp.
data.updated_at	integer	Update time as a Unix timestamp.
data.status	string	Current connector status. When it is active or failed after creation, first decide whether to continue creating the task based on this status.
data.username	string	Username in configuration.
data.related_task_ids	string[]	Initial association task list.
data.usage_type	integer[]	A list of saved uses, expanded from a bitmask by the server. Example: [1] only imports, [2] only exports, [1, 2] supports both.
data.config	object	A saved type-specific connection configuration. Sensitive fields may not be returned; failure to return a field does not mean that saved credentials have been cleared.

In this document, [] after a type means an array. In field paths, [] means each item in an array.

Error response

HTTP 200 does not necessarily mean that the creation was successful. Always check for code in the response; only code: "OK" indicates that the connector was created.

{
  "code": "ErrParamInvalid",
  "msg": "invalid connector parameters",
  "data": null
}

Common HTTP errors

HTTP status	Error code	Common cause	Recommended action
400	ErrParamInvalid	The request body is invalid or the name contains disallowed characters.	Correct the JSON and connector name.
404	ErrNotFound	The request uses a data-source type that is not currently enabled.	Select a currently available data-source type.
200	ErrServer	The service could not create the connector.	Check code; the connector was not created and can be retried later.
503	ErrServer	The service is temporarily unable to complete creation.	Retry later.

Follow-up operations

Record data.id. First decide the next step from data.status: when the connector is available, use data.usage_type to go to Create import task or Create export task; when it has failed, first Get connector details or Update connector to correct the configuration. To verify the saved connector, use data.id with Get connector details.

Last updated on Sep 3, 2026