Search cards and columns within a board

GET

/boards/{board}/search

const url = 'https://projects.work.optidata.cloud/api/boards/1/search?target=App%5CModels%5CCard';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://projects.work.optidata.cloud/api/boards/1/search?target=App%5CModels%5CCard' \
  --header 'Authorization: Bearer <token>'

Filters the board’s cards and columns by free-text query, tags, assignees, statuses, due-date buckets and custom field values. The response has the same shape as Get a board but with columns and cards restricted to the matches (plus a cards_summary with per-card counters). Requires view permission.

Authorizations

bearerAuth

Parameters

Path Parameters

board

required

integer

Board id.

Query Parameters

query

string | null

Free-text search over card titles/content.

by[tags][]

Array<integer>

Only cards having any of these tag ids.

by[assignees][]

Array<integer>

Only cards assigned to any of these user ids.

by[statuses][]

Array<string>

Allowed values: OPEN CLOSED ARCHIVED OVERDUE NEAR FAR

Only cards in any of these statuses / due-date statuses.

by[dueDate][]

Array<string>

Allowed values: overdue today tomorrow this-week next-week next-month future no-date completed

Due-date buckets to match.

by[customFields]

Array<object>

object

definitionId

required

integer

operator

required

string

Allowed values: contains equals gt gte lt lte between is is_not is_any_of before after is_empty is_not_empty

value

Comparison value (type depends on the field type; omitted for is_empty/is_not_empty).

Custom-field filters, e.g. by[customFields][0][definitionId]=12&by[customFields][0][operator]=equals&by[customFields][0][value]=High.

scope[archived]

boolean

Include archived cards/columns.

target

string

Allowed values: App\Models\Card App\Models\Column App\Models\CardTemplate

Restrict matching to one entity type; omit to search cards and columns.

Responses

200

Board payload restricted to matching columns/cards.

application/json

object

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

members

Map of user id → member (with pivot membership info).

object

key

additional properties

object

integer

uuid

string format: uuid

name

string

email

string format: email

avatar_url

string | null format: uri

username

string

company_name

string | null

role

string | null

status

string | null

deleted_at

string | null format: date-time

pivot

Membership metadata.

object

board_id

integer

user_id

integer

permission

string

Allowed values: view interact edit manage

view_mode

string | null

Allowed values: view_kanban view_list

created_at

string format: date-time

updated_at

string format: date-time

tags

Map of tag id → tag (board tags plus common tags).

object

key

additional properties

A label. board_id null means a common (tenant-wide) tag.

object

integer

board_id

integer | null

name

string

>= 2 characters <= 40 characters

description

string | null

>= 3 characters <= 250 characters

color

Hex color (e.g. #52eb00).

string

created_at

string format: date-time

updated_at

string format: date-time

columns

Map of column id → column.

object

key

additional properties

A task list within a board.

object

integer

board_id

integer

name

string

<= 80 characters

description

string | null

<= 300 characters

icon

string | null

<= 255 characters

color

Column accent color (fixed palette).

string | null

Allowed values: #ef4444 #f97316 #f59e0b #84cc16 #10b981 #06b6d4 #3b82f6 #8b5cf6 #ec4899 #64748b

order

Position within the board.

integer

sort_order

Sticky automatic card sort applied to this column, when set.

string | null

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

cards

The board’s cards (listing attributes).

Array<object>

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

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

cards_summary

Per-card counters (present on search responses).

object

key

additional properties

any

custom_field_definitions

Array<object>

Definition of a custom field. board_id null (and is_global true) means tenant-wide.

object

integer

board_id

integer | null

name

string

>= 1 characters <= 60 characters

type

string

Allowed values: text number select checkbox date person

description

string | null

<= 250 characters

config

Type-specific configuration. Examples — text: {multiline, max_length, placeholder, default_value}; select: {options: [{id, label, color}]}; checkbox: {default_value}.

object | null

order

integer

is_required

Required fields block card interactions (comments, files, timers) until filled.

boolean

is_active

boolean

is_global

boolean

created_at

string format: date-time

updated_at

string format: date-time

deleted_at

string | null format: date-time

permissions

The caller’s effective abilities on this board (ability → boolean).

object

key

additional properties

boolean

preferences

The caller’s per-board preferences.

object

view_mode

string

Allowed values: view_kanban view_list

notification

object

notification_mode

string

Allowed values: all assignee mentions silent

is_notified_through_app

boolean

is_notified_through_email

boolean

Example

{
  "visibility": "private",
  "order_cards_direction": "asc",
  "members": {
    "additionalProperty": {
      "pivot": {
        "permission": "view",
        "view_mode": "view_kanban"
      }
    }
  },
  "columns": {
    "additionalProperty": {
      "color": "#ef4444"
    }
  },
  "cards": [
    {
      "type": "ORDINARY",
      "status": "OPEN",
      "cover_color": "#ef4444",
      "due_date_status": "OVERDUE"
    }
  ],
  "custom_field_definitions": [
    {
      "type": "text"
    }
  ],
  "preferences": {
    "view_mode": "view_kanban",
    "notification": {
      "notification_mode": "all"
    }
  }
}

401

Missing, invalid or expired bearer passport.

application/json

object

error

string

Example

{
  "error": "JWT passport exception: Missing bearer token in request"
}

403

The authenticated user lacks the required board permission.

application/json

object

message

string

Example

{
  "message": "This action is unauthorized."
}

404

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

application/json

object

message

string

Example

{
  "message": "Not found."
}

422

Validation failed.

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