# 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.

```text
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

```bash
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.

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

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

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - 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](get-agent.md) or check whether the running environment binding has been restored to the expected state.