Skip to main content

​
Endpoint

PATCH /api/v1/boards/{board_id}
Update mutable properties of an existing board. All fields are optional - only include fields you want to change.

​
Path Parameters

​
board_id
string (UUID)
required
The unique identifier of the board to update

​
Request Body

All fields are optional. Only include fields you want to update.
​
name
string
Display name of the board
​
slug
string
URL-friendly identifier for the board
​
description
string
Detailed description of the board’s purpose. Cannot be empty or whitespace-only if provided.
​
gateway_id
string (UUID)
Gateway ID to associate with this board. The gateway must exist in the organization and have a main agent.
​
board_group_id
string (UUID)
Board group ID to move this board to. Set to null to remove from current group. When changing groups, all agents on related boards are notified of the change.
​
board_type
string
Type of board. When explicitly changing to “goal”, requires objective and success_metrics to be set.
​
objective
string
Primary objective for the board
​
success_metrics
object
Key-value pairs defining success criteria
​
target_date
string (datetime)
Target completion date in ISO 8601 format
​
goal_confirmed
boolean
Whether the goal has been confirmed
​
goal_source
string
Source or origin of the goal
​
require_approval_for_done
boolean
Whether tasks require approval before marking as done
​
require_review_before_done
boolean
Whether tasks require review before completion
​
block_status_changes_with_pending_approval
boolean
Whether status changes are blocked when approval is pending
​
only_lead_can_change_status
boolean
Whether only the board lead can change task status
​
max_agents
integer
Maximum number of agents allowed on this board. Must be >= 0.

​
Response

Returns the updated board object with all current values.
​
id
string (UUID)
Unique identifier for the board
​
organization_id
string (UUID)
Organization that owns this board
​
name
string
Display name of the board
​
slug
string
URL-friendly identifier
​
description
string
Board description
​
gateway_id
string (UUID)
Associated gateway ID
​
board_group_id
string (UUID)
Board group ID, if assigned
​
board_type
string
Type of board
​
objective
string
Primary objective
​
success_metrics
object
Success criteria key-value pairs
​
target_date
string (datetime)
Target completion date
​
goal_confirmed
boolean
Whether goal is confirmed
​
goal_source
string
Source of the goal
​
require_approval_for_done
boolean
Approval requirement setting
​
require_review_before_done
boolean
Review requirement setting
​
block_status_changes_with_pending_approval
boolean
Status change blocking setting
​
only_lead_can_change_status
boolean
Lead-only status change setting
​
max_agents
integer
Maximum agents allowed
​
created_at
string (datetime)
Creation timestamp (unchanged)
​
updated_at
string (datetime)
Last update timestamp (updated to current time)

​
Board Group Change Notifications

When board_group_id is changed, the system automatically:
  1. Notifies all agents on boards in the previous group (if any) that this board has left
  2. Notifies all agents on boards in the new group (if any) that this board has joined
Notification messages include coordination guidance for cross-board work.

​
Example Request

curl -X PATCH "https://api.example.com/api/v1/boards/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Product Launch - Updated",
    "max_agents": 5,
    "target_date": "2026-04-15T23:59:59Z"
  }'

​
Example Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Q1 Product Launch - Updated",
  "slug": "q1-product-launch",
  "description": "Launch new product features for Q1 2026",
  "gateway_id": "550e8400-e29b-41d4-a716-446655440000",
  "board_group_id": null,
  "board_type": "goal",
  "objective": "Successfully launch product with 95% uptime",
  "success_metrics": {
    "uptime": "95%",
    "user_satisfaction": "4.5/5"
  },
  "target_date": "2026-04-15T23:59:59Z",
  "goal_confirmed": true,
  "goal_source": null,
  "require_approval_for_done": true,
  "require_review_before_done": false,
  "block_status_changes_with_pending_approval": false,
  "only_lead_can_change_status": false,
  "max_agents": 5,
  "created_at": "2026-03-05T10:30:00Z",
  "updated_at": "2026-03-05T15:22:00Z"
}

​
Error Responses

​
404 Not Found
Board with the specified ID does not exist or you don’t have access to it
​
422 Unprocessable Entity
  • gateway_id is invalid: Gateway does not exist or does not belong to the organization
  • gateway must have a gateway main agent before boards can be created or updated: Gateway needs a main agent configured
  • board_group_id is invalid: Board group does not exist or does not belong to the organization
  • gateway_id is required: Cannot set gateway_id to null
  • description is required: Description cannot be empty or whitespace-only
  • Goal boards require objective and success_metrics: When explicitly switching to goal type, both must be set

​
Authorization

Requires write access to the board. Typically requires organization admin or specific board write permissions.

Build docs developers (and LLMs) love

Get started for freeTalk to us