Query channel instance list

Lists channel instances in the current workspace by Provider.

GET https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/channels/{provider}/instances

Before you call

Prepare a personal access token with access to the target workspace, the target workspace ID, and the channel provider ID.

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 to be queried, passed through the X-Workspace-ID Header, and as workspace_id in the path.

• $PROVIDER: Channel Provider ID, as provider in the path.

Request example

curl "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/channels/$PROVIDER/instances?limit=20&offset=0" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

Path parameters

Parameters	Type	Is it required	Description
workspace_id	string	Yes	Workspace ID.
provider	string	Yes	Channel Provider ID.

Query parameters

Parameters	Type	Is it required	Description
status	string	No	Filter by instance status.
limit	integer	No	Return quantity; default 50, maximum 200.
offset	integer	No	Returns the starting position of the list; negative numbers are treated as 0.

Successful response

Returns 200 on success. No plaintext keys are returned for each item.

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "inst_01",
        "workspace_id": "ws_01",
        "provider": "wecom",
        "channel_type": "wecom_mail",
        "name": "告警通道",
        "status": "active",
        "credential_ref": "cred_01"
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

The response fields are as follows.

Field	Type	Description
code	integer	0 on success.
data.items	array	Channel instance of the current page.
data.items[].id	string	Instance ID and workspace.
data.items[].workspace_id	string	Instance ID and workspace.
data.items[].provider	string	Provider, channel type, and current status.
data.items[].channel_type	string	Provider, channel type, and current status.
data.items[].status	string	Provider, channel type and current status.
data.items[].credential_ref	string	Credential reference, not clear text key.
data.items[].callback_path	string	Callback path, capabilities, and associated tools; returned when available.
data.items[].capabilities	string[]	Callback path, capabilities, and associated tools; returned when available.
data.items[].tool_ids	string[]	Callback path, capabilities, and associated tools; returned when available.
data.items[].last_test_status	string	Recent test information; may not be returned if it has not been tested yet.
data.items[].last_tested_at	string	Most recent test information; may not be returned when no test has been run.
data.items[].last_test_error	string	Recent test information; may not be returned if it has not been tested yet.
data.total	integer	The total number of matches, the size of this page and the starting offset.
data.limit	integer	The total number of matches, the size of this page and the starting offset.
data.offset	integer	The total number of matches, the size of this page and the starting offset.

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

Error response

{
  "code": 2,
  "message": "<错误信息>"
}

Common HTTP errors

HTTP status code	error code	Common causes	Recommended actions
400	2（INVALID_ARGUMENT）	Invalid provider, state, or paging parameters.	Check path and query parameters.
401	6（UNAUTHENTICATED）	Lack of valid identity credentials.	Check API Key.
403	5（PERMISSION_DENIED）	The current identity does not have permission to read the channel instance.	Check workspace authorization.
503	15（UNAVAILABLE）	Channel instance services or authorization dependencies are temporarily unavailable.	Try again later.

Follow-up operations

Use the instance’s id Query channel instance details.

Last updated on Sep 3, 2026