LystBot v0.3.5

LystBot Documentation - REST API, MCP Server and CLI Reference

The list app your AI can actually use.

Quick Start

Four 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
AlexaHands-free voice control on Echo devices1 minute

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

Alexa

LystBot works with Alexa. The skill is a thin voice front-end: Alexa handles invocation and speech-to-text, then forwards the spoken command to the LystBot voice endpoint, which uses the same command layer as the API, MCP Server, and CLI.

Setup

  1. Enable the LystBot skill for Alexa.
  2. LystBot issues a pairing code. Say it to Alexa once.
  3. Talk to your lists: "Alexa, tell LystBot to add milk to my shopping list."

How the pairing works

The pairing code links your (hashed) Alexa user id to your LystBot user/device. That link is the only account association LystBot creates for Alexa.

Intent model

RawCommandIntent
  command : AMAZON.SearchQuery   # the free-form spoken command

  -> LystBot voice/command endpoint
  -> same command layer as API / MCP / CLI
What is processed. Amazon converts your speech to text; only the recognized command text is transmitted to LystBot, never audio recordings. LystBot processes that text together with the hashed Alexa user id to carry out the list action. See the Privacy Policy for the full data handling description.

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