# BadBoard

> Kanban board with a full programmatic API for scripts, services, and AI agents.
> Everything the web UI can do with boards, lists, cards, and labels is available
> over REST and MCP.

## Authentication

Both surfaces use Personal Access Tokens (`pat_...`). A signed-in user creates
one in Settings → API Tokens at https://saas.nopped.art/dashboard/boards?settings=api-tokens
(no API endpoint for token creation).
Send it on every request:

    Authorization: Bearer pat_...

Tokens carry the full access of the issuing user's team. Rate limit: 240
requests/minute per token (429 + Retry-After when exceeded).

## REST API

- Base URL: https://saas.nopped.art/api/v1
- OpenAPI spec (machine-readable, no auth): https://saas.nopped.art/api/v1/openapi.json
- Swagger UI (no auth): https://saas.nopped.art/api/v1/docs

Resources: boards, lists (columns, with parking/active/done zones), cards,
labels, card comments, card activity, card reminders, team activity log,
cross-board card search. Errors use
`{ "error": { "code", "message", "details?" } }`.

Quick start:

    curl -H "Authorization: Bearer pat_..." https://saas.nopped.art/api/v1/boards

Tips for agents:
- Card responses include a `url` field — a shareable web link that opens the
  card in the web UI. Use it whenever you show a card to a human.
- `GET /api/v1/boards/:id?detail=summary` returns lists with card counts
  instead of full card bodies — use it on large boards.
- `GET /api/v1/lists/:listId/cards?limit=&offset=` pages through one column.
- `GET /api/v1/activity` answers "what changed recently?".
- `GET|POST /api/v1/cards/:cardId/comments` reads/writes card comments;
  `PATCH|DELETE /api/v1/comments/:commentId` edits/deletes your own.

## MCP server

Streamable HTTP (stateless) endpoint: https://saas.nopped.art/api/mcp
Auth: the same `Authorization: Bearer pat_...` header.

Tools: list_boards, get_board, create_board, update_board, delete_board,
move_board, list_lists, create_list, update_list, update_list_zone,
delete_list, move_list, list_cards, get_card, create_card, update_card,
move_card, delete_card, list_labels, create_label, update_label,
delete_label, toggle_card_label, get_card_activity, list_card_reminders,
list_card_comments, add_card_comment, update_card_comment,
delete_card_comment, list_team_activity, search_cards.

### Claude Code

    claude mcp add --transport http badboard https://saas.nopped.art/api/mcp \
      --header "Authorization: Bearer pat_..."

### Claude Desktop (claude_desktop_config.json)

    {
      "mcpServers": {
        "badboard": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://saas.nopped.art/api/mcp",
                   "--header", "Authorization:${AUTH_HEADER}"],
          "env": { "AUTH_HEADER": "Bearer pat_..." }
        }
      }
    }

### Codex CLI

    codex mcp add badboard -- npx -y mcp-remote https://saas.nopped.art/api/mcp \
      --header "Authorization: Bearer pat_..."

### Anything else

Any MCP client that speaks Streamable HTTP with custom headers can connect
directly to https://saas.nopped.art/api/mcp. Clients without header support can bridge via
`npx mcp-remote`. Agents without MCP should use the REST API and bootstrap
from the OpenAPI spec.