Boards API
Retrieve board data including groups, columns, items, and cell values.
Boards API
Every project in ProBeya has a primary board — the visual workspace where items (cards), groups (swimlanes), and columns (custom fields) are managed. The Boards API returns the complete board state in a single call, optimized for rendering Kanban, table, and visual board views.
Endpoints
GET /api/v1/boards/:id
Fetch the primary board for a project by its project ID. Returns the board with all groups, columns, items, and item values in a single payload.
tRPC: boards.getByProjectId
Auth: Bearer token required (scope: read:items) or session cookie
Org context: Required
Board permission: Requires view access on the board
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
id | string (path) | Yes | The project ID (not the board ID) |
Example:
curl -H "Authorization: Bearer probeya_sk_live_..." \
https://acme.probeya.com/api/v1/boards/clx9pj001
Response:
{
"data": {
"id": "clx9bd001",
"name": "Main Board",
"projectId": "clx9pj001",
"organizationId": "clx9abc123def",
"canvasLayout": null,
"createdAt": "2026-02-01T10:00:00.000Z",
"groups": [
{
"id": "clx9gr001",
"boardId": "clx9bd001",
"name": "To Do",
"color": "#579bfc",
"sortOrder": 0,
"collapsed": false
},
{
"id": "clx9gr002",
"boardId": "clx9bd001",
"name": "In Progress",
"color": "#fdab3d",
"sortOrder": 1,
"collapsed": false
},
{
"id": "clx9gr003",
"boardId": "clx9bd001",
"name": "Done",
"color": "#00c875",
"sortOrder": 2,
"collapsed": false
}
],
"columns": [
{
"id": "clx9co001",
"boardId": "clx9bd001",
"name": "Status",
"type": "status",
"sortOrder": 0,
"settings": null,
"formula": null
},
{
"id": "clx9co002",
"boardId": "clx9bd001",
"name": "Person",
"type": "person",
"sortOrder": 1,
"settings": null,
"formula": null
},
{
"id": "clx9co003",
"boardId": "clx9bd001",
"name": "Date",
"type": "date",
"sortOrder": 2,
"settings": null,
"formula": null
},
{
"id": "clx9co004",
"boardId": "clx9bd001",
"name": "Priority",
"type": "priority",
"sortOrder": 3,
"settings": null,
"formula": null
}
],
"items": [
{
"id": "clx9it001",
"boardId": "clx9bd001",
"groupId": "clx9gr001",
"name": "Draft SOP v2.0",
"sortOrder": 0,
"assigneeId": "clx9us001",
"createdById": "clx9us002",
"createdAt": "2026-02-10T09:15:00.000Z",
"updatedAt": "2026-03-28T11:00:00.000Z"
}
],
"itemValues": [
{
"id": "clx9iv001",
"itemId": "clx9it001",
"columnId": "clx9co001",
"value": "Working on it"
}
]
}
}
Errors:
| Code | Description |
|---|---|
| 401 | Missing or invalid authentication |
| 403 | Insufficient board permission (requires view) |
| 404 | No board found for the given project ID |
Response Structure
The board response is a denormalized payload designed for single-fetch rendering:
| Field | Type | Description |
|---|---|---|
id | string | Board ID (cuid2) |
name | string | Board display name (default: “Main Board”) |
projectId | string | Parent project ID |
organizationId | string | Tenant ID |
canvasLayout | object or null | Visual board builder state (widgets, pan, zoom) |
groups | array | Swimlane groups ordered by sortOrder |
columns | array | Custom field definitions ordered by sortOrder |
items | array | All items (cards) on the board ordered by sortOrder |
itemValues | array | Cell values linking items to columns (EAV pattern) |
Column Types
ProBeya supports a rich set of column types for custom fields:
| Type | Description |
|---|---|
status | Dropdown status labels with colors |
person | User assignment (references user ID) |
date | Date picker |
priority | Priority level (critical, high, medium, low) |
text | Free-text field |
number | Numeric value |
checkbox | Boolean toggle |
dropdown | Custom dropdown options |
rating | Star rating (1-5) |
formula | Computed column referencing other columns |
link | URL field |
file | File attachment reference |
timeline | Date range (start + end) |
color | Color picker |
tRPC-Only Board Procedures
The following board operations are available via tRPC but not yet exposed through the REST API:
| Procedure | Description |
|---|---|
boards.list | List all boards visible to the user in the org |
boards.get | Fetch a board by its board ID (not project ID) |
boards.getItems | Fetch items with values for a specific board |
boards.createGroup | Create a new group (swimlane) |
boards.updateGroup | Update group name, color, collapsed state |
boards.deleteGroup | Delete a group and its items |
boards.reorderGroups | Reorder groups within a board |
boards.createColumn | Create a new custom field column |
boards.updateColumn | Update column properties |
boards.deleteColumn | Delete a column |
boards.reorderColumns | Reorder columns within a board |
boards.getPermissions | List explicit board permissions |
boards.setPermission | Grant/update user permission on a board |
boards.removePermission | Revoke explicit board permission |
boards.validateFormula | Validate a formula expression |
boards.saveCanvasLayout | Save visual board builder state |
boards.getCanvasLayout | Fetch visual board builder state |
Was this page helpful?