Boards & Tasks

These operations work on the same boards you see under Tasks in the app. Reads count toward the read limit (120 per minute) and writes toward the write limit (60 per minute). Each operation is also an MCP tool with the name shown in brackets.

Names or IDs

Write operations accept either an ID or a name for columns and labels: sectionId or sectionName, labelId or labelName, and labelNames on tasks. Names are matched case-insensitively. If a name matches more than one column or label, the request fails with 409 conflict and the error message lists the candidates; retry with the ID.

Errors

List Boards

GET /v2/boards (list_boards)

Your boards with their columns and open-task counts. Call it first to find the boardId the other operations need.

{
  "data": {
    "boards": [
      {
        "boardId": "b5d0...",
        "title": "Launch",
        "boardType": "project",
        "color": "#3B82F6",
        "openTaskCount": 7,
        "sections": [{ "sectionId": "s1...", "name": "To Do" }]
      }
    ]
  }
}

Create a Board

POST /v2/boards (create_board)

Creates a project board with the default Inbox, To Do, In Progress, and Done columns. Returns 201 with the board and its sections.

Get a Board

GET /v2/boards/{boardId} (get_board)

One board with its columns (sections), labels, and tasks.

Each task has taskId, title, sectionId, priority, dueDate, labelIds, completedAt, and subtaskCount.

Update a Board

PATCH /v2/boards/{boardId} (update_board)

Renames a board or changes its color or description. Only the board owner can do this.

Search Tasks

GET /v2/tasks/search (search_tasks)

Searches tasks across all your boards, or one board with boardId.

curl "https://developer.optiverse.ai/api/v2/tasks/search?priority=1,2&dueBefore=2026-10-31" \
  -H "Authorization: Bearer optiuser_v1_your_key_here"

Date-only bounds use calendar days, including tasks with a due time on that day. Timestamp bounds accept a timezone and compare UTC instants; board due times without a timezone are interpreted as UTC. Tasks with only a due date overlap that full UTC day.

Manage Columns

POST /v2/boards/{boardId}/sections (manage_board_section)

Creates, updates, deletes, or reorders columns. Deleting a column moves its tasks to Inbox. Inbox and Done cannot be deleted.

{ "action": "create", "name": "Review", "order": 2 }

Manage Labels

POST /v2/boards/{boardId}/labels (manage_board_label)

Create a Task

POST /v2/boards/{boardId}/tasks (create_task)

Creates one task. Returns 201 with the task. For three or more tasks, use Create tasks in bulk.

curl -X POST "https://developer.optiverse.ai/api/v2/boards/b5d0.../tasks" \
  -H "Authorization: Bearer optiuser_v1_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Send renewal contract to Mario", "sectionName": "To Do", "priority": 2, "dueDate": "2026-10-20" }'

Update a Task

PATCH /v2/boards/{boardId}/tasks/{taskId} (update_task)

Updates one task and optionally moves it to another column. Send only the fields you want to change.

• completed: true marks the task done and moves it to Done; false reopens it.
• labelNames and subtasks replace the existing lists.
• dueDate: null clears the due date.
• sectionId or sectionName moves the task; position places it within the column.

Create Tasks in Bulk

POST /v2/boards/{boardId}/tasks/batch (batch_create_tasks)

Creates up to 40 tasks on one board, for example a meeting's action items. Each item in tasks takes the same fields as Create a task.

All columns, labels, and due dates are checked before the first write. The response includes tasks, status (completed or partial), and remainingTaskIndexes (zero-based indexes of unattempted items). A completed batch has an empty remaining list.

If persistence fails after work starts, the response contains a partial receipt instead of hiding created tasks. Its failure has taskIndex, code, message, and retryable: false. When the outcome of the failed item is uncertain, uncertainTaskId identifies the task to look for before attempting that item again. The failed index is separate from the unattempted indexes. Do not replay the entire batch: keep the returned tasks and inspect the failed item before submitting only the remaining work. Each task is saved atomically, but the entire batch is not one transaction. If the first task is rejected, nothing was saved and the request fails with the usual error, for example 403 forbidden when you can view the board but not edit it.

{
  "tasks": [
    { "title": "Send renewal contract", "sectionName": "To Do", "transcriptId": "8f0c..." },
    { "title": "Book follow-up call", "priority": 3 }
  ]
}

Move Tasks

POST /v2/boards/{boardId}/tasks/move (move_tasks)

Moves up to 50 tasks on one board to the same column.