Re-coordinate the running environment¶

Re-register and activate bindings for a specified run provider configuration for an agent version. Before calling, please confirm that the agent version, provider, and configuration file all exist, and that the caller has update permissions for the agent.

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

Preparation before calling¶

First confirm that the agent version, running provider and configuration file all 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: The agent version to coordinate.
$PROVIDER: Running provider ID.
$PROFILE: Profile ID of the running provider.

The request body of this interface must be empty.

Request example¶

curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/versions/$VERSION/runtime-bindings/$PROVIDER/$PROFILE/reconcile" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

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 to reconcile.
`provider`	string	Yes	Running provider ID.
`profile`	string	Yes	The profile ID of the running provider.

Successful response¶

When successful, 200 is returned. data in the unified response is bound to the current running environment. Receiving 200 indicates that this coordination request has been successfully processed; please use the returned binding status to determine whether it has been activated.

{
  "code": 0,
  "data": {
    "workspace_id": "ws_01",
    "agent_id": "agent_01",
    "agent_version": "1",
    "provider": "matrixone",
    "profile": "default",
    "provider_binding_id": "pb_01",
    "provider_binding_name": "default-binding",
    "provider_binding_hash": "sha256:0123456789abcdef",
    "status": "active",
    "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	Binding status, may be `pending`, `active`, `binding_failed` or `disabled`.
`data.last_error`	string	Failure reason returned only when status is `binding_failed`.
`data.provider_binding_id`	string	Run provider side binding ID, name and summary.
`data.provider_binding_name`	string	Run provider side binding ID, name and summary.
`data.provider_binding_hash`	string	Run provider side binding ID, name and summary.
`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 path parameter is invalid, the request body is not empty, the version is deactivated, or the provider is not a type supported by the coordination interface.	Use valid path parameters and remove request body; check version status and running provider.
`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 workspace and agent authorizations.
`404`	`3`（`NOT_FOUND`）	Agent version or runtime provider configuration does not exist.	Check identifiers in paths.
`503`	`15`（`UNAVAILABLE`）	Version service, operation record service or authorization dependency are temporarily unavailable.	Try again later.

Follow-up operations¶

After coordination is completed, use the same agent identifier to Query agent details or check whether the running environment binding has been restored to the expected state.

Last updated on Sep 11, 2026