Bind the running environment¶

Create or update an agent version of the runtime environment binding. Please confirm that the version and provider configuration exist before calling, and prepare request fields that match the binding status.

PUT https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agents/{agent_id}/versions/{version}/runtime-bindings/{provider}/{profile}

Preparation before calling¶

First confirm that the agent version and run provider configuration exist. Prepare a personal access token with access to the target workspace, target workspace ID, agent ID, version number, provider and profile ID.

The example below uses:

$AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.
$WORKSPACE_ID: Target workspace ID, passed through X-Workspace-ID Header.
$AGENT_ID: Agent ID.
$VERSION: Agent version.
$PROVIDER: Run provider.
$PROFILE: Provider configuration file.

Request example¶

curl -X PUT "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/versions/$VERSION/runtime-bindings/$PROVIDER/$PROFILE" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "pending"
  }'

Path parameters¶

Parameters	Type	Is it required	Description
`workspace_id`	string	Yes	The current workspace ID.
`agent_id`	string	Yes	Agent ID.
`version`	string	Yes	Agent version.
`provider`	string	Yes	Running provider.
`profile`	string	Yes	Provider configuration file.

Request body¶

If the request body also provides workspace_id, agent_id, agent_version, provider or profile, its value must be consistent with the path.

Field	Type	Is it required	Description
`status`	string	Yes	Binding status: `pending`, `active`, `binding_failed`, or `disabled`.
`provider_binding_id`	string	Condition required	Required when `status` is `active`.
`provider_binding_name`	string	Condition required	Required when `status` is `active`.
`provider_binding_hash`	string	Condition required	Required when `status` is `active`; format: `sha256:<hex>`.
`last_error`	string	Condition required	Required when `status` is `binding_failed`; omit it for other statuses.

Successful response¶

Returns 200 on success.

{
  "code": 0,
  "data": {
    "workspace_id": "ws_01",
    "agent_id": "agent_01",
    "agent_version": "1",
    "provider": "matrixone",
    "profile": "default",
    "status": "pending",
    "registered_at": "2026-01-02T15:04:05Z",
    "updated_at": "2026-01-02T15:04:05Z"
  }
}

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` on success.
`data.workspace_id`	string	The workspace, agent and agent version to which the binding belongs.
`data.agent_id`	string	The workspace, agent and agent version to which the binding belongs.
`data.agent_version`	string	The workspace, agent and agent version to which the binding belongs.
`data.provider`	string	Run provider and configuration file.
`data.profile`	string	Run provider and configuration file.
`data.status`	string	The binding status after saving.
`data.provider_binding_id`	string	Running provider binding ID, name and summary when activating the binding.
`data.provider_binding_name`	string	Running provider binding ID, name and summary when activating the binding.
`data.provider_binding_hash`	string	Running provider binding ID, name and summary when activating the binding.
`data.last_error`	string	Returned only when the status is `binding_failed`.
`data.registered_at`	string	Creation and last update times, using RFC 3339 format.
`data.updated_at`	string	Creation and last update times, using RFC 3339 format.

Error response¶

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

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`2`（`INVALID_ARGUMENT`）	The fields do not match the status rules, the summary format is incorrect, the request body is inconsistent with the path range, or the running environment access verification fails.	Complete or remove criteria fields based on `status` and check providers and profiles.
`401`	`6`（`UNAUTHENTICATED`）	Lack of valid identity credentials.	Check API Key.
`403`	`5`（`PERMISSION_DENIED`）	The current caller does not have permission to update the agent.	Check the agent authorization in the workspace.
`404`	`3`（`NOT_FOUND`）	The target agent version or runtime provider configuration does not exist.	Query the agent version first and check the provider and configuration files.
`503`	`15`（`UNAVAILABLE`）	Version service, operation record service or authorization dependency are temporarily unavailable.	Try again later.

Follow-up operations¶

After the binding is completed, use the same agent identifier Query agent details to confirm that the running environment is associated.

Last updated on Sep 11, 2026