Boards API: Create, Update, Archive, and Query

Boards are the top-level containers in Hashboard. Each board holds an ordered set of columns, and each column holds cards. The board API lets you create and manage boards, control their visibility, and fetch a full composite view (board metadata, columns, and cards) in a single round-trip. Columns and their creation endpoint are also documented here; standalone column operations (rename, reorder, archive) are on the Columns page. All endpoints require a bearer token (Authorization: Bearer hb_…) or session cookie. Visibility changes, archival, and deletion are creator-only operations.

GET /api/v1/boards

List every board that is visible to the authenticated principal. Returns live boards by default; pass ?archived=true to list archived boards instead. GET /api/v1/boards

Query Parameters

archived

string

Pass true to return archived boards instead of live ones. Any other value (or omitting the parameter) returns live boards.

Response

Returns an array of Board objects.

string

Unique board ID (UUID).

name

string

Display name of the board.

description

string | null

Optional board description.

visibility

string

One of private, link-read, link-write, or public. See Visibility modes below.

createdBy

string

Principal ID of the board creator.

createdAt

string

ISO 8601 timestamp.

updatedAt

string

ISO 8601 timestamp of the last update.

archivedAt

string | null

ISO 8601 timestamp if archived, otherwise null.

curl -H "Authorization: Bearer hb_…" \
  https://your-instance.example/api/v1/boards

POST /api/v1/boards

Create a new board. The authenticated principal becomes the board’s creator and can later archive, unarchive, and change visibility. Returns 201 Created with the new board. POST /api/v1/boards

Request Body

name

string

required

The board’s display name.

description

string

Optional description rendered on the board page.

visibility

string

One of private (default), link-read, link-write, or public.

Response

Returns the created Board object (same shape as the list items above).

curl -X POST \
  -H "Authorization: Bearer hb_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sprint 12", "visibility": "private"}' \
  https://your-instance.example/api/v1/boards

GET /api/v1/boards/{id}

Fetch a composite board view in a single request. The response includes the board row, its ordered columns, and every card you can see. This is the same payload served at /boards/{id} with Accept: application/json. GET /api/v1/boards/{id}

Path Parameters

string

required

Board ID.

Response

board

Board

The board metadata object (same fields as the list response).

columns

Column[]

Ordered array of columns belonging to this board.

Show Column fields

string

UUID.

boardId

string

Parent board ID.

name

string

Column display name.

pos

string

Fractional-index position key (lexicographic).

createdAt

string

ISO 8601 timestamp.

archivedAt

string | null

Set when archived, otherwise null.

cards

Card[]

Cards on this board that are visible to the caller, ordered by position within their column.

Show Card fields

string

UUID.

boardId

string | null

Board this card belongs to.

columnId

string | null

Column this card sits in.

pos

string | null

Fractional-index position within its column.

docId

string

ID of the card’s description document (use PUT /api/v1/docs/{docId} to edit).

title

string

Card title.

visibility

string

Card visibility mode.

dueAt

string | null

ISO 8601 due date, or null.

createdBy

string

Creator principal ID.

createdAt

string

ISO 8601 timestamp.

updatedAt

string

ISO 8601 timestamp.

archivedAt

string | null

Set when archived, otherwise null.

curl -H "Authorization: Bearer hb_…" \
  https://your-instance.example/api/v1/boards/018f2e3a-…

Append .md to the board URL (/boards/{id}.md) or send Accept: text/markdown to get the board as a markdown document with YAML frontmatter — useful for agents that need a concise text snapshot.

PATCH /api/v1/boards/{id}

Update one or more fields on a board. All fields are optional; send only what you want to change. Visibility changes are creator-only — other principals receive 403. PATCH /api/v1/boards/{id}

Path Parameters

string

required

Board ID.

Request Body

name

string

New display name.

description

string | null

New description. Pass null to clear it.

visibility

string

New visibility mode. Creator-only. One of private, link-read, link-write, public.

Response

Returns the updated Board object.

curl -X PATCH \
  -H "Authorization: Bearer hb_…" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated scope for Q3"}' \
  https://your-instance.example/api/v1/boards/018f2e3a-…

POST /api/v1/boards/{id}/archive

Archive a board. Creator-only. Archived boards are hidden from the default list but remain accessible via GET /api/v1/boards?archived=true and their direct URL. The board’s columns and cards are also considered archived. POST /api/v1/boards/{id}/archive

Path Parameters

string

required

Board ID.

Response

Returns the updated Board object with archivedAt set.

curl -X POST \
  -H "Authorization: Bearer hb_…" \
  https://your-instance.example/api/v1/boards/018f2e3a-…/archive

POST /api/v1/boards/{id}/unarchive

Restore an archived board to active status. Creator-only. POST /api/v1/boards/{id}/unarchive

Path Parameters

string

required

Board ID.

Response

Returns the updated Board object with archivedAt set to null.

curl -X POST \
  -H "Authorization: Bearer hb_…" \
  https://your-instance.example/api/v1/boards/018f2e3a-…/unarchive

GET /api/v1/boards/{id}/archived

Retrieve a snapshot of the board’s archived content — the columns and cards that have been individually archived (as opposed to the entire board being archived). Useful for building a restore UI. GET /api/v1/boards/{id}/archived

Path Parameters

string

required

Board ID.

Response

columns

Column[]

Archived columns belonging to this board.

cards

Card[]

Archived cards belonging to this board that are visible to the caller.

curl -H "Authorization: Bearer hb_…" \
  https://your-instance.example/api/v1/boards/018f2e3a-…/archived

GET /api/v1/boards/{id}/columns

List the live (non-archived) columns of a board in their display order. To create a column, use the POST variant below. GET /api/v1/boards/{id}/columns

Path Parameters

string

required

Board ID.

Response

Returns an ordered array of Column objects (fields described under GET /boards/ above).

curl -H "Authorization: Bearer hb_…" \
  https://your-instance.example/api/v1/boards/018f2e3a-…/columns

POST /api/v1/boards/{id}/columns

Add a new column at the end of a board. Returns 201 Created with the new column. To reorder or rename columns after creation see the Columns API. POST /api/v1/boards/{id}/columns

Path Parameters

string

required

Board ID.

Request Body

name

string

required

Column display name.

Response

Returns the created Column object.

curl -X POST \
  -H "Authorization: Bearer hb_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "In Review"}' \
  https://your-instance.example/api/v1/boards/018f2e3a-…/columns

GET /api/v1/boards/{id}/cards

List all cards on a board that are visible to the caller, ordered by their position within their respective columns. This is a flat list across all columns; use the columnId field on each card to group them client-side, or fetch the composite view at GET /api/v1/boards/{id} instead. GET /api/v1/boards/{id}/cards

Path Parameters

string

required

Board ID.

Response

Returns an array of Card objects (fields described under GET /boards/ above).

curl -H "Authorization: Bearer hb_…" \
  https://your-instance.example/api/v1/boards/018f2e3a-…/cards

GET /api/v1/boards/{id}/activity

Fetch the activity feed for a board, newest events first. Each event records who did what and when. Activity entries survive the deletion of their subject (foreign keys use ON DELETE SET NULL). GET /api/v1/boards/{id}/activity

Path Parameters

string

required

Board ID.

Query Parameters

limit

string

Maximum number of events to return. Defaults to 50.

Response

Returns an array of ActivityEvent objects.

string

Event ID.

boardId

string | null

Related board ID (may be null if the board was deleted).

cardId

string | null

Related card ID, if the event is card-scoped.

docId

string | null

Related document ID, if the event is doc-scoped.

actorId

string

Principal who performed the action.

type

string

Event type string (e.g. card.created, column.archived).

data

any

Event-specific payload (structure depends on type).

createdAt

string

ISO 8601 timestamp.

curl -H "Authorization: Bearer hb_…" \
  "https://your-instance.example/api/v1/boards/018f2e3a-…/activity?limit=20"

Visibility modes

Every board carries a visibility field that controls who can see and interact with it. The value propagates downward: a board’s visibility cascades to its cards, their description documents, and any linked documents.

Value	Who can read	Who can write
`private`	Creator’s household + card assignees	Creator’s household
`link-read`	Anyone with the board URL	Creator’s household
`link-write`	Anyone with the board URL	Anyone with the board URL
`public`	Every authenticated user (world-readable)	Creator’s household

Visibility changes on a board are creator-only. A non-creator who sends a PATCH with a visibility field receives 403 Forbidden.

Overview

Boards & Columns

Cards & Documents

Content & Activity

Administration

Documentation Index

​GET /api/v1/boards

​Query Parameters

​Response

​POST /api/v1/boards

​Request Body

​Response

​GET /api/v1/boards/{id}

​Path Parameters

​Response

​PATCH /api/v1/boards/{id}

​Path Parameters

​Request Body

​Response

​POST /api/v1/boards/{id}/archive

​Path Parameters

​Response

​POST /api/v1/boards/{id}/unarchive

​Path Parameters

​Response

​GET /api/v1/boards/{id}/archived

​Path Parameters

​Response

​GET /api/v1/boards/{id}/columns

​Path Parameters

​Response

​POST /api/v1/boards/{id}/columns

​Path Parameters

​Request Body

​Response

​GET /api/v1/boards/{id}/cards

​Path Parameters

​Response

​GET /api/v1/boards/{id}/activity

​Path Parameters

​Query Parameters

​Response

​Visibility modes

Build docs developers (and LLMs) love

GET /api/v1/boards

Query Parameters

Response

POST /api/v1/boards

Request Body

Response

GET /api/v1/boards/{id}

Path Parameters

Response

PATCH /api/v1/boards/{id}

Path Parameters

Request Body

Response

POST /api/v1/boards/{id}/archive

Path Parameters

Response

POST /api/v1/boards/{id}/unarchive

Path Parameters

Response

GET /api/v1/boards/{id}/archived

Path Parameters

Response

GET /api/v1/boards/{id}/columns

Path Parameters

Response

POST /api/v1/boards/{id}/columns

Path Parameters

Request Body

Response

GET /api/v1/boards/{id}/cards

Path Parameters

Response

GET /api/v1/boards/{id}/activity

Path Parameters

Query Parameters

Response

Visibility modes