<span id="安装插件"></span>

# Install a plugin

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

Save a plugin installation and its selected account connection bindings.

```text
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/plugin-installations
```

<span id="调用前准备"></span>

## 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](objects.md#input-identifiers) for environment variable sources.

<span id="请求体"></span>

## Request body

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```bash
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]
}
')"
```

:::::
:::::{tab-item} Parameters

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.

:::::
::::::
:::::::

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "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"
  }
}
```

:::::
:::::{tab-item} Fields

| 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](objects.md). |
| `data.workspace_id` | string | Resource fields; see [common objects and states](objects.md). |
| `data.release_workspace_id` | string | Resource fields; see [common objects and states](objects.md). |
| `data.release_id` | string | Resource fields; see [common objects and states](objects.md). |
| `data.release_digest` | string | Resource fields; see [common objects and states](objects.md). |
| `data.release_name` | string | Resource fields; see [common objects and states](objects.md). |
| `data.owner_user_id` | string | Resource fields; see [common objects and states](objects.md). |
| `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](objects.md). |
| `data.updated_at` | string | Resource fields; see [common objects and states](objects.md). |

:::::
::::::
:::::::

<span id="错误响应"></span>

## Error responses

Handle business errors with numeric `code`, `message`, and `details.reason` separately from authorization-layer errors with string codes. See [errors and states](objects.md#error-responses). On state or version conflicts, read the current resource before changing identifiers or retrying writes.
