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

release_namespace

string

Yes

system or workspace.

release_id

string

Yes

Selected release ID from the release list.

bindings

object

No

Supply the complete bindings by connection requirement key. Omission or an empty object produces an empty set.

bindings["要求键"].connection_id

string

Yes

Plugin connection ID for the current user in the same workspace.

bindings["要求键"].profile

string

Yes

Authorization profile key for this requirement.

bindings["要求键"].executor_id

string

Conditionally required

For a managed_session profile, supply the executor ID matching the connection. Omit it for other drivers.

setup_operation_id

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

code

integer

0 on success.

data

object

Data returned by this action.

data.id

string

Resource fields; see common objects and states.

data.workspace_id

string

Resource fields; see common objects and states.

data.release_workspace_id

string

Resource fields; see common objects and states.

data.release_id

string

Resource fields; see common objects and states.

data.release_digest

string

Resource fields; see common objects and states.

data.release_name

string

Resource fields; see common objects and states.

data.owner_user_id

string

Resource fields; see common objects and states.

data.bindings

object

Complete installation bindings.

data.version

integer

Current resource version, supplied as expected_version for writes.

data.created_at

string

Resource fields; see common objects and states.

data.updated_at

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.

Last updated on