Install a plugin¶
Save a plugin installation and its selected account connection bindings.
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/plugin-installations
Before you call this API¶
Prepare the target workspace ID and a personal access token with access to the resources and permission for this action. Use the actual resource workspace_id in the path and in X-Workspace-ID. The example uses jq to construct JSON; install it first. See common objects and inputs for environment variable sources.
Request body¶
curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/plugin-installations" \
-H "X-API-Key: $AI_STUDIO_API_KEY" \
-H "X-Workspace-ID: $WORKSPACE_ID" \
-H 'Content-Type: application/json' \
--data-binary "$(jq -n --arg RELEASE_NAMESPACE "$RELEASE_NAMESPACE" --arg RELEASE_ID "$RELEASE_ID" --slurpfile PLUGIN_BINDINGS_FILE "$PLUGIN_BINDINGS_FILE" '
{
"release_namespace": $RELEASE_NAMESPACE,
"release_id": $RELEASE_ID,
"bindings": $PLUGIN_BINDINGS_FILE[0]
}
')"
Confirm installation persistence and account authorization separately. Bound connections must belong to the current user and workspace, be active, and match the release configuration. Successful installation does not establish that all components are authorized or executable. The example reads the complete bindings JSON object from $PLUGIN_BINDINGS_FILE.
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
system or workspace. |
|
string |
Yes |
Selected release ID from the release list. |
|
object |
No |
Supply the complete bindings by connection requirement key. Omission or an empty object produces an empty set. |
|
string |
Yes |
Plugin connection ID for the current user in the same workspace. |
|
string |
Yes |
Authorization profile key for this requirement. |
|
string |
Conditionally required |
For a managed_session profile, supply the executor ID matching the connection. Omit it for other drivers. |
|
string |
No |
Operation ID of an existing plugin configuration interaction. Optional for an ordinary installation; do not invent one. |
JSON objects reject unknown fields, duplicate keys, and multiple consecutive objects. The entire request body must not exceed 1 MiB.
Successful response¶
{
"code": 0,
"data": {
"id": "installation_example",
"workspace_id": "workspace_example",
"release_workspace_id": "workspace_example",
"release_id": "pr_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"release_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"release_name": "example",
"owner_user_id": "user_example",
"bindings": {},
"version": 1,
"created_at": "2026-11-11T00:00:00Z",
"updated_at": "2026-11-11T00:00:00Z"
}
}
Field |
Type |
Description |
|---|---|---|
|
integer |
0 on success. |
|
object |
Data returned by this action. |
|
string |
Resource fields; see common objects and states. |
|
string |
Resource fields; see common objects and states. |
|
string |
Resource fields; see common objects and states. |
|
string |
Resource fields; see common objects and states. |
|
string |
Resource fields; see common objects and states. |
|
string |
Resource fields; see common objects and states. |
|
string |
Resource fields; see common objects and states. |
|
object |
Complete installation bindings. |
|
integer |
Current resource version, supplied as expected_version for writes. |
|
string |
Resource fields; see common objects and states. |
|
string |
Resource fields; see common objects and states. |
Error responses¶
Handle business errors with numeric code, message, and details.reason separately from authorization-layer errors with string codes. See errors and states. On state or version conflicts, read the current resource before changing identifiers or retrying writes.