Skip to content

api

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

api

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 

README.md

📡 LystBot API Reference

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

LystBot exposes the same list, category, and reminder data that powers the mobile app, CLI, and MCP server.

All requests and responses use Content-Type: application/json.

Authentication

Mobile App / Device Auth

Use the device UUID header:

X-Device-UUID: your-device-uuid

Agents, CLI, MCP, Automations

Use a Bearer API key:

Authorization: Bearer your-api-key

Agent Self-Management

PATCH /agents/me is Bearer-only. No device header is required.

Health

GET /health

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

Lists

GET /lists

Returns all lists the current device / agent can access.

curl https://lystbot.com/api/v1/lists \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "lists": [
    {
      "id": "list-uuid",
      "title": "Groceries",
      "type": "shopping",
      "emoji": "🛒",
      "is_shared": true,
      "share_code": "ABC123",
      "member_count": 2,
      "item_count": 5,
      "unchecked_count": 3,
      "updated_at": "2026-04-14T11:00:00Z"
    }
  ]
}

GET /lists/{id}

Returns the full list including members, bot members, categories, and items.

curl https://lystbot.com/api/v1/lists/LIST_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "id": "list-uuid",
  "title": "Groceries",
  "type": "shopping",
  "emoji": "🛒",
  "is_shared": true,
  "share_code": "ABC123",
  "hide_completed": false,
  "members": [
    {
      "device_uuid": "device-uuid",
      "name": "Alex",
      "display_name": "Alex",
      "label": "Alex",
      "signature_emoji": "🙂",
      "role": "owner"
    }
  ],
  "bot_members": [
    {
      "api_key_id": 12,
      "name": "TARS",
      "signature_emoji": "🤖"
    }
  ],
  "categories": [
    {
      "id": "cat-fruit",
      "name": "Fruits",
      "position": 0,
      "created_at": "2026-04-14T10:00:00Z",
      "updated_at": "2026-04-14T10:00:00Z"
    }
  ],
  "items": [
    {
      "id": "item-uuid",
      "category_id": "cat-fruit",
      "text": "Bananas",
      "checked": false,
      "quantity": 2,
      "unit": null,
      "position": 0,
      "created_by": "device-uuid",
      "created_by_api_key_id": 12,
      "updated_at": "2026-04-14T10:05:00Z"
    },
    {
      "id": "item-other",
      "category_id": null,
      "text": "Coffee",
      "checked": false,
      "quantity": 1,
      "unit": null,
      "position": 1,
      "created_by": "device-uuid",
      "created_by_api_key_id": null,
      "updated_at": "2026-04-14T10:06:00Z"
    }
  ],
  "updated_at": "2026-04-14T11:00:00Z"
}

POST /lists

Create a new list.

curl -X POST https://lystbot.com/api/v1/lists \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "new-list-uuid",
    "title": "Groceries",
    "type": "shopping",
    "emoji": "🛒"
  }'
{
  "id": "new-list-uuid",
  "created_at": "2026-04-14T11:05:00Z"
}

Valid list types: shopping, todo, packing, generic

PUT /lists/{id}

Update title, emoji, or hide_completed.

curl -X PUT https://lystbot.com/api/v1/lists/LIST_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Weekly Groceries", "emoji": "🛒", "hide_completed": false}'
{
  "success": true
}

DELETE /lists/{id}

Delete a list.

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

Items

POST /lists/{id}/items

Create an item. Supports categories via category_id.

curl -X POST https://lystbot.com/api/v1/lists/LIST_ID/items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "item-uuid",
    "text": "Bananas",
    "quantity": 2,
    "unit": null,
    "position": 0,
    "category_id": "cat-fruit"
  }'
{
  "id": "item-uuid"
}

Use "category_id": null or omit the field to place the item in Other / uncategorized.

PUT /lists/{id}/items/{itemId}

Update any of: text, checked, quantity, unit, position, category_id.

curl -X PUT https://lystbot.com/api/v1/lists/LIST_ID/items/ITEM_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "checked": true,
    "category_id": null
  }'
{
  "success": true,
  "updated_at": "2026-04-14T11:10:00Z"
}

DELETE /lists/{id}/items/{itemId}

curl -X DELETE https://lystbot.com/api/v1/lists/LIST_ID/items/ITEM_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "success": true
}

DELETE /lists/{id}/items/checked

Delete all checked items in a list.

curl -X DELETE https://lystbot.com/api/v1/lists/LIST_ID/items/checked \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "success": true,
  "deleted_count": 3
}

Categories

Categories let you structure a list into sections. Items without a category_id belong to Other / uncategorized.

POST /lists/{id}/categories

Create a category.

curl -X POST https://lystbot.com/api/v1/lists/LIST_ID/categories \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "cat-fruit",
    "name": "Fruits",
    "position": 0
  }'
{
  "id": "cat-fruit",
  "name": "Fruits",
  "position": 0,
  "created_at": "2026-04-14T10:00:00Z",
  "updated_at": "2026-04-14T10:00:00Z"
}

PUT /lists/{id}/categories/{categoryId}

Rename a category.

curl -X PUT https://lystbot.com/api/v1/lists/LIST_ID/categories/CATEGORY_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Fresh Fruits"}'
{
  "success": true,
  "id": "cat-fruit",
  "name": "Fresh Fruits",
  "position": 0,
  "created_at": "2026-04-14T10:00:00Z",
  "updated_at": "2026-04-14T10:12:00Z"
}

PUT /lists/{id}/categories/reorder

Reorder categories.

curl -X PUT https://lystbot.com/api/v1/lists/LIST_ID/categories/reorder \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order": [
      {"category_id": "cat-veg", "position": 0},
      {"category_id": "cat-fruit", "position": 1}
    ]
  }'
{
  "success": true
}

DELETE /lists/{id}/categories/{categoryId}

Delete a category. Its items are automatically moved to Other / uncategorized.

curl -X DELETE https://lystbot.com/api/v1/lists/LIST_ID/categories/CATEGORY_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "success": true,
  "id": "cat-fruit",
  "moved_count": 4
}

Sharing

POST /lists/{id}/share

Generate or return the existing share code.

curl -X POST https://lystbot.com/api/v1/lists/LIST_ID/share \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "share_code": "ABC123"
}

POST /lists/join

Join a shared list via invite code.

curl -X POST https://lystbot.com/api/v1/lists/join \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "ABC123"}'
{
  "list_id": "list-uuid",
  "title": "Groceries",
  "type": "shopping",
  "emoji": "🛒",
  "members": [
    {
      "device_uuid": "device-uuid",
      "name": "Alex",
      "signature_emoji": "🙂",
      "role": "owner"
    }
  ]
}

POST /lists/{id}/leave

Leave a shared list.

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

Reminders

Reminders can be managed by agents, the CLI, MCP server, and automations with the same Bearer API key auth shown above.

Fields:

  • id: reminder UUID
  • title: reminder text
  • scheduled_at: scheduled date/time string
  • timezone: IANA timezone, for example Europe/Berlin
  • repeat: none, daily, weekly, biweekly, monthly, yearly
  • is_enabled: whether the reminder is active

One-time reminders with "repeat": "none" cannot be created in the past.

GET /reminders

Returns all reminders for the current device / agent.

curl https://lystbot.com/api/v1/reminders \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "reminders": [
    {
      "id": "reminder-uuid",
      "title": "Take vitamins",
      "scheduled_at": "2026-05-08 09:00",
      "timezone": "Europe/Berlin",
      "repeat": "none",
      "is_enabled": true
    }
  ]
}

POST /reminders

Create a reminder.

curl -X POST https://lystbot.com/api/v1/reminders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "reminder-uuid",
    "title": "Take vitamins",
    "scheduled_at": "2026-05-08 09:00",
    "timezone": "Europe/Berlin",
    "repeat": "none",
    "is_enabled": true
  }'
{
  "reminder": {
    "id": "reminder-uuid",
    "title": "Take vitamins",
    "scheduled_at": "2026-05-08 09:00",
    "timezone": "Europe/Berlin",
    "repeat": "none",
    "is_enabled": true
  }
}

GET /reminders/{id}

Returns one reminder.

curl https://lystbot.com/api/v1/reminders/REMINDER_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "reminder": {
    "id": "reminder-uuid",
    "title": "Take vitamins",
    "scheduled_at": "2026-05-08 09:00",
    "timezone": "Europe/Berlin",
    "repeat": "none",
    "is_enabled": true
  }
}

PUT /reminders/{id}

Update any of: title, scheduled_at, timezone, repeat, is_enabled.

curl -X PUT https://lystbot.com/api/v1/reminders/REMINDER_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Take supplements",
    "scheduled_at": "2026-05-09 09:00",
    "timezone": "Europe/Berlin",
    "repeat": "daily",
    "is_enabled": true
  }'
{
  "reminder": {
    "id": "reminder-uuid",
    "title": "Take supplements",
    "scheduled_at": "2026-05-09 09:00",
    "timezone": "Europe/Berlin",
    "repeat": "daily",
    "is_enabled": true
  }
}

DELETE /reminders/{id}

Delete a reminder.

curl -X DELETE https://lystbot.com/api/v1/reminders/REMINDER_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "success": true
}

Favorites

GET /favorites

Optional filter: ?type=shopping

curl https://lystbot.com/api/v1/favorites?type=shopping \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "favorites": [
    {
      "id": "fav-uuid",
      "text": "Milk",
      "list_type": "shopping",
      "category": "Dairy",
      "use_count": 12,
      "updated_at": "2026-04-14T10:30:00Z"
    }
  ]
}

POST /favorites

curl -X POST https://lystbot.com/api/v1/favorites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "fav-uuid",
    "text": "Milk",
    "list_type": "shopping",
    "category": "Dairy"
  }'
{
  "id": "fav-uuid",
  "created_at": "2026-04-14T10:30:00Z"
}

PUT /favorites/{id}

curl -X PUT https://lystbot.com/api/v1/favorites/FAVORITE_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Oat Milk", "category": "Dairy"}'
{
  "success": true
}

DELETE /favorites/{id}

curl -X DELETE https://lystbot.com/api/v1/favorites/FAVORITE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "success": true
}

POST /favorites/{id}/use

Increment use_count for ranking.

curl -X POST https://lystbot.com/api/v1/favorites/FAVORITE_ID/use \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "use_count": 13
}

Agent Profile

PATCH /agents/me

Set the bot's display name and / or signature emoji.

curl -X PATCH https://lystbot.com/api/v1/agents/me \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "TARS", "signature_emoji": "🤖"}'
{
  "success": true,
  "name": "TARS",
  "signature_emoji": "🤖"
}

Errors

Errors use this shape:

{
  "error": "error_code",
  "message": "Human-readable description"
}

Common codes:

  • missing_fields
  • not_found
  • forbidden
  • invalid_api_key
  • invalid_code
  • already_member
  • invalid_category
  • invalid_type
  • conflict
  • max_items_reached

Notes

  • All list, item, category, and favorite IDs should be UUID v4
  • quantity is limited to 1..99
  • Items without category_id appear in Other / uncategorized
  • Deleting a category moves its items to Other / uncategorized
  • The CLI (npx lystbot) and built-in MCP server use these same endpoints