# bundlist API — Agent Guide

bundlist is a flexible list management SaaS with a REST API and MCP server.

## Base URL

`https://api.bundlist.app`

## Auth

All endpoints require `Authorization: Bearer <token>`.

- **JWT**: Supabase JWT from Google or Apple OAuth

## Key Endpoints

- `GET /v1/me` — user profile, tier, limits, usage
- `GET /v1/lists` — list all lists
- `POST /v1/lists` — create a list
- `GET /v1/lists/{id}/fields` — get schema (includes virtual name field)
- `GET /v1/lists/{id}/items` — list items (updated_at DESC)
- `GET /v1/export` — full data dump

## MCP

Connect to `https://api.bundlist.app/mcp` using the MCP streamable HTTP transport. Setup guides: [Claude.ai](https://bundlist.app/mcp/claude-web.html) · [Claude Code](https://bundlist.app/mcp/claude-code.html)

**Auth:** OAuth via browser. Connect without a token — the server returns a `WWW-Authenticate` header pointing to the OAuth discovery endpoint. Clients like Claude Desktop and Claude Code handle the browser prompt automatically.

**Tools:** `get_me`, `list_lists`, `get_list`, `get_lists`, `create_list`, `rename_list`, `delete_list`, `get_schema`, `delete_field`, `delete_item`, `merge_list`, `export_data`

- `merge_list` is the primary mutation tool for fields and items. Pass `fields` and/or `items` arrays; entries without an `id` are created, entries with an `id` are updated. Non-destructive — unmentioned rows are untouched.
- `get_list` accepts `include_items=true` to embed items in a single call.
- `get_lists` accepts a `list_ids` array for batch fetching.

**Resources:** `bundlist://guide` (this document), `bundlist://lists`, `bundlist://lists/{id}/items`, `bundlist://lists/{id}/fields`

**Notifications:** The server sends `notifications/resources/updated` whenever data changes. Subscribe by opening `GET /mcp` with a valid `Mcp-Session-Id`.

## List Naming

List names are used directly in voice interface commands across digital assistants
(`"What's on my [name] in bundlist"`). Keep names short and voice-friendly:

- **Prefer 1–3 word noun phrases**: "Business Ideas", "Wine Cellar", "Packing List"
- **Avoid prepositions and filler words**: not "Ideas to Incorporate into Projects" → "Project Ideas"
- **Avoid punctuation**: slashes, dashes, and parentheses don't translate to speech
- **Avoid app/project name prefixes**: not "Bundlist - Marketing" → "Marketing"
- **Avoid generic suffixes** unless they add meaning: "Notes", "Tracker", "Session", "(Demo Content)" are usually noise
- **"List" suffix**: only include it if the name would be ambiguous without it ("Grocery List" is fine; "Shopping List" already implies a list — no need to add "List" again)

When creating a list on behalf of a user, default to the shortest unambiguous noun phrase that captures the intent.

## Field Value Discipline

Fields fall into two categories — treat them differently:

**Categorization fields** (Category, Type, Status, Priority, Rating, Stage, Tier, and similar):
- Use short, consistent labels only — no parentheticals, no qualifying text
- Aim for 3–8 distinct values across all items in a list
- Bad: `Priority 1 — Now (MCP server live; connects via MCP not GPT)` → Good: `Priority 1`
- Bad: `LLM-driven (agent selects tool + params)` → Good: `LLM-driven`
- If you need to explain your reasoning, put it in a separate text field

**Text fields** (Notes, Description, URL, Summary, and similar):
- Free text, any length — this is where qualifications and context belong

When in doubt: if the field name could be a column header in a spreadsheet you'd want to filter or sort by, treat it as categorization.

## Real-time Events (Supabase Realtime)

The web and mobile clients subscribe **directly to Supabase Realtime** (`postgres_changes`) using the `@supabase/supabase-js` client. There is no SSE endpoint on the bundlist API.

Event shape: `{"type": "items"|"fields"|"lists", "list_id": "uuid", "action": "created"|"updated"|"deleted"}`

Clients subscribe to the `lists`, `items`, and `fields` tables filtered by `user_id`. Events are notifications only — refetch the affected resource via REST on receipt. MCP clients receive `notifications/resources/updated` via the MCP session stream instead.