Set as default version¶

Set the runnable version as the default version for the agent lineage.

HTTP
POST $CLOUDSIGMA_API_BASE/workspaces/{workspace_id}/agents/{agent_id}/versions/{version}/default

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First query the agent version and confirm that you want to set it as the default version number.

Set the operation-specific values used in the request:

$WORKSPACE_ID: Target workspace ID, passed through the X-Workspace-ID header and as workspace_id in the path.
$AGENT_ID: Target agent ID, as agent_id in the path.
$VERSION: The version number to set as the default version, as version in the path.

Request¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/versions/$VERSION/default" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

Parameter reference

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	The version number to set as the default version.

Successful response¶

Returns 200 on success. data is the updated version pedigree.

Response example

JSON
{
  "code": 0,
  "data": {
    "workspace_id": "ws_01",
    "agent_id": "agent_01",
    "default_version": "v3",
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z"
  }
}

Field reference

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` on success.
`data.workspace_id`	string	The workspace and agent ID to which the agent belongs.
`data.agent_id`	string	The workspace and agent ID to which the agent belongs.
`data.default_version`	string	The default version used by the current agent lineage.
`data.created_at`	string	Version lineage creation time, using RFC 3339 format.
`data.updated_at`	string	The last modification time of the default version, using RFC 3339 format.

Error response¶

Response example

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

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`2`（`INVALID_ARGUMENT`）	The path parameter is empty or has an invalid format, or the target version cannot be used as the default version.	Check the workspace, agent and version identification; select a runnable version.
`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 agent or version does not exist.	Query the agent version first.
`503`	`15`（`UNAVAILABLE`）	The agent resource service or its authorized dependencies are temporarily unavailable.	Try again later.

Follow-up operations¶

Use the same agent ID Query the agent version to confirm the default version, or Query agent details to check the current effective configuration.

Last updated on Sep 15, 2026