LystBot

Grocery list API: automate shared lists with LystBot

The LystBot grocery list API lets scripts read shared shopping lists and add or check individual items over HTTP. Start with curl https://lystbot.com/api/v1/lists -H "Authorization: Bearer YOUR_API_KEY"; writes use JSON and new records need client-generated UUID v4 IDs.

Request Payload requirement Purpose
GET /lists No body Find your list ID
POST /lists UUID v4 id and title Create a shopping list
POST /lists/:id/items UUID v4 id and text Add one grocery item
PUT /lists/:id/items/:itemId {"checked": true} Check off an item

See the LystBot agent setup for the full reference. Related guides: REST setup for todo lists, CLI commands for shopping lists.

LystBot REST API for automating grocery and todo lists

First shopping list API requests

  1. Copy your API key from Settings, then AI Agents.
  2. Read your lists with GET /lists before selecting a target.
  3. Create a list with POST /lists or add one item with POST /lists/:id/items.

Use the Bearer header on each request. Replace UUID placeholders with client-generated UUID v4 values; a title or an array of item names alone is not a valid create payload.

Why a programmable list app beats a regular list app

Think about when you actually add items to a grocery list. You're cooking and realize you're out of cumin. You're reading a recipe and need six ingredients. Your smart home detects the washing machine finished. You're in Slack and someone mentions needing printer paper for the office.

None of these moments happen inside a list app. They happen everywhere else. An API lets you capture items where the thought occurs instead of forcing you to context-switch, open an app, type it in, and lose your train of thought.

Three uses for a list automation API:

A recipe parser scrapes ingredients from a URL and dumps them straight into your shared grocery list. Your partner sees the items appear on their phone before you've even closed the browser tab.

A smart home trigger fires when your Philips Hue motion sensor hasn't detected movement in the pantry for a while, or when your smart plug detects the washing machine stopped. It adds "hang laundry" to your todo list automatically.

A Slack bot lets your whole team manage an office supply list without anyone downloading yet another app.

Shopping list API: core endpoints

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

You authenticate with a Bearer token. Grab your API key from the app settings (more on that below). Every request needs this header:

Authorization: Bearer YOUR_API_KEY

Here are the endpoints you'll use most.

Create a 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": "🛒"}'

Response:

{
  "id": "NEW_LIST_UUID",
  "created_at": "2026-04-14T11:05:00Z"
}

List types are shopping, todo, packing, and generic. Pick whichever fits.

Add items

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": "NEW_ITEM_UUID", "text": "Flour", "quantity": 1, "unit": "500g"}'

REST adds one item per request. Replace NEW_ITEM_UUID with a UUID v4. Use quantity for a count from 1 to 99 and unit for weight or volume. For comma-separated items and parsed amounts, use the CLI or MCP add_items.

Check off an item

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}'

Generate a share code

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

Returns a 6-character code anyone can use to join the list. No account creation needed on their end.

Terminal showing LystBot API response with curl

The full endpoint reference is in the LystBot docs. There are also endpoints for updating lists, deleting items, clearing checked items, and managing your profile. Choose endpoints based on the operation your automation needs.

Want to try it right now? Download LystBot, go to Settings, copy your API key, and run the curl commands above. Read the resulting list to verify the request.

Smart grocery list API workflows

This is the part I actually care about. The API is just plumbing. What matters is what you build on top.

The following are workflow ideas, rather than bundled integrations. Build and test the trigger separately, then use the documented LystBot request shape for each write.

1. Recipe to grocery list (Zapier or n8n)

The idea: You star a recipe in Pocket (or Instapaper, or save a bookmark). An automation parses the ingredients and adds them to your shared grocery list.

In n8n, the flow looks like this:

  1. Trigger: A saved recipe URL
  2. HTTP Request: Fetch the recipe page
  3. AI node: Extract ingredient list from the HTML (GPT or Claude work fine here)
  4. HTTP Request: POST one item at a time to https://lystbot.com/api/v1/lists/YOUR_LIST_ID/items, with a UUID v4 id and text for each ingredient

Each REST item write needs its own ID and text. Read the list after the workflow runs to confirm the ingredients and quantities.

For another automation service, check whether it can send the documented authenticated JSON request. This guide does not establish a built-in LystBot connector.

2. Weekly grocery list from a template (cron job)

The idea: Every Sunday morning, a script creates a fresh grocery list pre-filled with your staples.

#!/bin/bash
set -e
# Log in once with npx lystbot login YOUR_API_KEY before scheduling.
LIST_NAME="Groceries $(date +'%b %d')"
npx lystbot create "$LIST_NAME" --type shopping
npx lystbot add "$LIST_NAME" "Milk, Eggs, Bread"

Drop this in a crontab (0 8 * * 0 for Sundays at 8am) and you've got a way to automate your shopping list every week. You wake up, your grocery list is already started. Add whatever else you need during the week.

You could keep the template items in a JSON file and read from that, so editing your staples doesn't mean editing the script.

3. Slack bot for shared lists

The idea: Type /groceries add milk, eggs, bread in Slack and the items appear on your shared list.

A custom slash-command handler would parse the submitted text and send one authenticated item request for each entry. The LystBot side uses the same documented shape:

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": "NEW_ITEM_UUID", "text": "Flour", "quantity": 1, "unit": "500g"}'

This is the API request, not a complete Slack handler. Supply a fresh UUID v4 for each item and check the HTTP response before reporting that it was saved. No built-in Slack connector is established by this example.

4. Home Assistant automation

The idea: When the washing machine finishes (detected by a smart plug's power dropping below 5W), add "hang laundry" to your todo list.

A custom Home Assistant REST command can send a request to the item endpoint. Configure the trigger for your own sensor and supply a fresh UUID v4 for each new item. The documented LystBot payload is:

{"id": "NEW_ITEM_UUID", "text": "Flour", "quantity": 1, "unit": "500g"}

Replace the example text and amount for the task you want to save. Read the list after a test event and check the HTTP response before relying on an unattended job.

Production tips for your todo app REST API setup

If you're running automations that fire unattended, a few things to keep in mind.

Error handling. The API returns standard HTTP status codes. 200 for success, 404 if a list or item doesn't exist, 401 if your key is wrong. Wrap your curl calls in a check for non-2xx responses before moving on. In bash, curl -f exits with a non-zero code on HTTP errors.

Retries. Read the list after an uncertain write before sending another request. Do not create a new item ID for a retry without first checking whether the intended item already exists.

Credentials. Keep the API key out of version-controlled files and public examples. Use an environment variable or your existing secrets storage for unattended jobs.

Item limits. A list holds up to 300 items. Read the current list and check response codes instead of assuming every add succeeded.

Authentication

Copy the API key from the mobile app.

  1. Open LystBot
  2. Go to Settings
  3. Open AI Agents and copy the API key
LystBot settings screen showing the API key

Send it as a Bearer token in every request:

Authorization: Bearer YOUR_API_KEY

Use the same API key for REST, the CLI and MCP. If you're building something for other people, each user gets their own key from their own app.

Beyond the API: CLI and MCP server

The REST API is one way in. There are two more.

CLI: Run npx lystbot and you have a terminal client. Authenticate first with npx lystbot login YOUR_API_KEY. We wrote about this in the feature overview post.

npx lystbot lists
npx lystbot add "Groceries" "Tomatoes, Basil, Mozzarella"

Pipe output to jq, feed it to scripts, use it in CI/CD if that's your thing.

MCP Server: If you use Claude Desktop, Cursor, or any MCP-compatible AI tool, LystBot has an MCP server that lets your AI assistant manage your lists directly. "Add the ingredients for pad thai to my grocery list" just works. We covered 10 MCP workflow examples if you want ideas for what else to connect.

The three interfaces (API, CLI, MCP) all talk to the same backend. Items added via curl show up in the app instantly. Items checked off in the app retain their checked state when read through the CLI. Everything syncs.

Go build something

LystBot is free during launch. REST, CLI and MCP use the same API key.

  1. Download LystBot (App Store / Google Play)
  2. Grab your API key from Settings
  3. Run that first curl command. Create a list, add an item, see it appear on your phone.

Then pick one of the automations above and make it yours. The API docs have the full endpoint reference. If you build something cool, we want to hear about it.

FAQ

Can REST add an array of grocery names?

The documented REST item endpoint takes one item with id and text. For several ingredients, send individual requests with separate UUID v4 IDs, or use CLI comma-separated input or MCP add_items.

What is the item limit?

A list holds up to 300 items. The documented error for reaching that limit is max_items_reached with HTTP status 422.

Where do I get the API key?

Copy it from Settings, then AI Agents in the LystBot app. Send it as Authorization: Bearer YOUR_API_KEY on list requests.