# bundlist — Full LLM Reference

bundlist is a flexible list management app with a REST API and MCP server. Users create lists with custom field schemas, add items, and access everything from a web app, iOS/Android, or any AI assistant via MCP.

---

## What makes bundlist different

bundlist is built for AI-native use. Every list has a structured schema (user-defined fields), every item has field values, and the MCP server exposes the full read/write surface to any compatible AI assistant. A list can be created, populated, and updated entirely through conversation — no manual data entry required.

The MCP server is the primary interface for AI agents. The REST API is available for direct programmatic access.

---

## MCP Server

**URL:** https://api.bundlist.app/mcp
**Transport:** MCP streamable HTTP — POST /mcp for tool calls, GET /mcp for the SSE event stream
**Spec:** MCP 2025-03

**Auth:** OAuth 2.0 + PKCE. Connect without a token — the server returns a WWW-Authenticate header with a discovery URL. Clients like Claude Desktop, Claude Code, and ChatGPT handle the browser auth flow automatically via Dynamic Client Registration (RFC 7591). No manual API key setup.

### Tools

#### get_me
Returns the authenticated user's identity (user ID, email), subscription tier (free / basic / pro), usage limits, and current usage counts. Call this first when you need to know what the user can do before writing.

#### list_lists
Returns all of the user's lists with their names, IDs, field counts, and item counts. Use this to discover what lists exist before fetching items or deciding where to write.

#### get_list(list_id, include_items?)
Fetches a single list. Pass `include_items=true` to embed all items and their field values in one call — preferred when a list has fewer than ~200 items and you need both schema and data.

#### get_lists(list_ids[])
Batch version of get_list. Pass an array of list IDs to fetch multiple lists in a single round trip.

#### get_schema(list_id)
Returns the field definitions for a list: field IDs, names, and types. The virtual "name" field is always present on every item and does not have a field ID. Use this when you need field IDs for a merge_list call without fetching all items.

#### create_list(name, fields?)
Creates a new empty list. Optionally pass an initial `fields` array of `{name: string}` objects to set the schema at creation time. Returns the new list with its ID and field IDs.

#### rename_list(list_id, name)
Updates the display name of a list. All items and fields are preserved.

#### merge_list(list_id, fields?, items?)
The primary mutation tool. Creates or updates fields and items in a single call.

- `fields`: array of field objects. Without an `id`, a new field is created. With an `id`, the field is updated (rename supported).
- `items`: array of item objects. Without an `id`, a new item is created. With an `id`, the item is updated.
- **Merge semantics:** only keys you include are written. Omitting a field value on an existing item leaves the current value unchanged. Non-destructive — items and fields not mentioned are untouched.
- **Idempotent:** safe to call repeatedly with the same payload. Existing items matched by ID are updated, not duplicated.
- `field_values` keys in items are field names (strings), not field IDs.

Typical flow for populating a list from scratch:
1. `create_list` with initial fields → get list_id and field IDs
2. `merge_list` with items array referencing field names → populate items

#### delete_list(list_id)
Permanently deletes a list and all of its fields and items. Irreversible. Requires the list ID explicitly — no bulk deletion.

#### delete_field(list_id, field_id)
Permanently removes a field and all of its stored values from every item in the list. Irreversible.

#### delete_item(list_id, item_id)
Permanently removes a single item. Irreversible.

#### export_data
Returns a full JSON snapshot of all the user's lists, fields, and items. Useful for backup, migration, or analysis.

---

## REST API

**Base URL:** https://api.bundlist.app
**Auth:** Authorization: Bearer <token>
**Response shape:** `{"data": <payload>}` on success, `{"error": "<code>", "detail": "<message>"}` on error

```
GET    /v1/me
GET    /v1/lists
POST   /v1/lists                     body: {name}
GET    /v1/lists/{id}
PATCH  /v1/lists/{id}                body: {name}
DELETE /v1/lists/{id}
GET    /v1/lists/{id}/fields
POST   /v1/lists/{id}/fields         body: {name}
PATCH  /v1/lists/{id}/fields/{fid}   body: {name?, position?}
DELETE /v1/lists/{id}/fields/{fid}
GET    /v1/lists/{id}/items
POST   /v1/lists/{id}/items          body: {name, field_values: {field_name: value}}
GET    /v1/lists/{id}/items/{iid}
PATCH  /v1/lists/{id}/items/{iid}    body: {name?, field_values?}  (merge semantics)
DELETE /v1/lists/{id}/items/{iid}
GET    /v1/export
```

---

## Data model

- **User** has many **Lists**
- **List** has many **Fields** and many **Items**
- **Field** has a name and type (currently all fields are text; more types coming)
- **Item** has a name (always present, stored directly) and many **FieldValues** (one per field)
- **FieldValue** is a string, up to 500 characters
- The "name" field is virtual — it's stored on the item row, not as a field value, and has no field ID

---

## List naming conventions

List names appear in voice interface commands: "What's on my [name] in bundlist?" Keep them short and voice-friendly.

**Good:** "Business Ideas", "Wine Cellar", "Packing List", "Gift Ideas"
**Avoid:** prepositions, filler words, punctuation (slashes, dashes, parentheses), app-name prefixes ("Bundlist - Marketing" → "Marketing"), generic suffixes that add no meaning ("Notes", "Tracker")

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

---

## Field value discipline

### Categorization fields
Names like: Status, Priority, Category, Type, Rating, Stage, Tier, Phase

- Use short, consistent labels only — no parentheticals, no qualifying text
- Aim for 3–8 distinct values across all items in a list
- **Wrong:** `"Priority 1 — Now (MCP server live)"` → **Right:** `"Priority 1"`
- **Wrong:** `"LLM-driven (agent selects tool + params)"` → **Right:** `"LLM-driven"`
- If you need to explain your reasoning, put it in a separate Notes or Description field

### Text fields
Names like: Notes, Description, URL, Summary, Source, Details

- Free text, any length — this is where qualifications and context belong
- No length or format constraints; write what's useful

**Rule of thumb:** if the field name would be a column header in a spreadsheet you'd want to sort or filter by, treat it as categorization.

---

## Tiers

| Tier  | Lists | Fields/list | Items/list |
|-------|-------|-------------|------------|
| Free  | 10    | 5           | 100        |
| Basic | 25    | 10          | 250        |
| Pro   | 100   | 20          | 1000       |

Writes that would exceed a limit are skipped and reported in the tool response. Call `get_me` to check current usage before bulk writes.

---

## Real-time

- Web and mobile clients subscribe directly to **Supabase Realtime** (`postgres_changes`) for live updates
- MCP clients receive **`notifications/resources/updated`** events over the SSE stream when data changes
- Events are notifications only — re-fetch the affected resource via the appropriate tool on receipt

---

## Use cases

### Grocery + meal planning
Plan meals for the week with your AI assistant, then generate a grocery list in bundlist in one shot — organized by store section.

*Example prompt:* "Plan 5 weeknight dinners for a family of four, then create a grocery list in bundlist with ingredients grouped by section (produce, dairy, meat, pantry, frozen)."

Full guide: https://bundlist.app/uses/grocery.html

### Travel packing
Describe your trip and let the AI build a tailored packing list — categorized for your specific destination, duration, and activities.

*Example prompt:* "I'm taking two kids to the beach for a week in August. Create a packing list in bundlist with categories for clothes, gear, toiletries, and entertainment."

Full guide: https://bundlist.app/uses/packing.html

### Gift tracking
Keep a gift ideas list per person. Get AI-generated suggestions based on their interests and your budget, added directly to the list.

*Example prompt:* "My daughter turns 10 and loves art and animals. Add 5 gift ideas under $40 to her gift list in bundlist."

Full guide: https://bundlist.app/uses/gifts.html

### Watchlist
Track shows and movies, mark things watched, and get recommendations based on what's already on your list.

*Example prompt:* "I just finished Severance season 2. Mark it done in my watchlist and add 3 shows I'd probably enjoy based on what else is on the list."

Full guide: https://bundlist.app/uses/watchlist.html

### Fitness planning
Build a workout schedule around your goals, schedule, and equipment.

*Example prompt:* "I want to build strength, have 4 days a week, and a set of dumbbells at home. Create a workout schedule in bundlist with the day, muscle group, and exercises for each session."

Full guide: https://bundlist.app/uses/fitness.html

### AI preferences
Keep a list of how you like AI to behave — tone, formatting, things to avoid. Load it at the start of any session, across any AI surface.

*Example prompt:* "Fetch my AI rules list from bundlist and apply those rules to this session."

Full guide: https://bundlist.app/uses/ai-rules.html

---

## Support

- General: support@bundlist.app
- Privacy: privacy@bundlist.app
- Docs: https://bundlist.app/guide.html
- API reference: https://bundlist.app/api.html
- MCP overview: https://bundlist.app/mcp/