Skip to content
Optiwork API Docs

Create a board

POST
/boards
curl --request POST \
  --url https://projects.work.optidata.cloud/api/boards \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Website Redesign", "description": "Q3 marketing site refresh", "icon": "🎨", "parent_id": null, "user_permissions": { "8": "edit", "9": "manage" } }'

Creates a board owned by the authenticated user, attaches the listed members with their permission levels, and optionally seeds columns from a project template. Members receive an in-app notification.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
required
string
<= 80 characters
description
string | null
<= 600 characters
icon

Emoji used as the board icon.

string | null
<= 14 characters
parent_id

Id of an existing board to nest this board under.

integer | null
user_permissions
required

Map of user id → permission level for the initial members. Use none to skip a user. The creator is always the owner.

object
key
additional properties
string
Allowed values: none view interact edit manage
template

Optional project template used to seed the board’s columns.

string | null
Example
{
  "name": "Website Redesign",
  "description": "Q3 marketing site refresh",
  "icon": "🎨",
  "parent_id": null,
  "user_permissions": {
    "8": "edit",
    "9": "manage"
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

The created board.

Media typeapplication/json

A project (kanban board). Boards nest via parent_id.

object
id
integer
user_id

Owner user id.

integer | null
group_id
integer | null
cuid

Tenant/company identifier the board belongs to.

string
parent_id

Parent board id (null for root boards).

integer | null
name
string
<= 80 characters
description
string | null
<= 600 characters
icon

Emoji icon.

string | null
visibility
string
Allowed values: private public
order_cards_by

Default card sort field for new columns.

string | null
order_cards_direction
string | null
Allowed values: asc desc
archived_at
string | null format: date-time
created_at
string format: date-time
updated_at
string format: date-time
deleted_at
string | null format: date-time
Example
{
  "visibility": "private",
  "order_cards_direction": "asc"
}

401

Section titled “401”

Missing, invalid or expired bearer passport.

Media typeapplication/json
object
error
string
Example
{
  "error": "JWT passport exception: Missing bearer token in request"
}

403

Section titled “403”

The authenticated user lacks the required board permission.

Media typeapplication/json
object
message
string
Example
{
  "message": "This action is unauthorized."
}

422

Section titled “422”

Validation failed.

Media typeapplication/json
object
message

First validation error message.

string
errors

Map of field name → list of error messages.

object
key
additional properties
Array<string>
Example
{
  "message": "The name field is required.",
  "errors": {
    "name": [
      "The name field is required."
    ]
  }
}