API Reference¶

HoneyDew exposes a REST API for managing boards, columns, cards, and labels. All endpoints are prefixed with /api.

Overview¶

Property	Value
Base URL	`http://localhost:8000`
Auth	None (designed for local / trusted-network use)
Content type	`application/json`
Interactive docs	`http://localhost:8000/docs` (Swagger UI, auto-generated by FastAPI)

Health Check¶

GET /health

Returns {"status": "healthy"} when the backend is running. Use this to verify connectivity before making API calls.

Configuration¶

GET /api/config

Returns the application configuration (user and agent profile names, board definitions). Useful for agents that need to discover profile IDs at runtime.

Boards¶

List all boards¶

GET /api/boards

Returns an array of boards (id, name, created_at). Does not include nested columns/cards.

Create a board¶

POST /api/boards

Field	Type	Required	Description
`name`	string	Yes	Board name (1–255 chars).
`columns`	string[]	No	Column names in order. Defaults to `["To Do", "In Progress", "Done"]`.

Get a board¶

GET /api/boards/{id}

Returns the board with all columns and cards. Supports an optional query parameter:

Param	Type	Description
`profile`	string	Filter cards to only those owned by this profile ID.

Update a board¶

PATCH /api/boards/{id}

Field	Type	Required	Description
`name`	string	No	New board name.

Delete a board¶

DELETE /api/boards/{id}

Deletes the board and all its columns and cards. Returns 204 No Content.

Columns¶

Create a column¶

POST /api/columns

Field	Type	Required	Description
`board_id`	int	Yes	The board to add the column to.
`name`	string	Yes	Column name (1–255 chars).
`position`	int	No	Position index (0-based). Appends to end if omitted.

Update a column¶

PATCH /api/columns/{id}

Field	Type	Required	Description
`name`	string	No	New column name.
`position`	int	No	New position index.

Delete a column¶

DELETE /api/columns/{id}

Deletes the column and all its cards. Returns 204 No Content.

Cards¶

List cards¶

GET /api/cards

Param	Type	Description
`board_id`	int	Filter by board.
`column_id`	int	Filter by column (takes precedence over `board_id`).
`profile`	string	Filter by profile ID.
`priority`	int	Filter by priority (1–4).
`has_due_date`	bool	`true` = only cards with a due date; `false` = only cards without.

Create a card¶

POST /api/cards

Field	Type	Required	Default	Description
`column_id`	int	Yes	—	Column to place the card in.
`title`	string	Yes	—	Card title (1–255 chars).
`description`	string	No	`null`	Card description (max 5000 chars).
`priority`	int	No	`2`	Priority: 1 = Low, 2 = Medium, 3 = High, 4 = Urgent.
`due_date`	string	No	`null`	ISO 8601 date (`YYYY-MM-DD`).
`profile`	string	No	User profile	Profile ID of the card owner. Must be a valid profile from config.

Get a card¶

GET /api/cards/{id}

Returns the card with all fields and attached labels.

Update a card¶

PATCH /api/cards/{id}

All fields are optional. Only provided fields are updated.

Field	Type	Description
`title`	string	New title.
`description`	string	New description.
`priority`	int	New priority (1–4).
`due_date`	string	New due date (ISO 8601).
`profile`	string	New profile ID.
`agent_tokens_used`	int	Tokens consumed by the agent (optional, for agent completions).
`agent_model`	string	Model name used by the agent (optional, max 120 chars).
`agent_execution_time_seconds`	float	Agent execution time in seconds (optional).
`agent_started_at`	string	ISO 8601 datetime when the agent started work (optional).
`agent_completed_at`	string	ISO 8601 datetime when the agent finished (optional).

These agent metadata fields are designed for OpenClaw or other integrations to report completion details. When present on a card, HoneyDew displays an "Agent Completion" section in the task detail UI.

Move a card¶

POST /api/cards/{id}/move

Field	Type	Required	Default	Description
`column_id`	int	Yes	—	Target column ID.
`position`	int	No	`0`	Position within the target column (0-based).

Handles position reordering automatically within and across columns.

Move a card to another board¶

POST /api/cards/{id}/move-to-board

Field	Type	Required	Description
`board_id`	int	Yes	Target board ID.
`column_name`	string	No	Preferred column on the target board.

Target column resolution:

If column_name is provided and exists on the target board, it is used.
Otherwise, the card's current column name is matched on the target board.
If no match, the first column of the target board is used.

Transfer a card¶

POST /api/cards/{id}/transfer

Field	Type	Required	Description
`target_profile`	string	Yes	Profile ID to transfer the card to. Must be a valid profile from config.

Delete a card¶

DELETE /api/cards/{id}

Deletes the card and reorders remaining cards in the column. Returns 204 No Content.

Labels¶

List all labels¶

GET /api/labels

Create a label¶

POST /api/labels

Field	Type	Required	Default	Description
`name`	string	Yes	—	Label name (1–100 chars).
`color`	string	No	`#6366f1`	Hex color string (e.g. `#ff00aa`).

Add a label to a card¶

POST /api/cards/{card_id}/labels/{label_id}

Idempotent — adding an already-attached label is a no-op.

Remove a label from a card¶

DELETE /api/cards/{card_id}/labels/{label_id}

Returns 204 No Content.

Comments¶

List comments on a card¶

GET /api/cards/{card_id}/comments

Returns an array of comments for the card, ordered by created_at.

Add a comment to a card¶

POST /api/cards/{card_id}/comments

Field	Type	Required	Description
`body`	string	Yes	Comment text (1–5000 chars).
`profile`	string	No	Profile ID of the commenter. Defaults to the user profile from config.

Returns the created comment object:

{
  "id": 1,
  "card_id": 5,
  "profile": "tony",
  "body": "Looks good, moving to Done.",
  "created_at": "2026-02-22T14:30:00"
}

Priority Values¶

Value	Name	Description
1	Low	Low-priority work.
2	Medium	Default priority.
3	High	Important work that should be addressed soon.
4	Urgent	Critical work that needs immediate attention.

Card Response Shape¶

All card endpoints return a consistent object:

{
  "id": 1,
  "column_id": 2,
  "profile": "jarvis",
  "title": "Implement feature X",
  "description": "Details here",
  "priority": 3,
  "due_date": "2026-03-01",
  "position": 0,
  "created_at": "2026-02-22T10:30:00",
  "updated_at": "2026-02-22T11:45:00",
  "labels": [
    { "id": 1, "name": "frontend", "color": "#06b6d4" }
  ],
  "comments": [
    { "id": 1, "card_id": 1, "profile": "tony", "body": "Started working on this.", "created_at": "2026-02-22T12:00:00" }
  ],
  "agent_tokens_used": null,
  "agent_model": null,
  "agent_execution_time_seconds": null,
  "agent_started_at": null,
  "agent_completed_at": null
}

Error Responses¶

Errors return a JSON body with a detail field:

{
  "detail": "Card with id 99 not found"
}

Status	Meaning
400	Bad request (invalid profile, missing fields, board has no columns).
404	Resource not found.
422	Validation error (Pydantic).