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

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

## Before you call

Prepare the same connector definition used by [Create a connector](create-connector.md), 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.

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

| `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

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

```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 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](create-connector.md). When it is `false`, correct `config` or the purpose and validate again; do not create the connector directly.