Validate connector configuration¶

Validate a connector definition that has not been saved or has been edited. Validation checks only the current connection information; it does not create or update a connector.

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

Before you call¶

Prepare the same connector definition used by Create a connector, a personal access token that can access the target workspace, and the target workspace ID.

The example uses:

$AI_STUDIO_API_KEY: your personal access token, sent in the X-API-Key header.
$WORKSPACE_ID: the workspace where the connection configuration is validated, sent in the X-Workspace-ID header.
$CONNECTOR_NAME: connector name used by this validation. Validation does not save the name.
$S3_ENDPOINT: target standard S3 service endpoint.
$S3_ACCESS_KEY_ID: target standard S3 access key ID.
$S3_ACCESS_KEY_SECRET: target standard S3 access key.
$S3_BUCKET_NAME: bucket to access.
$S3_REGION: region of the target bucket.

Request example¶

The following executable example uses standard S3. To validate another type, retain the outer structure, replace source_type and the config top-level key according to the preceding table, and provide all fields for that type.

curl -X POST "https://moi.matrixorigin.cn/newmoi/connectors/validate" \
  -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¶

The validation request uses the same fields as creating a connector. First send actual connection information, then create the connector only after confirming data.valid.

Field	Type	Required	Description
`name`	string	Yes	Connector name to validate. It is used only for this validation and is not saved.
`source_type`	integer	Yes	Data-source type code to validate. For available type and purpose combinations, see Connectors.
`usage_type`	integer or integer[]	Yes	Connector-purpose bitmask: `1` = import and `2` = export. You can send a single integer or an array with the same meaning: `1` and `[1]` are import only, `2` and `[2]` are export only, and `3` and `[1, 2]` support both. `0` and `[]` are invalid. Available values are restricted by `source_type`, and not every data source supports every purpose. The Langfuse creation form uses `[1]` and does not show a purpose selector.
`config`	object	Yes	Type-specific connection address and credentials. The top-level key and all fields are the same as Type-specific configuration fields for creating a connector. Do not write passwords or keys from this object to logs.

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

Configuration type mapping¶

config must be nested by source_type; do not put type-specific fields directly under config. The following table covers every connector type in the current creation form. For complete fields, conditional fields, and authentication branches for each type, see Type-specific configuration fields for creating a connector.

`source_type`	Connector type	`config` top-level 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`

Successful response¶

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "valid": true
  }
}

Response fields are as follows.

Field	Type	Description
`code`	string	`OK` when the request is processed correctly.
`msg`	string	`OK` when the request is processed correctly.
`data.valid`	boolean	Whether the current connector definition passes validation. `false` is not an HTTP request failure and does not mean that the connector is available.

Error response¶

HTTP 200 does not necessarily mean validation passed. Check code first, then check data.valid.

{
  "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 connector definition and retry.
`404`	`ErrNotFound`	The request uses a data-source type that is not currently enabled.	Select a currently available data-source type.
`200`	`ErrServer`	An internal error occurred during service validation.	Check `code`; do not confuse this with `data.valid: false`.

Next steps¶

When data.valid is true, use the same request body to create a connector. When it is false, correct config or the purpose and validate again; do not create the connector directly.

Last updated on Sep 3, 2026