API Reference

GET /api/lists/?user_id={id}

Returns all shopping lists the user owns, is shared with, or belongs to via group.

{
  "lists": [
    {
      "id": 1,
      "name": "Weekly Groceries",
      "owner": 1,
      "group": null,
      "created_at": "2026-01-15T10:30:00Z",
      "items": [ ... ],
      "items_count": 5
    }
  ]
}

POST /api/lists/create/?user_id={id}

Create a new shopping list. Send a JSON body.

# Personal list
{ "name": "My Shopping List" }

# Group list
{ "name": "Family Groceries", "group_id": 2 }

Returns 201 Created with the list object. User must be member of specified group.

DELETE /api/lists/{id}/delete/?user_id={id}

Delete a personal list. Only the owner can delete, and only personal lists (no group).

{ "message": "List deleted successfully" }

POST /api/lists/{id}/leave/?user_id={id}

Leave a shared or group list. Removes the user from the list.

• If you're the owner, ownership transfers to another member
• If no members remain, the list is deleted
• Cannot leave personal lists (use delete instead)

# Success
{ "message": "Successfully left the list" }

# List deleted when no members remain
{ "message": "List deleted as no members remain" }

GET /api/lists/{list_id}/items/?user_id={id}

Returns all items in a shopping list.

{
  "items": [
    {
      "id": 1,
      "shopping_list": 1,
      "name": "Milk",
      "category": { "id": 2, "name": "Dairy" },
      "amount": 2,
      "max_price": "3.50",
      "buy_until": "2026-02-15",
      "link": null,
      "created_at": "2026-02-10T14:00:00Z",
      "is_bought": false
    }
  ]
}

POST /api/lists/{list_id}/items/create/?user_id={id}

Add a new item to a list. Send a JSON body.

Returns 201 Created with the item object.

PATCH /api/items/{item_id}/update/?user_id={id}

Update an item. Send only fields to change.

{ "amount": 3, "max_price": "4.00" }

DELETE /api/items/{item_id}/delete/?user_id={id}

Delete an item.

{ "message": "Item deleted successfully" }

POST /api/items/{item_id}/toggle/?user_id={id}

Toggle is_bought status. Returns the updated item.

GET /api/categories/

List all categories. No user_id required.

{
  "categories": [
    { "id": 1, "name": "Electronics" },
    { "id": 2, "name": "Groceries" },
    { "id": 3, "name": "Household" }
  ]
}

POST /api/categories/create/?user_id={id}

Create a new category. Send a JSON body.

{ "name": "Books" }

Returns 201 Created with the category object, or 400 if category already exists.

GET /api/shops/

List all shops and their categories. No user_id required.

{
  "shops": [
    {
      "id": 1,
      "name": "Amazon",
      "url": "https://amazon.de",
      "categories": [
        { "id": 1, "name": "Electronics" },
        { "id": 3, "name": "Household" }
      ]
    }
  ]
}

GET /api/groups/?user_id={id}

List all groups the user belongs to.

{
  "groups": [
    {
      "id": 1,
      "name": "Household",
      "members": [1, 2, 3],
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

GET /api/bulk-check/?user_id={id}

Scans all unbought items across all accessible lists. Groups by category and returns categories with 2+ items — potential bulk order opportunities.

{
  "bulk_opportunities": {
    "Electronics": [
      { "id": 5, "name": "USB-C Cable", "list_name": "Office", "amount": 3, "max_price": "8.00" },
      { "id": 12, "name": "HDMI Adapter", "list_name": "Living Room", "amount": 1, "max_price": null }
    ]
  }
}