Create channel instance

Creates a channel instance for the specified Provider. Sensitive configuration is only submitted in the request, and no clear text is returned in a successful response.

POST 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 of the instance to be created, passed in the X-Workspace-ID header, and as workspace_id in the path.

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

Request example

curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/channels/$PROVIDER/instances" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "channel_type": "<CHANNEL_TYPE>",
    "name": "告警通道",
    "config": {
      "endpoint": "<ENDPOINT>"
    },
    "secrets": {
      "token": "<TOKEN>"
    }
  }'

Path parameters

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

Request body

Parameters	Type	Is it required	Description
channel_type	string	Yes	The channel type within the Provider.
name	string	Yes	Instance name.
description	string	No	Example description.
config	object	No	Non-sensitive configuration.
secrets	object	Required by channel type	Keys and other sensitive configuration.
visibility	string	No	Visible range.
labels	object	No	Tag key-value pair.

Successful response

Returns 201 on success. data contains instance ID, provider, status, credential reference, and non-sensitive configuration; secrets in the request is not echoed. Successful saving does not mean that the external service connection is available, please perform a connection test.

{
  "code": 0,
  "data": {
    "id": "inst_01",
    "workspace_id": "ws_01",
    "provider": "wecom",
    "channel_type": "wecom_mail",
    "name": "告警通道",
    "status": "active",
    "credential_ref": "cred_01",
    "config": {
      "endpoint": "https://example.com/hook"
    },
    "created_at": "2026-08-18T01:00:00Z",
    "updated_at": "2026-08-18T01:00:00Z"
  }
}

The response fields are as follows.

Field	Type	Description
code	integer	0 on success.
data.id	string	Instance ID and workspace.
data.workspace_id	string	Instance ID and workspace.
data.provider	string	Provider and instance channel type.
data.channel_type	string	Provider and instance channel type.
data.name	string	Instance name, description, and current status.
data.description	string	Instance name, description, and current status.
data.status	string	Instance name, description, and current status.
data.credential_ref	string	A reference to a saved credential, not a clear text key.
data.callback_path	string	The callback path, capabilities, and associated tools returned when available.
data.capabilities	string[]	The callback path, capabilities, and associated tools returned when available.
data.tool_ids	string[]	The callback path, capabilities, and associated tools returned when available.
data.config	object	Non-sensitive configuration and tags.
data.labels	object	Non-sensitive configuration and tags.
data.created_at	string	Creation and last update times, using RFC 3339 format.
data.updated_at	string	Creation and last update times, using RFC 3339 format.

[] 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, channel type, configuration, key, or visibility scope.	Use the channel type supported by this Provider and complete the corresponding config and secrets.
401	6（UNAUTHENTICATED）	Lack of valid identity credentials.	Check API Key.
403	5（PERMISSION_DENIED）	The current identity does not have permission to create channel instances.	Check workspace authorization.
409	4（ALREADY_EXISTS）	Instance definition conflicts under the same Provider.	Check the existing instance or change the instance configuration.
503	15（UNAVAILABLE）	Channel instance services or authorization dependencies are temporarily unavailable.	Try again later.

Follow-up operations

Test the created channel instance to check the connection.

Last updated on Sep 3, 2026