Skip to main content

​
Endpoint

POST /api/v1/boards
Create a new board in the active organization. The gateway must have a main agent configured before boards can be created.

​
Request Body

​
name
string
required
Display name of the board
​
slug
string
required
URL-friendly identifier for the board
​
description
string
required
Detailed description of the board’s purpose. Cannot be empty or whitespace-only.
​
gateway_id
string (UUID)
required
Gateway ID to associate with this board. The gateway must exist and have a main agent configured.
​
board_group_id
string (UUID)
Board group ID to add this board to. Must be a valid group in the organization.
​
board_type
string
default:"goal"
Type of board. Typically “goal” for goal-oriented boards.
​
objective
string
Primary objective for the board. Required if goal_confirmed is true.
​
success_metrics
object
Key-value pairs defining success criteria. Required if goal_confirmed is true.Example:
{
  "uptime": "99%",
  "response_time": "< 200ms"
}
​
target_date
string (datetime)
Target completion date in ISO 8601 format
​
goal_confirmed
boolean
default:"false"
Whether the goal has been confirmed. If true, objective and success_metrics are required.
​
goal_source
string
Source or origin of the goal (e.g., “Product roadmap Q1”)
​
require_approval_for_done
boolean
default:"true"
Whether tasks require approval before marking as done
​
require_review_before_done
boolean
default:"false"
Whether tasks require review before completion
​
block_status_changes_with_pending_approval
boolean
default:"false"
Whether status changes are blocked when approval is pending
​
only_lead_can_change_status
boolean
default:"false"
Whether only the board lead can change task status
​
max_agents
integer
default:"1"
Maximum number of agents allowed on this board. Must be >= 0.

​
Response

Returns the created board object.
​
id
string (UUID)
Unique identifier for the created 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
​
updated_at
string (datetime)
Last update timestamp

​
Example Request

curl -X POST "https://api.example.com/api/v1/boards" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Product Launch",
    "slug": "q1-product-launch",
    "description": "Launch new product features for Q1 2026",
    "gateway_id": "550e8400-e29b-41d4-a716-446655440000",
    "board_type": "goal",
    "objective": "Successfully launch product with 95% uptime",
    "success_metrics": {
      "uptime": "95%",
      "user_satisfaction": "4.5/5"
    },
    "target_date": "2026-03-31T23:59:59Z",
    "goal_confirmed": true,
    "max_agents": 3
  }'

​
Example Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Q1 Product Launch",
  "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-03-31T23: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": 3,
  "created_at": "2026-03-05T10:30:00Z",
  "updated_at": "2026-03-05T10:30:00Z"
}

​
Error Responses

​
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 first
  • board_group_id is invalid: Board group does not exist or does not belong to the organization
  • gateway_id is required: No gateway_id provided
  • description is required: Description is empty or whitespace-only
  • Confirmed goal boards require objective and success_metrics: When goal_confirmed is true, both fields must be provided

​
Authorization

Requires organization admin authentication. Only organization admins can create boards.

Build docs developers (and LLMs) love

Get started for freeTalk to us