Update an agent branch

Rename, describe, protect, archive, or restore an agent branch when permitted.

Endpoint

PATCH/api/v1/workspaces/{workspace_id}/agents/{agent_id}/branches/{branch_id}

Authentication

Operation class	Authentication	Minimum role	API key
customer-api	Bearer API key or dashboard session cookie; dashboard mutations also require X-CX-Request: 1.	member	Allowed

Parameters

Name	In	Type	Required	Description
`workspace_id`	path	string	Yes	—
`agent_id`	path	string	Yes	—
`branch_id`	path	string	Yes	—

Request body

application/json request schema

Field path	Type	Reference	Format	Nullable	Required	Enum	Description
`$`	object	PermintaanUbahBranch	—	No	Yes	—	—
`archived`	boolean or null	—	—	Yes	No	—	—
`description`	string or null	—	—	Yes	No	—	—
`is_protected`	boolean or null	—	—	Yes	No	—	—
`name`	string or null	—	—	Yes	No	—	—

Example

curl --request PATCH 'https://operade.ai/api/v1/workspaces/ws_demo/agents/agt_demo/branches/br_demo' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"description":"Updated example branch"}'

{
  "description": "Updated example branch"
}

Responses

Status	Description	Content
`4XX`	Handled client error	application/json: ErrorResponse
`200`	Successful Response	application/json: AgentBranch

4XX application/json response schema

Field path	Type	Reference	Format	Nullable	Required	Enum	Description
`$`	object	ErrorResponse	—	No	Yes	—	—
`error`	object	ErrorItem	—	No	Yes	—	—
`error.code`	string	—	—	No	Yes	—	—
`error.details`	object	—	—	No	No	—	—
`error.message`	string	—	—	No	Yes	—	—

200 application/json response schema

Field path	Type	Reference	Format	Nullable	Required	Enum	Description
`$`	object	AgentBranch	—	No	Yes	—	—
`archived_at`	string or null	—	date-time	Yes	Yes	—	—
`conversations_7d`	integer	—	—	No	Yes	—	—
`created_at`	string	—	date-time	No	Yes	—	—
`created_by`	object	NamedActor	—	No	Yes	—	—
`created_by.email`	string	—	—	No	Yes	—	—
`created_by.id`	string	—	—	No	Yes	—	—
`created_by.name`	string	—	—	No	Yes	—	—
`description`	string	—	—	No	Yes	—	—
`has_draft`	boolean	—	—	No	Yes	—	—
`id`	string	—	—	No	Yes	—	—
`is_live`	boolean	—	—	No	Yes	—	—
`is_main`	boolean	—	—	No	Yes	—	—
`is_protected`	boolean	—	—	No	Yes	—	—
`name`	string	—	—	No	Yes	—	—
`status`	string	—	—	No	Yes	"Main", "Up to date", "Behind Main"	—
`tip_version_id`	string	—	—	No	Yes	—	—
`traffic_percentage`	number	—	—	No	Yes	—	—
`updated_at`	string	—	date-time	No	Yes	—	—

Response example

{
  "id": "string",
  "name": "string",
  "description": "string",
  "is_main": false,
  "is_protected": false,
  "traffic_percentage": 0,
  "tip_version_id": "string",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "archived_at": "2026-01-01T00:00:00Z",
  "created_by": {
    "id": "string",
    "name": "string",
    "email": "string"
  },
  "conversations_7d": 0,
  "has_draft": false,
  "is_live": false,
  "status": "Main"
}

Errors

Reviewed common and route-declared errors are summarized here; the list is not exhaustive. Start with the distributed error index to find each code's canonical domain page.

Status	Code	Description
`401`	`unauthenticated`	Authentication is missing, invalid, or revoked.
`403`	`forbidden`	The authenticated caller does not have access to this operation.
`404`	`not_found`	The requested workspace resource was not found.
`422`	`validation_failed`	The request did not pass field or business validation.