LystBot v0.3.5

LystBot Documentation - REST API, MCP Server and CLI Reference

The list app your AI can actually use.

Quick Start

Three ways to connect. Pick one:

MethodBest forSetup time
MCP ServerClaude Desktop, Cursor, Windsurf, Cline30 seconds
CLITerminal workflows, shell scripts, AI agents via exec1 minute
REST APICustom integrations, any language, webhooks2 minutes

Step 1: Install the LystBot app (iOS / Android)

Step 2: Go to Settings > AI Agents > Create API Key

Step 3: Pick your integration method below

REST API Reference

Base URL: https://lystbot.com/api/v1

Authentication

Two auth methods:

MethodHeaderUsed by
Bearer TokenAuthorization: Bearer YOUR_API_KEYAI agents, CLI, external integrations
Device UUIDX-Device-UUID: YOUR_UUIDMobile app

Get a Bearer token: install the app, go to Settings > AI Agents > Create API Key.

Endpoints Overview

MethodEndpointDescription
GET/api/v1/healthHealth check (no auth)
POST/api/v1/devices/registerRegister device (no auth)
PATCH/api/v1/devices/{uuid}Update device
GET/api/v1/devices/{uuid}/api-keyGet API key
GET/api/v1/listsGet all lists
POST/api/v1/listsCreate list
GET/api/v1/lists/{id}Get list with items
PUT/api/v1/lists/{id}Update list
DELETE/api/v1/lists/{id}Delete list
POST/api/v1/lists/{id}/itemsAdd item
PUT/api/v1/lists/{id}/items/{itemId}Update item
DELETE/api/v1/lists/{id}/items/{itemId}Delete item
POST/api/v1/lists/{id}/shareGenerate share code
POST/api/v1/lists/joinJoin shared list
POST/api/v1/lists/{id}/leaveLeave shared list
GET/api/v1/favoritesGet favorites
POST/api/v1/favoritesCreate favorite
PUT/api/v1/favorites/{id}Update favorite
DELETE/api/v1/favorites/{id}Delete favorite
POST/api/v1/favorites/{id}/useAdd favorite to list
PATCH/api/v1/agents/meUpdate agent profile

Health Check

GET /api/v1/health

No authentication required.

curl https://lystbot.com/api/v1/health
{
  "status": "ok"
}

Device Registration

POST /api/v1/devices/register

No authentication required. Registers a new device and returns a UUID.

curl -X POST https://lystbot.com/api/v1/devices/register \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent", "platform": "cli"}'
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Agent",
  "platform": "cli",
  "createdAt": "2026-03-13T09:00:00Z"
}

Get API Key

GET /api/v1/devices/{uuid}/api-key
curl https://lystbot.com/api/v1/devices/YOUR_UUID/api-key \
  -H "X-Device-UUID: YOUR_UUID"
{
  "apiKey": "lystbot_ak_xxxxxxxxxxxxxxxxxxxx"
}

Lists

Get All Lists

GET /api/v1/lists
curl https://lystbot.com/api/v1/lists \
  -H "Authorization: Bearer YOUR_API_KEY"
[
  {
    "id": 1,
    "name": "Groceries",
    "emoji": "🛒",
    "itemCount": 5,
    "checkedCount": 2,
    "shared": true,
    "createdAt": "2026-03-13T09:00:00Z",
    "updatedAt": "2026-03-13T10:30:00Z"
  }
]

Create List

POST /api/v1/lists
curl -X POST https://lystbot.com/api/v1/lists \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Groceries", "emoji": "🛒"}'
{
  "id": 1,
  "name": "Groceries",
  "emoji": "🛒",
  "itemCount": 0,
  "checkedCount": 0,
  "shared": false,
  "createdAt": "2026-03-13T09:00:00Z",
  "updatedAt": "2026-03-13T09:00:00Z"
}

Get Single List (with items)

GET /api/v1/lists/{id}
curl https://lystbot.com/api/v1/lists/1 \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "id": 1,
  "name": "Groceries",
  "emoji": "🛒",
  "items": [
    {
      "id": 1,
      "text": "Oat milk",
      "checked": false,
      "position": 0,
      "createdAt": "2026-03-13T09:00:00Z"
    },
    {
      "id": 2,
      "text": "Bananas",
      "checked": true,
      "position": 1,
      "createdAt": "2026-03-13T09:01:00Z"
    }
  ],
  "shared": true,
  "shareCode": "ABC123",
  "members": 2,
  "createdAt": "2026-03-13T09:00:00Z",
  "updatedAt": "2026-03-13T10:30:00Z"
}

Update List

PUT /api/v1/lists/{id}
curl -X PUT https://lystbot.com/api/v1/lists/1 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Weekly Groceries", "emoji": "🛒"}'

Delete List

DELETE /api/v1/lists/{id}
curl -X DELETE https://lystbot.com/api/v1/lists/1 \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns 204 No Content on success.

Items

Add Item to List

POST /api/v1/lists/{id}/items
curl -X POST https://lystbot.com/api/v1/lists/1/items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Coffee beans"}'
{
  "id": 3,
  "text": "Coffee beans",
  "checked": false,
  "position": 2,
  "createdAt": "2026-03-13T09:05:00Z"
}

Update Item (check/uncheck, edit text)

PUT /api/v1/lists/{id}/items/{itemId}
curl -X PUT https://lystbot.com/api/v1/lists/1/items/3 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Coffee beans (whole)", "checked": true}'

Delete Item

DELETE /api/v1/lists/{id}/items/{itemId}
curl -X DELETE https://lystbot.com/api/v1/lists/1/items/3 \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns 204 No Content on success.

Sharing

Generate Share Code

POST /api/v1/lists/{id}/share
curl -X POST https://lystbot.com/api/v1/lists/1/share \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "shareCode": "ABC123",
  "listId": 1,
  "listName": "Groceries"
}

Join a Shared List

POST /api/v1/lists/join
curl -X POST https://lystbot.com/api/v1/lists/join \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shareCode": "ABC123"}'
{
  "id": 1,
  "name": "Groceries",
  "emoji": "🛒",
  "itemCount": 5,
  "shared": true
}

Leave a Shared List

POST /api/v1/lists/{id}/leave
curl -X POST https://lystbot.com/api/v1/lists/1/leave \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns 204 No Content on success.

Favorites

Reusable item templates. "Milk" that you add to your grocery list every week.

Get All Favorites

GET /api/v1/favorites
curl https://lystbot.com/api/v1/favorites \
  -H "Authorization: Bearer YOUR_API_KEY"
[
  {
    "id": 1,
    "text": "Milk",
    "emoji": "🥛",
    "useCount": 12,
    "lastUsedAt": "2026-03-12T18:00:00Z"
  }
]

Create Favorite

POST /api/v1/favorites
curl -X POST https://lystbot.com/api/v1/favorites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Milk", "emoji": "🥛"}'

Use Favorite (add to list)

POST /api/v1/favorites/{id}/use
curl -X POST https://lystbot.com/api/v1/favorites/1/use \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listId": 1}'

Update / Delete Favorite

PUT /api/v1/favorites/{id}     # update
DELETE /api/v1/favorites/{id}  # delete (returns 204)

Agent Profile

PATCH /api/v1/agents/me
curl -X PATCH https://lystbot.com/api/v1/agents/me \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "TARS", "description": "Personal AI assistant"}'

MCP Server

The fastest way to connect your AI to LystBot. Works with any MCP-compatible client. Listed in the official MCP Registry.

Setup

  1. Install the LystBot app and copy your API key (Settings > AI Agents)
  2. Authenticate: 
    npx lystbot login YOUR_API_KEY
  3. Add to your MCP config:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "lystbot": {
      "command": "npx",
      "args": ["lystbot", "mcp"]
    }
  }
}

Cursor / Windsurf / Cline: Same config format, add to your editor's MCP settings.

OpenClaw:

openclaw mcp add lystbot -- npx lystbot mcp

Available Tools (10)

ToolParametersDescription
list_lists(none)Get all lists
get_listlist_id or nameGet a list with all items
create_listname, emoji (opt)Create a new list
delete_listlist_idDelete a list
add_itemslist_id, items[]Add one or more items
check_itemlist_id, item_id or textCheck off an item
uncheck_itemlist_id, item_id or textUncheck an item
remove_itemlist_id, item_id or textRemove item from list
share_listlist_idGenerate a share code
join_listshare_codeJoin a shared list

Supported Clients

CLI

Manage lists from your terminal. Works standalone or as a tool for AI agents.

Install

# Run directly (no install)
npx lystbot

# Or install globally
npm install -g lystbot

Authenticate

npx lystbot login YOUR_API_KEY

Credentials are stored in ~/.lystbot/config.json. You can also set LYSTBOT_API_KEY as env variable.

Commands

# Lists
npx lystbot lists                              # show all lists
npx lystbot create "Groceries" --category shopping
npx lystbot show "Groceries"                   # show items
npx lystbot delete "Groceries"

# Items
npx lystbot add "Groceries" "Milk" "Eggs" "Bread"
npx lystbot check "Groceries" "Milk"
npx lystbot uncheck "Groceries" "Milk"
npx lystbot remove "Groceries" "Milk"

# Sharing
npx lystbot share "Groceries"                  # get share code
npx lystbot join ABC123                        # join shared list

# JSON output (for piping / AI agents)
npx lystbot show "Groceries" --json | jq '.items'

# MCP Server mode
npx lystbot mcp

Options

FlagDescription
--jsonOutput as JSON
--api-urlOverride API base URL
--versionShow version
--helpShow help

Agent System Prompt

Copy this into your agent's system prompt or context file:

System Prompt Block

You have access to the user's LystBot lists.

## MCP (preferred)
If MCP is available, use these tools: list_lists, get_list, create_list,
delete_list, add_items, check_item, uncheck_item, remove_item, share_list, join_list.

## REST API (fallback)
Base URL: https://lystbot.com/api/v1
Auth: Authorization: Bearer API_KEY

Endpoints:
- GET    /lists              - List all lists
- POST   /lists              - Create list {"name": "...", "emoji": "..."}
- GET    /lists/:id          - Get list with items
- PUT    /lists/:id          - Update list
- DELETE /lists/:id          - Delete list
- POST   /lists/:id/items    - Add item {"text": "..."}
- PUT    /lists/:id/items/:itemId - Update item {"checked": true}
- DELETE /lists/:id/items/:itemId - Remove item
- POST   /lists/:id/share    - Get share code
- POST   /lists/join          - Join list {"shareCode": "..."}

## CLI
npx lystbot lists | show | add | check | uncheck | remove | share | join

When the user asks to add something to a list, do it.
When the user asks what's on a list, read it.
Always confirm what you did.

Errors & Rate Limits

All errors return JSON:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "List not found"
  }
}
CodeMeaning
400BAD_REQUEST - Invalid or missing parameters
401UNAUTHORIZED - Missing or invalid authentication
403FORBIDDEN - No access to this resource
404NOT_FOUND - Resource not found
409CONFLICT - Already exists (e.g. already joined)
422VALIDATION_ERROR - Invalid request body
429RATE_LIMITED - Slow down (Retry-After header included)
500INTERNAL_ERROR - Server error

Rate Limits

100 requests per minute per API key. 429 responses include a Retry-After header.

Tips for AI agents: Register once, reuse the token. Check items instead of deleting them (users want to see what was completed). Parse error codes, they're machine-readable.

© 2026 TourAround UG (haftungsbeschränkt) · Privacy · Imprint