Skip to content
Optiwork API Docs

Create a card

POST
/boards/{board}/cards
curl --request POST \
  --url https://projects.work.optidata.cloud/api/boards/1/cards \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "column_id": 301, "title": "Draft homepage copy", "content": "{}", "due_date": "2026-08-01T12:00:00Z", "cover_color": "#3b82f6" }'

Creates a card (task) in one of the board’s columns. Optionally applies a card template, sets a due date, cover color and rich-text content. @-mentions inside content trigger notifications. Requires edit permission (create policy).

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
board
required
integer

Board id.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
column_id
required

Target column (must exist).

integer
title
required
string
<= 255 characters
content

Rich-text card description (serialized editor document, JSON string).

string | null
type

Card type; only ORDINARY can be created directly.

string | null
Allowed values: ORDINARY
status
string | null
Allowed values: OPEN CLOSED ARCHIVED
icon
string | null
order

Position within the column.

integer | null
due_date
string | null format: date-time
template_id

Card template to apply (must be visible on this board).

integer | null
cover_color
string | null
Allowed values: #ef4444 #f97316 #eab308 #22c55e #06b6d4 #3b82f6 #8b5cf6 #ec4899 #6b7280 #000000
source

Originating Optiwork app nickname when the card is created from another app (e.g. mail).

string | null
Example
{
  "column_id": 301,
  "title": "Draft homepage copy",
  "content": "{}",
  "due_date": "2026-08-01T12:00:00Z",
  "cover_color": "#3b82f6"
}

Responses

Section titled “Responses”

200

Section titled “200”

The created card.

Media typeapplication/json

A task. Derived attributes (tags_ids, assignees_ids, *_count, human_*, due_date_status, is_time_tracking) are present on single card reads; list contexts may return a subset of attributes.

object
id
integer
board_id
integer
column_id
integer
user_id

Creator user id.

integer | null
title
string
<= 255 characters
content

Rich-text description (serialized editor document, JSON string).

string | null
type
string
Allowed values: ORDINARY CHECKLIST_ITEM
status
string | null
Allowed values: OPEN CLOSED ARCHIVED
icon
string | null
order

Position within its column.

integer
number

Sequential card number within the board.

integer
due_date
string | null format: date-time
due_date_hash

Opaque id tied to the current due date (used for calendar sync).

string | null
pinned_at
string | null format: date-time
completed_at
string | null format: date-time
archived_at
string | null format: date-time
deleted_at
string | null format: date-time
checklist_id

Owning checklist (checklist-item cards only).

integer | null
checklist_items

Cached count of checklist items on this card.

integer | null
checklist_items_completed
integer | null
card_recurrence_id
integer | null
cover_color
string | null
Allowed values: #ef4444 #f97316 #eab308 #22c55e #06b6d4 #3b82f6 #8b5cf6 #ec4899 #6b7280 #000000
created_at
string format: date-time
updated_at
string format: date-time
tags_ids

Ids of the card’s tags (as strings; may contain null when empty).

Array<string | null> | null
assignees_ids

Ids of the card’s assignees (as strings; may contain null when empty).

Array<string | null> | null
is_time_tracking

Truthy when the caller has a running timer on this card.

boolean | integer | null
comments_count
integer
files_count
integer
custom_fields_count
integer
due_date_status
string | null
Allowed values: OVERDUE NEAR FAR
human_due_date

Localized short due date (e.g. Aug 1, 2026).

string | null
short_locale_date
string | null
human_verbose_due_date
string | null
is_completed
boolean
is_recurrent
boolean
Example
{
  "type": "ORDINARY",
  "status": "OPEN",
  "cover_color": "#ef4444",
  "due_date_status": "OVERDUE"
}

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."
}

404

Section titled “404”

Resource not found, or a nested resource does not belong to its parent in the path.

Media typeapplication/json
object
message
string
Example
{
  "message": "Not found."
}

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."
    ]
  }
}