# 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.

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

## Preparation before calling

First select the data source and purpose in [Data Source Type Description](../../../../../guides/ai-studio/data-sources/connectors.md#select-a-data-source-type), then use [Validate connector configuration](validate-connector.md) 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

```bash
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](../../../../../guides/ai-studio/data-sources/connectors.md#select-a-data-source-type) 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.

```json
{
  "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.

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

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - 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](../import-tasks/create-import-task.md) or [Create export task](../export-tasks/create-export-task.md); when it has failed, first [Get connector details](get-connector.md) or [Update connector](update-connector.md) to correct the configuration. To verify the saved connector, use `data.id` with [Get connector details](get-connector.md).