# bundlist API

> A flexible list management SaaS. Create lists with custom schemas, add items, manage fields.

## API Reference

Base URL: https://api.bundlist.app

Auth: Bearer token (Supabase JWT from Google, Apple, or Facebook OAuth, or `bndl_` API key)

## Endpoints

- GET /v1/me — current user profile + tier + limits
- GET /v1/lists — all lists
- POST /v1/lists — create list (body: {name: string, is_checklist?: boolean})
- GET /v1/lists/{id} — get list (includes fields array)
- PATCH /v1/lists/{id} — update list (body: {name?: string, is_checklist?: boolean})
- DELETE /v1/lists/{id} — delete
- GET /v1/lists/{id}/fields — schema (virtual name field + stored fields)
- POST /v1/lists/{id}/fields — add field (body: {name: string})
- PATCH /v1/lists/{id}/fields/{fid} — rename/reorder field
- DELETE /v1/lists/{id}/fields/{fid} — delete field
- GET /v1/lists/{id}/items — items (updated_at desc); content truncated to 100 chars, content_size always present
- POST /v1/lists/{id}/items — create item (body: {name: string, content?: string, checked?: boolean, field_values: {}})
- DELETE /v1/lists/{id}/items — bulk delete (body: {item_ids: string[]})
- GET /v1/lists/{id}/items/{iid} — get item (full content always returned)
- PATCH /v1/lists/{id}/items/{iid} — update item (merge semantics; body: {name?: string, content?: string, checked?: boolean, field_values?: {}})
- DELETE /v1/lists/{id}/items/{iid} — delete item
- GET /v1/export — full dump
- POST /v1/auth/api-keys — create API key
- GET /v1/auth/api-keys — list keys
- DELETE /v1/auth/api-keys/{id} — revoke key

## Item fields

Every item has: id, name, content (string|null), content_size (int|null), checked (bool), field_values (dict), created_at, updated_at.
In list responses, content is set to null when it exceeds 100 characters; content_size always reflects the true length. Use GET /v1/lists/{id}/items/{iid} to retrieve the full content.

## MCP Server

Connect AI agents directly via MCP at `https://api.bundlist.app/mcp`.

Transport: MCP streamable HTTP — `POST /mcp` for tool calls, `GET /mcp` for live update stream.

Auth: `Authorization: Bearer bndl_<api-key>` (create via `POST /v1/auth/api-keys`).
Interactive clients (Claude Desktop, Claude Code) can authenticate via OAuth — connect without a token and follow browser prompts.

Tools: get_me, list_lists, get_list, get_lists, create_list, rename_list, delete_list, get_schema, delete_field, delete_item, merge_list, reset_checklist, clear_checked, get_item_content, export_data

Resources: bundlist://guide, bundlist://lists, bundlist://lists/{id}/items, bundlist://lists/{id}/fields

Real-time: clients receive notifications/resources/updated when data changes.

## Response Shape

Success: {"data": <payload>}
Error: {"error": "<code>", "detail": "<message>"}