← Back

API Documentation

Integrate Bring Bananas into your apps, automations, and workflows using our REST API.

Try it out

Enter your API key to run requests directly from this page. You can generate an API key in the Bring Bananas app.

Authentication

All API requests require an API key sent via the X-API-Key header. 

X-API-Key: bb_your_api_key_here

Requests without a valid API key will receive a 401 error response.

Base URL

https://api.bringbananas.com

Endpoints

GET /api/v1/shopping-lists

Returns the user's shopping lists.

Example request

curl https://api.bringbananas.com/api/v1/shopping-lists \
  -H "X-API-Key: bb_your_api_key"

Response

Returns an array of shopping list objects.

[
  {
    "id": "7ed1ae7f-8626-45fd-9998-91a6afae186d",
    "name": "Home",
    "role": "owner",
    "created_at": "2026-02-19T21:33:38.126Z",
    "updated_at": "2026-02-26T02:02:54.454Z"
  }
]
GET /api/v1/shopping-lists/:id/items

Returns items in a shopping list (excludes soft-deleted).

Path parameters

id required

The UUID of the shopping list.

Example request

curl https://api.bringbananas.com/api/v1/shopping-lists/{id}/items \
  -H "X-API-Key: bb_your_api_key"

Response

Returns an array of shopping list item objects.

[
  {
    "id": "6752281c-fdcd-4404-8598-06dd89696d67",
    "shopping_list_id": "7ed1ae7f-8626-45fd-9998-91a6afae186d",
    "ingredient_id": null,
    "name": "Quinoa",
    "normalized_name": "quinoa",
    "note": null,
    "added_at": "2026-02-26T17:10:04.848Z",
    "completed_at": null
  }
]
GET /api/v1/ingredients

Returns all ingredients with their category name, sorted alphabetically.

Example request

curl https://api.bringbananas.com/api/v1/ingredients \
  -H "X-API-Key: bb_your_api_key"

Response

Returns an array of ingredient objects.

[
  { "id": 1, "name": "Apple", "category": "Fruits" },
  { "id": 2, "name": "Banana", "category": "Fruits" },
  { "id": 3, "name": "Chicken Breast", "category": "Meat" }
]
POST /api/v1/shopping-lists/:id/items

Adds a new item to a shopping list. The normalized_name is auto-generated from name (lowercased + trimmed).

Path parameters

id required

The UUID of the shopping list.

Request body

name required string

Item name.

note string

Optional note.

ingredient_id integer

Link to an ingredient.

Example request

curl -X POST https://api.bringbananas.com/api/v1/shopping-lists/{id}/items \
  -H "X-API-Key: bb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Bananas", "note": "the ripe ones"}'

Response

Returns the created item object.

{
  "id": "c3988d3f-72fa-4ef2-8fcf-4687b00a011f",
  "shopping_list_id": "7ed1ae7f-8626-45fd-9998-91a6afae186d",
  "ingredient_id": null,
  "name": "Bananas",
  "normalized_name": "bananas",
  "note": "the ripe ones",
  "added_at": "2026-02-27T15:05:43.161549Z",
  "completed_at": null
}
PATCH /api/v1/shopping-list-items/:id

Updates an item. All fields are optional — only provided fields are updated.

Path parameters

id required

The UUID of the shopping list item.

Request body

name string

Updates name + normalized_name.

note string

Updates note.

ingredient_id integer

Updates ingredient link.

completed_at string

ISO 8601 timestamp to mark complete, "" to uncomplete.

Example request

curl -X PATCH https://api.bringbananas.com/api/v1/shopping-list-items/{id} \
  -H "X-API-Key: bb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"note": "updated note", "completed_at": "2026-02-27T15:00:00Z"}'

Response

Returns the updated item object.

{
  "id": "c3988d3f-72fa-4ef2-8fcf-4687b00a011f",
  "shopping_list_id": "7ed1ae7f-8626-45fd-9998-91a6afae186d",
  "ingredient_id": null,
  "name": "Test API Item",
  "normalized_name": "test api item",
  "note": "updated note",
  "added_at": "2026-02-27T15:05:43.161549Z",
  "completed_at": "2026-02-27T15:00:00Z"
}
DELETE /api/v1/shopping-list-items/:id

Soft-deletes an item from a shopping list.

Path parameters

id required

The UUID of the shopping list item to delete.

Example request

curl -X DELETE https://api.bringbananas.com/api/v1/shopping-list-items/{id} \
  -H "X-API-Key: bb_your_api_key"

Response

Returns an empty response with status 204 No Content on success.

Errors

The API returns JSON error responses with an error field.

Status Body Meaning
401 {"error": "missing API key"} No X-API-Key header provided.
401 {"error": "invalid API key"} The provided API key is not valid.