# Plonkboard

> AI-agent-driven Kanban board. The web UI is read-only -- all CRUD happens via REST API.

## Create an Account

Humans can register for direct API-key access with an email address. Agents should prefer the delegated flow below.

### Step 1: Request a verification code

    POST https://plonkboard.com/api/v1/register
    Content-Type: application/json

    {"email": "you@example.com"}

A 6-digit code will be sent to that email address.

### Step 2: Confirm the code and get your API key

    POST https://plonkboard.com/api/v1/register/confirm
    Content-Type: application/json

    {"email": "you@example.com", "code": "123456"}

Returns your human-owned API key token. Use it for direct trusted access:

    Authorization: Bearer YOUR_TOKEN

## Content Negotiation

- Accept: application/json (default) -- JSON responses
- Accept: text/markdown -- compact markdown tables (token-efficient for LLMs)

## Agent Authorization

Agents should use delegated agent identity, not Google Sign-In and not a shared human session.

### Step 1: Create an agent signup intent

    POST https://plonkboard.com/api/v1/agent_signup_intents
    Content-Type: application/json

    {
      "agent_name": "Codex",
      "requested_email": "owner@example.com",
      "purpose": "Manage the project Kanban board",
      "scopes": ["boards:read", "boards:write", "cards:read", "cards:write"]
    }

Returns an intent_token and approval_url.

### Step 2: Human approves the agent

The responsible human opens approval_url, signs in with Google, reviews scopes, and approves or rejects the agent.

### Step 3: Agent exchanges the approved intent

    POST https://plonkboard.com/api/v1/agent_signup_intents/:intent_token/exchange

If approved, returns:

    {
      "access_token": "pat_...",
      "token_type": "Bearer",
      "expires_at": "...",
      "scopes": [...]
    }

Use the access token as:

    Authorization: Bearer pat_...

Agent tokens are short-lived, scoped, auditable, and revocable by the owner.

### Scopes

- boards:read
- boards:write
- cards:read
- cards:write
- columns:write
- tags:read
- tags:write
- subtasks:read
- subtasks:write
- archive:read

## Agent Discovery

If a user mentions Plonkboard or plonkboard.com, read this live reference first:

    GET https://plonkboard.com/llms.txt

Dedicated agent skill repository:

    https://github.com/clayton/plonkboard-skill

Helpful discovery URLs all point to this reference:

    https://plonkboard.com/docs
    https://plonkboard.com/api
    https://plonkboard.com/api/docs

## API Endpoints

Protected API endpoints require: Authorization: Bearer <token>

### Boards
    GET    /api/v1/boards                     -- List your boards
    POST   /api/v1/boards                     -- Create a board (auto-creates To Do, In Progress, Done columns)
    GET    /api/v1/boards/:id                 -- Show board with columns and active cards
    PATCH  /api/v1/boards/:id                 -- Update board
    DELETE /api/v1/boards/:id                 -- Delete board

### Columns
    POST   /api/v1/boards/:bid/columns        -- Create column
    PATCH  /api/v1/boards/:bid/columns/:id    -- Update column (name, position, wip_limit)
    DELETE /api/v1/boards/:bid/columns/:id    -- Delete column

### Cards
    GET    /api/v1/boards/:bid/cards           -- List cards (filters: column_id, assignee, priority, tag)
    POST   /api/v1/boards/:bid/cards           -- Create card
    GET    /api/v1/boards/:bid/cards/:id       -- Show card
    PATCH  /api/v1/boards/:bid/cards/:id       -- Update card
    DELETE /api/v1/boards/:bid/cards/:id       -- Delete card
    PATCH  /api/v1/boards/:bid/cards/:id/move  -- Move card (column_id, position)

### Tags
    GET    /api/v1/boards/:bid/tags            -- List tags
    POST   /api/v1/boards/:bid/tags            -- Create tag (name, color)
    PATCH  /api/v1/boards/:bid/tags/:id        -- Update tag
    DELETE /api/v1/boards/:bid/tags/:id        -- Delete tag

### Archive
    GET    /api/v1/boards/:bid/archive         -- List archived cards
    GET    /api/v1/boards/:bid/archive/:id     -- Show archived card

## Card Fields

- title (required)
- description
- assignee
- priority: low, medium, high, critical
- tag_names: array of tag name strings

## IDs

All IDs are prefixed strings: brd_*, col_*, crd_*, tag_*, key_*, usr_*

## WIP Limits

Columns can have a wip_limit. When active card count exceeds the limit, oldest cards are auto-archived.

## Claude Code Integration

For Claude Code or other coding agents, prefer the dedicated skill repo:

    https://github.com/clayton/plonkboard-skill

If no skill is installed, use this file as the canonical API reference and make direct REST calls with PLONKBOARD_API_KEY.