# Get your Shopping Lists

## Get Shopping Lists

<mark style="color:blue;">`GET`</mark> `https://api.studio.whisk.com/list/v2`

You can use just the base URL and the authentication header to retrieve basic information of all shopping list stored in your Whisk account:

#### Headers

| Name           | Type   | Description                                                                                                                 |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- |
| Authentication | string | User Access token with `shopping_list:read` scope  to to authorize the API usage. For more information, see Authentication. |

{% tabs %}
{% tab title="200 This is how a successful response looks." %}

```graphql
{
  "list": [
    {
      "id": "string",
      "name": "string",
      "primary": true
    }
  ],
  "items": [
    {
      "list": {
        "id": "string",
        "name": "string",
        "primary": true
      },
      "item_count": 0,
      "grouped_item_count": 0
    }
  ]
}
```

{% endtab %}

{% tab title="400 This failed response appears when error codes are found in the endpoint query." %}

```yaml
{
  "error_code": "REAL_CODES_ARE_IN_ENDPOINT_DESCRIPTION",
  "message": "Additional details about error are not static and can be changed"
}
```

{% endtab %}

{% tab title="401 This failed response appears due to API authentication failure. The possible error codes that may appear are:
auth.tokenNotFound
, auth.tokenExpired, auth.tokenInvalid, auth.tokenRequired." %}

```yaml
{
  "code": "auth.tokenNotFound"
}
```

{% endtab %}

{% tab title="500 This failed response appears when something is not right on Whisk's end. Please send a message to <help@whisk.com>, and be sure to include both the Request and Response data. We’ll get back to you soon." %}

```yaml
This is unexpected response, something is wrong on our side, please contact: help@whisk.com
```

{% endtab %}
{% endtabs %}

### Sample Request and Response

{% tabs %}
{% tab title="Curl Request" %}

```bash
curl -X GET "https://api.whisk.com/list/v2"
    -H "Accept: application/json" 
    -H "Authorization: Bearer <YOUR-API-ACCESS-KEY>"
```

{% hint style="info" %}
Whisk allows you to discover and understand its API capabilities on the Swagger interface with the ability to try out the API calls directly in your browser. You can call this endpoint [here](https://api.whisk.com/spec/#/ShoppingListAPI/ShoppingListAPI_GetLists).
{% endhint %}
{% endtab %}

{% tab title="Response" %}

```graphql
{
  "list": [
    {
      "id": "106e1fa4cbb7c844458be372c3e0f7bfa94",
      "name": "My Secondary Shopping List"
    },
    {
      "id": "106f9105f1d05d24ad2b833f5d2a966be77",
      "name": "My Shopping List",
      "primary": true
    }
  ],
  "items": [
    {
      "list": {
        "id": "106e1fa4cbb7c844458be372c3e0f7bfa94",
        "name": "My Secondary Shopping List"
      },
      "item_count": 21,
      "grouped_item_count": 20
    },
    {
      "list": {
        "id": "106f9105f1d05d24ad2b833f5d2a966be77",
        "name": "My Shopping List",
        "primary": true
      },
      "item_count": 2,
      "grouped_item_count": 2
    }
  ]
}
```

As shown in this example, the information that gets retrieved is generally grouped into `list` and `items` arrays.

#### `list`

The `list` array includes identification details of all your shopping lists.

| **Attribute** | **Type** | **Description**                      |
| ------------- | -------- | ------------------------------------ |
| `id`          | string   | The unique shopping list identifier. |
| `name`        | string   | The name of the shopping list.       |
| `primary`     | boolean  | Indicates if the list is primary.    |

#### `items`

The `items` array includes the count of items in each shopping list.

| **Attribute**        | **Type** | **Description**                                                                 |
| -------------------- | -------- | ------------------------------------------------------------------------------- |
| `list`               | array    | The list identification details as explained above.                             |
| `item_count`         | number   | The total number of items in the shopping list without combining similar items. |
| `grouped_item_count` | number   | The total number of items in the shopping list after combining similar items.   |
| {% endtab %}         |          |                                                                                 |
| {% endtabs %}        |          |                                                                                 |