API Reference

REST API and MCP server for developers and AI integrations

Overview

The bundlist API is a standard JSON REST API. All endpoints require authentication. The base URL is:

https://api.bundlist.app/v1

All request and response bodies are application/json. Errors follow a consistent shape: {"detail": "human-readable message"}.

Authentication

Pass a Bearer token in the Authorization header on every request:

Authorization: Bearer your_api_key_here

You can use:

• An API key generated from the Settings panel in the app — recommended for scripts and AI integrations
• A session token issued after signing in with Google — used internally by the web app

API keys are shown once at creation. If you lose one, revoke it from Settings and generate a new one.

Lists

• GET /v1/lists — return all lists for the authenticated user
• POST /v1/lists — create a list; body: {"name": "..."}
• GET /v1/lists/{id} — get a single list by ID
• PATCH /v1/lists/{id} — rename a list; body: {"name": "..."}
• DELETE /v1/lists/{id} — delete a list and all its items and fields

Creating a list beyond your account limit returns 409 Conflict.

Fields

Fields define the schema for items in a list. Every list starts with a built-in name field that cannot be removed.

• GET /v1/lists/{id}/fields — list all fields for a list
• POST /v1/lists/{id}/fields — add a field; body: {"name": "..."}
• PATCH /v1/lists/{id}/fields/{field_id} — rename or reorder a field; body: {"name": "...", "position": 0} (both optional)
• DELETE /v1/lists/{id}/fields/{field_id} — remove a field and its data from all items

All fields are text. Adding a field beyond your list's limit returns 409 Conflict.

Items

Items are the rows in a list. Each item's shape is determined by the list's fields.

• GET /v1/lists/{id}/items — list all items in a list (newest first)
• POST /v1/lists/{id}/items — create an item; body: {"name": "...", "field_values": {"<field_id>": "value"}}
• GET /v1/lists/{id}/items/{item_id} — get a single item
• PATCH /v1/lists/{id}/items/{item_id} — update an item (merge semantics); body: {"name": "...", "field_values": {"<field_id>": "value"}}
• DELETE /v1/lists/{id}/items/{item_id} — delete an item

Adding an item beyond your list's limit returns 409 Conflict.

Real-time events

GET /v1/events — open a Server-Sent Events stream of change notifications for the authenticated user.

Each event has the shape:

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

Events are notifications only — your client should refetch the affected resource via the normal REST endpoints when an event arrives. The stream sends a heartbeat ping every 15 seconds to keep the connection alive through proxies and load balancers.

Connect using the browser's EventSource API or any SSE-compatible HTTP client with a valid Bearer token.

Export

GET /v1/export — download a full JSON dump of all your lists, fields, and items in one request.

API keys

• POST /v1/auth/api-keys — create an API key; body: {"label": "optional label"} — the key value is returned once and not stored
• GET /v1/auth/api-keys — list all keys (labels and IDs only; values are never returned after creation)
• DELETE /v1/auth/api-keys/{key_id} — revoke a key immediately

MCP server

bundlist includes a built-in Model Context Protocol (MCP) server so AI assistants like Claude can read and update your lists without you copy-pasting anything.

Connect your MCP client to https://api.bundlist.app/mcp using the streamable HTTP transport.

Authentication — two options:

• API key (recommended for scripts): Generate a key from the Settings panel and pass it as Authorization: Bearer bndl_<key> on every request.
• OAuth (recommended for Claude Desktop / Claude Code): Connect without a token. The server returns a WWW-Authenticate header pointing to the OAuth discovery endpoint. Your client will open a browser window for Google sign-in and handle the rest automatically — no manual key setup needed.

Tools: list_lists, get_list, create_list, rename_list, delete_list, get_schema, add_field, delete_field, list_items, get_item, create_item, update_item, delete_item, export_data.

Real-time notifications: The MCP server sends notifications/resources/updated events whenever your data changes, so agents always know when to re-fetch without polling.

Rate limits

All endpoints are rate-limited. Exceeding the limit returns 429 Too Many Requests with standard rate-limit headers indicating when you can retry.

Common status codes

• 200 OK — success
• 201 Created — resource created
• 400 Bad Request — malformed body or invalid field value
• 401 Unauthorized — missing or invalid token
• 403 Forbidden — valid token but insufficient permission
• 404 Not Found — resource doesn't exist or belongs to another user
• 409 Conflict — usage limit reached (lists, items, or fields cap)
• 422 Unprocessable — validation error (see detail for specifics)
• 429 Too Many Requests — rate limit exceeded