# 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 setup

For a signed-in owner, the simplest setup is:

1. Open https://plonkboard.com/settings/api_keys
2. Click "copy setup prompt for my agent"
3. Paste the prompt into the agent

The prompt contains a one-time token that expires after 10 minutes and returns an API key once. Never print or commit the returned key.

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

    {"token": "boot_..."}

## Delegated agent authorization

Use the approval flow below when an agent needs scoped, short-lived, auditable access.

### 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 Skill

This file is the live Plonkboard skill and canonical API reference. If a user mentions Plonkboard or plonkboard.com, fetch and follow it first:

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

Helpful discovery URLs all point to this skill:

    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.

## Coding Agent Integration

Claude Code, Codex, Cursor, and other coding agents should use this file directly and make REST calls with PLONKBOARD_API_KEY.