README.md

Agent Backlog — API Server (Team Mode)

The optional central API server lets multiple developers share a single backlog.

By default each session uses a local SQLite database (.backlog.db in the project root). When BACKLOG_API_URL and BACKLOG_API_KEY are set, the MCP server connects to a central API server instead.

Developer A                Developer B                API Server
┌──────────────┐          ┌──────────────┐          ┌───────────────┐
│ MCP Server   │──HTTP──> │ MCP Server   │──HTTP──> │ api-server.js │
│              │          │              │          │               │
│ Kanban UI    │──proxy─> │ Kanban UI    │──proxy─> │ SQLite per    │
│ :3456        │          │ :3456        │          │ project       │
└──────────────┘          └──────────────┘          └───────────────┘

---

Setup

1. Start the server

node mcp/api-server.js serve
# Listening on http://0.0.0.0:4000

2. Create a project

node mcp/api-server.js create-project my-project
# Project "my-project" created.
# API Key: sk-proj-abc123...
# DB: ~/.config/agent-backlog-server/data/my-project.backlog.db

3. Configure clients

Set BACKLOG_API_URL and BACKLOG_API_KEY as environment variables on the MCP server process:

• Claude Code — see the Team Mode section in claude-code.md for system env vars or a per-user ~/.claude.json override
• Copilot CLI — see the Team Mode section in copilot-cli.md for system env vars

---

CLI Commands

Command	Description
serve	Start the HTTP server
create-project <slug>	Generate API key, initialize DB, print key
list-projects	Show all projects and DB status
delete-project <slug>	Remove project, API key, and DB

---

Configuration

See ../configuration.md for all environment variables.

Environment Variable	Default	Description
BACKLOG_API_PORT	4000	Port the server listens on
BACKLOG_API_DATA_DIR	~/.config/agent-backlog-server	Directory for per-project SQLite databases

---

Endpoints

• Items — list, get, create, update
• Search — keyword search
• Checklist — add, update, delete checklist items
• Comments — append comments
• Dependencies — add/remove dependency edges
• Events — SSE live updates
• Projects — admin project listing
• Health — health check

---

Authentication

All endpoints except GET /api/health and GET /api/projects require:

Authorization: Bearer sk-proj-<key>

The key identifies the project — no separate project ID is needed in the URL.

---

Error responses

Status	Meaning
400	Validation error — { "error": "field: message" }
401	Missing or invalid API key
404	Item not found
409	Version conflict — re-fetch and retry