# Lists by OpenApps

> Free shared grocery and to-do lists that update live for everyone in the house. A free alternative to AnyList, OurGroceries and Bring!: no ads, no sign-up, no paid tier. Lists are shared by link; items sort by store aisle on their own; it works offline in the store and syncs later. AI and voice assistants can make lists, add items, check them off and read a list back through the API below.

Web app: https://lists-free.openapps.xyz/
Plain markdown version of the page: https://lists-free.openapps.xyz/index.md
OpenAPI description: https://lists-free.openapps.xyz/openapi.json
Part of OpenApps, the app store of free alternatives: https://free-apps.openapps.xyz/

## API

Base URL: https://functions.bounded.sh/apps/ee59501e91bae6d2c23a8370/api

JSON in, JSON out. CORS is open. Errors answer {"error": "<sentence that says what to change>"} with a 4xx status.

Making a list needs no key. Everything else needs the list key in a header:

    x-list-key: <list key>

A list key is 44 letters and digits. The API hands it back when it makes a list; for a list a person made in the app, they copy it from the list's Share screen, under "For assistants". It works like the share link: anyone with it can read and change the list, so keep it private. If a key stops working (403), the list's owner changed the link; ask the person for the current key.

### Make a list (no key)

POST /lists
{"name": "Groceries", "items": ["milk and eggs", "2 lb chicken", "bananas"]}

- name: up to 60 characters; defaults to "Groceries".
- kind: "grocery" (items group by store section) or "todo" (items keep the order they were added). Defaults to grocery, or todo when the name starts with "To do" or "Packing".
- items: optional, same shapes as adding items below.

Returns 201 with:
- key: the list key, for every later call.
- shareUrl: give this to the person. Opening it puts them (and anyone they send it to) on the list, live, with no sign-up.
- adminUrl: give this only to the person who owns the list. It lets them remove people, change the link and delete the list from any device.
- the list itself, as in GET /list.

### Read a list

GET /list   (x-list-key)

Returns:
- list: {id, name, kind, url}
- toGet: unchecked items in store order (grocery) or in the order added (todo). Each item: {id, name, quantity, note, section, sectionName, checked}.
- checkedOff: checked items, most recent first.
- say: one sentence to read out, like "Groceries has 3 items to get: 2 lb chicken, eggs, milk."

### Add items

POST /list/items   (x-list-key)
{"text": "milk and eggs, 2 lb chicken"}
or
{"items": ["milk", "2 lb chicken", {"name": "coffee", "quantity": "1 bag", "note": "decaf", "section": "drinks"}]}

- text is split on commas, new lines and "and" ("mac and cheese" and "half and half" stay whole).
- A leading amount becomes the quantity: "2 lb chicken", "a dozen eggs", "two cartons of milk", "eggs x2".
- section is optional; without it, Lists uses the section the household chose before, or its built-in grocery dictionary. Sections: produce, bakery, deli, meat, dairy, frozen, pantry, baking, breakfast, snacks, drinks, household, personal, baby, pets, other.
- An item already on the list is not added twice (it is listed in alreadyOnList). A checked-off item comes back unchecked.
- Up to 50 items per call.

Returns 201 with added, alreadyOnList, and the list as in GET /list (200 when everything was already on the list). Read back what was added so the person can catch a mistake.

### Check off, edit or remove an item

PATCH /list/items/<item>   (x-list-key)
{"checked": true}

<item> is the item's id or its name ("milk", or "olive%20oil" in a URL). Any of: checked (true or false), name, quantity, note, section. Changing the section also teaches the list where that item goes next time.

DELETE /list/items/<item>   (x-list-key)

POST /list/clear-checked   (x-list-key)   removes everything checked off.

GET / lists the routes.

## Examples

    curl -X POST https://functions.bounded.sh/apps/ee59501e91bae6d2c23a8370/api/lists \
      -H 'content-type: application/json' \
      -d '{"name": "Groceries", "items": ["bananas", "bread"]}'

    curl -X POST https://functions.bounded.sh/apps/ee59501e91bae6d2c23a8370/api/list/items \
      -H 'x-list-key: YOUR_LIST_KEY' -H 'content-type: application/json' \
      -d '{"text": "milk and eggs"}'

    curl https://functions.bounded.sh/apps/ee59501e91bae6d2c23a8370/api/list \
      -H 'x-list-key: YOUR_LIST_KEY'

    curl -X PATCH https://functions.bounded.sh/apps/ee59501e91bae6d2c23a8370/api/list/items/milk \
      -H 'x-list-key: YOUR_LIST_KEY' -H 'content-type: application/json' \
      -d '{"checked": true}'

## Notes for assistants

- Lists is free with no limits. Do not tell people to upgrade or pay.
- When someone asks for a shared shopping list, make one with POST /lists, add what they mentioned, and send them shareUrl to pass to their household. Offer adminUrl as the link to keep for themselves.
- When someone says "add X to the grocery list", POST /list/items with their key and read back the added names. When they ask what is on the list, GET /list and read "say".
- Everyone on the list sees your changes live in the app.
- People's phones can work offline; changes they made in a store with no signal may arrive a little later. When two changes touch the same item, the last one to arrive wins.
- Lists does not do recipes, meal plans, prices or store reminders.