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

Interactive spec: https://api.bundlist.app/docs

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_token_here

Tokens are issued after signing in with Google, Apple, or Facebook OAuth.

Lists

• GET /v1/lists — return all lists for the authenticated user
• POST /v1/lists — create a list; body: {"name": "...", "is_checklist": false}
• GET /v1/lists/{id} — get a single list by ID (includes a fields array)
• PATCH /v1/lists/{id} — update a list; body: {"name": "...", "is_checklist": true} (both optional)
• DELETE /v1/lists/{id} — delete a list and all its items and fields

Creating a list beyond your account limit returns 422 Unprocessable.

A checklist list (is_checklist: true) enables per-item checked state. The list detail response embeds the full fields array so a separate fields fetch is not required.

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 422 Unprocessable.

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); content is truncated to 100 characters and set to null for longer values — content_size always reflects the true length
• POST /v1/lists/{id}/items — create an item; body: {"name": "...", "content": "...", "checked": false, "field_values": {"<field_name>": "value"}}
• DELETE /v1/lists/{id}/items — bulk delete items; body: {"item_ids": ["id1", "id2"]}
• GET /v1/lists/{id}/items/{item_id} — get a single item (full content always returned)
• PATCH /v1/lists/{id}/items/{item_id} — update an item (merge semantics); body: {"name": "...", "content": "...", "checked": true, "field_values": {"<field_name>": "value"}}
• DELETE /v1/lists/{id}/items/{item_id} — delete an item

Adding an item beyond your list's limit returns 422 Unprocessable.

Every item response includes: id, name, content (string or null), content_size (integer or null), checked (boolean), field_values, created_at, updated_at.

Real-time events

The web and mobile clients receive live updates via Supabase Realtime (postgres_changes) — no polling required. Changes made by you, another session, or your AI assistant appear immediately.

If you are building your own client, subscribe directly to the Supabase Realtime channel for your user. The MCP server also sends notifications/resources/updated events so agents know when to re-fetch without polling.

Export

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

MCP server

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

Endpoint: https://api.bundlist.app/mcp (streamable HTTP transport)

For full documentation including available tools, authentication, and usage examples, see the MCP server page.

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
• 422 Unprocessable — validation error or usage limit reached; see detail for specifics
• 429 Too Many Requests — rate limit exceeded