List connectors¶

List connectors that you can read in the current workspace. Use this endpoint to find a connector ID, then get its details, update or delete it, or create a data task.

GET https://moi.matrixorigin.cn/newmoi/connectors/list

Before you call¶

Prepare 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 to query, sent in the X-Workspace-ID header.

Request example¶

curl "https://moi.matrixorigin.cn/newmoi/connectors/list?page=1&page_size=20" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

To filter by name, append name as a query parameter.

Query parameters¶

Without query parameters, the endpoint returns the first page of connectors. Use filters to narrow the result set, and use page and page_size to paginate it.

Parameter	Type	Required	Description
`name`	string	No	Filter by name.
`page`	integer	No	Page number. The default is `1`.
`page_size`	integer	No	Number of items per page. The default is `20`.
`order_by`	string	No	Sort field. Results are sorted by creation time in descending order when omitted.
`is_desc`	boolean	No	Whether to sort in descending order when `order_by` is set.
`keyword`	string	No	Keyword filter.
`source_type`	integer	No	Filter by one data-source type.
`source_type_list`	integer[]	No	Filter by multiple data-source types. This parameter can be repeated.
`status`	string	No	Filter by one connector status.
`status_list`	string[]	No	Filter by multiple connector statuses. This parameter can be repeated.
`usage_type`	integer[]	No	Filter by connector purpose.

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

Successful response¶

A successful request returns 200. Get connector information from data.connectors[], and use data.total to determine the number of matching results.

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

Response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.connectors`	object[]	Connectors matching the current filters.
`data.connectors[].id`	string	Connector ID.
`data.connectors[].name`	string	Connector name.
`data.connectors[].source_type`	integer	Data-source type code.
`data.connectors[].created_at`	integer	Creation time as a Unix timestamp.
`data.connectors[].updated_at`	integer	Update time as a Unix timestamp.
`data.connectors[].status`	string	Current connector status.
`data.connectors[].username`	string	User name in the configuration.
`data.connectors[].related_task_ids`	string[]	IDs of related data tasks.
`data.connectors[].usage_type`	integer[]	Saved purpose list expanded by the service from the bitmask. For example, `[1]` is import only, `[2]` is export only, and `[1, 2]` supports both.
`data.connectors[].config`	object	Type-specific connection configuration. For top-level keys and complete fields, see Type-specific configuration fields for creating a connector. Response fields depend on the actual data-source type.
`data.total`	integer	Total number of connectors matching the filters.

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

Read the next page¶

Use data.total and the requested page_size to calculate the last page, then increase page in sequence. For example, when total is 41 and page_size is 20, request pages 1, 2, and 3.

Error response¶

{
  "code": "ErrForbidden",
  "msg": "permission denied",
  "data": null
}

Common HTTP errors¶

HTTP status	Error code	Common cause	Recommended action
`400`	`ErrParamInvalid`	A query parameter has an invalid format.	Correct the parameter and retry.
`403`	`ErrForbidden`	The caller cannot read the connector collection.	Check workspace and connector permissions.
`503`	`ErrCoreAuthorizeUnavailable`	The service cannot complete authorization filtering.	Retry later; do not treat an empty list as meaning that no connectors exist.

Next steps¶

Keep the target connector’s id, then get connector details. To select databases or tables, view browsable connectors; to browse files, list files.

Last updated on Sep 3, 2026