> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference key-value store

> Store, group, and query Redis-based key-value entries through the Admin Interface API for temporary configs, caches, and shop status data.

The `storage/` endpoint provides an interface for managing key-value pairs in a Redis-based store.

In addition to directly storing individual key-value pairs, the API also offers the option of consolidating these entries into logical groups, enabling structured organization and targeted queries. Creating, retrieving, updating, and deleting both individual entries and entire groups is supported.

The API is particularly suitable for temporary configuration data, intermediate caches, or status-related information in the shop system.

***

## Supported methods

List of all supported methods.

| **Command/info**    | **Endpoints**  | **GET**               | **POST**              | **PUT**               | **DELETE**            |
| ------------------- | -------------- | --------------------- | --------------------- | --------------------- | --------------------- |
| **Key-value pairs** | storage/keys   | <Icon icon="check" /> | <Icon icon="check" /> | <Icon icon="ban" />   | <Icon icon="check" /> |
| **Key groups**      | storage/groups | <Icon icon="check" /> | <Icon icon="check" /> | <Icon icon="check" /> | <Icon icon="check" /> |

## Key groups

### Data fields of a key group

| **Name**        | **Type** | **Usage**                                   |
| --------------- | -------- | ------------------------------------------- |
| **createdAt**   | String   | Time of creation (ISO 8601 format, UTC).    |
| **description** | String   | Description of the group.                   |
| **id**          | Integer  | Unique ID of the group.                     |
| **keysArray**   | Array    | Names of keys belonging to the group.       |
| **name**        | String   | Name of the group.                          |
| **updatedAt**   | String   | Time of last update (ISO 8601 format, UTC). |

#### Example

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "createdAt": "2025-02-17 15:49:33",
    "description": "myDescription",
    "id": 1,
    "keysArray": [
        "asdf",
        "foo"
    ],
    "name": "myGroup",
    "updatedAt": "2025-02-17 15:49:34"
}
```

## Methods for key-value pairs

This section describes the endpoints for managing individual key-value pairs in the system's key-value store. The API can be used to create, retrieve, update, and delete entries.

Optionally, an expiration date (TTL) can be set to store values for a limited time.

### GET storage/keys

This endpoint retrieves a list of all key-value pairs stored in the system.

The values are returned together with the corresponding key (`key`), the associated value (`value`), and an optional expiration date (`expirationDate`). This endpoint thus enables an overview of all entries currently present in the key-value store.

There are no sort or filter fields — the list of parameters is fixed. For `textSearch`, the key name is considered; for `filter_contains[value]`, it is not. `filter_contains[value]` can also be specified multiple times. Other parameters behave the same as for standard GET requests.

Read permissions for key-value store data are required to use this endpoint.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/storage/keys
```

#### Supported parameters

`size`, `filter_gte[expirationDate]`, `filter_lte[expirationDate]`, `filter_eq[group]`, `pageToken`, `textSearch`, `filter_contains[value]`, `sort`

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "endReached": false,
    "items": [
        {
            "expirationDate": "2026-02-18T09:27:09.868Z",
            "key": "asdf",
            "value": "asdf"
        },
        {
            "expirationDate": "2026-02-18T09:24:38.868Z",
            "key": "test",
            "value": "test123"
        }
    ],
    "nextPageToken": "",
    "totalCount": 2
}
```

#### Error codes

| **Error**               | **Type**        | **Reason**                                                                                           |
| ----------------------- | --------------- | ---------------------------------------------------------------------------------------------------- |
| 401 Unauthorized        |                 | Not authorized: you are not logged in.                                                               |
| 403 Forbidden           |                 | You do not have the required permissions to read key-value store data.                               |
| 400 Bad Request         | "invalidFormat" | The group ID in `filter_eq[group]` is not a positive integer.<br />`size` is not a positive integer. |
| 503 Service Unavailable | "internalError" | The internal `RedisService` cannot be reached.                                                       |

### GET storage/keys/\{key}

This endpoint can be used to retrieve an individual key-value pair by its key (`key`).

The response contains the stored value (`value`) and, optionally, an expiration date (`expirationDate`) if one was set.

Read permissions for key-value store data are required to use this endpoint.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/storage/keys/asdf
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "expirationDate": "2025-02-20T15:49:19.169Z",
    "key": "asdf",
    "value": "asdf"
}
```

#### Error codes

| **Error**               | **Type**        | **Reason**                                                                                  |
| ----------------------- | --------------- | ------------------------------------------------------------------------------------------- |
| 401 Unauthorized        |                 | Not authorized: you are not logged in.                                                      |
| 403 Forbidden           |                 | You do not have the required permissions to read key-value store data.                      |
| 400 Bad Request         | "invalidFormat" | `{key}` contains special characters that do not belong to `{'_', '-', '/', '.', ':', ' '}`. |
| 400 Bad Request         | "missing"       | `{key}` was not provided.                                                                   |
| 404 Not Found           |                 | The key was not found in Redis.                                                             |
| 503 Service Unavailable | "internalError" | The internal `RedisService` cannot be reached.                                              |

### POST storage/keys

This endpoint can be used to store a new key-value pair in the key-value store.

The key (`key`) and the associated value (`value`) are passed in the request body.\
Optionally, a lifetime in days can be specified with `ttlDays`, after which the entry is automatically deleted (TTL = Time To Live).

If the key-value pair already exists, it is overwritten.

Create permissions for key-value store data are required to use this endpoint.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/storage/keys
```

#### Request body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "key": "foo",
    "value": "bar",
    "ttlDays": 2
}
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "key": "foo",
    "ttl": 172800,
    "ttlDays": 2,
    "value": "bar"
}
```

#### Error codes

| **Error**               | **Type**           | **Reason**                                                                                                                                                                               |
| ----------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized        |                    | Not authorized: you are not logged in.                                                                                                                                                   |
| 403 Forbidden           |                    | You do not have the required permissions to create key-value store data.                                                                                                                 |
| 400 Bad Request         |                    | Request body could not be loaded.                                                                                                                                                        |
| 400 Bad Request         | "unknownDataField" | An unknown field was provided in the request body.                                                                                                                                       |
| 400 Bad Request         | "missing"          | `key` or `value` is missing.                                                                                                                                                             |
| 400 Bad Request         | "invalidValue"     | `key` or `value` is empty.                                                                                                                                                               |
| 400 Bad Request         | "invalidFormat"    | `key` contains special characters that do not belong to `{'_', '-', '/', '.', ':', ' '}`. <br /> `key`, `value`, or `ttlDays` has an invalid type. `ttlDays` must be a positive integer. |
| 503 Service Unavailable | "internalError"    | The internal `RedisService` cannot be reached. <br /> The value could not be stored.                                                                                                     |

### DELETE storage/keys/\{key}

This endpoint permanently removes an existing key-value pair from the key-value store by its key (`key`).

On success, a JSON object with `success: true` is returned.

Delete permissions for key-value store data are required to use this endpoint.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/storage/keys/asdf
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "success": true
}
```

#### Error codes

| **Error**               | **Type**        | **Reason**                                                                                  |
| ----------------------- | --------------- | ------------------------------------------------------------------------------------------- |
| 401 Unauthorized        |                 | Not authorized: you are not logged in.                                                      |
| 403 Forbidden           |                 | You do not have the required permissions to delete key-value store data.                    |
| 400 Bad Request         | "invalidFormat" | `{key}` contains special characters that do not belong to `{'_', '-', '/', '.', ':', ' '}`. |
| 400 Bad Request         | "missing"       | `{key}` was not provided.                                                                   |
| 503 Service Unavailable | "internalError" | The internal `RedisService` cannot be reached.                                              |

## Methods for key groups

Key groups are used to logically bundle multiple key-value pairs.\
The endpoints described here enable groups to be created, edited, retrieved, or deleted. A group contains meta information such as name, description, and a list of associated keys.

### GET storage/groups

This endpoint retrieves a list of all key groups defined in the system.\
A key group is a logical collection of multiple key-value pairs that are managed under a shared group name.

The response contains, among other things, the group name (`name`), the number of keys it contains (`numKeys`), and creation and modification times. Filter and sort functions are available for controlling the results.

Read permissions for key-value store data are required to use this endpoint.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/storage/groups/
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "endReached": true,
    "items": [
        {
            "createdAt": "2025-02-17 15:49:33",
            "description": "",
            "id": 1,
            "keysArray": [
                "asdf"
            ],
            "name": "qwerty",
            "numKeys": 1,
            "updatedAt": "2025-02-17 15:49:34"
        },
        ...
    ],
    "nextPageToken": "MA",
    "totalCount": 1
}
```

#### Filter fields

`keysArray`

#### Sort fields

`numKeys`, `name`, `createdAt`, `updatedAt`

#### Error codes

| **Error**        | **Type**            | **Reason**                                                             |
| ---------------- | ------------------- | ---------------------------------------------------------------------- |
| 401 Unauthorized |                     | Not authorized: you are not logged in.                                 |
| 403 Forbidden    |                     | You do not have the required permissions to read key-value store data. |
| 400 Bad Request  | "invalidValue"      |                                                                        |
| 400 Bad Request  | "invalidCharacters" | `size` is not an integer. <br /> A filter value is invalid.            |
| 400 Bad Request  | "unknownDataField"  | A filter or sort field is invalid.                                     |
| 400 Bad Request  | "unknownOperation"  | A filter type is invalid.                                              |
| 400 Bad Request  | "syntaxError"       | `sort` contains more than one or no ":".                               |

### GET storage/groups/\{id}

This endpoint can be used to load a single key group by its ID.

The response contains all available metadata for the group, including the group name (`name`), an optional description (`description`), and a list of associated keys (`keysArray`).

Read permissions for key-value store data are required to use this endpoint.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/storage/groups/1
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "createdAt": "2025-02-17 15:49:33",
    "description": "",
    "id": 1,
    "keysArray": [
        "asdf"
    ],
    "name": "qwerty",
    "updatedAt": "2025-02-17 15:49:34"
}
```

#### Error codes

| **Error**               | **Type**        | **Reason**                                                             |
| ----------------------- | --------------- | ---------------------------------------------------------------------- |
| 401 Unauthorized        |                 | Not authorized: you are not logged in.                                 |
| 403 Forbidden           |                 | You do not have the required permissions to read key-value store data. |
| 400 Bad Request         | "missing"       | `id` was not provided.                                                 |
| 503 Service Unavailable | "internalError" | `id` is invalid.                                                       |
| 404 Not Found           |                 | The group with `id`=`{id}` was not found.                              |

### POST storage/groups

This endpoint creates a new key group.

A key group consists of a unique name (`name`), an optional description (`description`), and a list of assigned keys (`keysArray`). The group can be used for structured management and grouping of multiple key-value entries.

Create permissions for key-value store data are required to use this endpoint.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/storage/groups
```

#### Request body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "name": "myGroup",
    "description": "Group description",
    "keysArray": [
        "asdf",
        "foo"
    ]
}
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "description": "Group description",
    "id": 3,
    "keysArray": [
        "asdf",
        "foo"
    ],
    "name": "myGroup"
}
```

#### Error codes

| **Error**        | **Type**           | **Reason**                                                               |
| ---------------- | ------------------ | ------------------------------------------------------------------------ |
| 401 Unauthorized |                    | Not authorized: you are not logged in.                                   |
| 403 Forbidden    |                    | You do not have the required permissions to create key-value store data. |
| 400 Bad Request  |                    | Request body could not be loaded.                                        |
| 400 Bad Request  | "unknownDataField" | An unknown field was provided in the request body.                       |
| 400 Bad Request  | "missing"          | `name` or `keysArray` is missing.                                        |
| 400 Bad Request  | "invalidValue"     | `name` is empty.                                                         |
| 400 Bad Request  | "invalidFormat"    | `name` or `description` is not a string, or `keysArray` is not an array. |

### PUT storage/groups/\{id}

This endpoint can be used to update an existing key group by its ID.

The group name (`name`), description (`description`), and associated keys (`keysArray`) can be changed or reset.

Write permissions for key-value store data are required to use this endpoint.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/storage/groups/1
```

#### Request body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "description": "myDescription",
    "keysArray": [
        "asdf",
        "foo"
    ],
    "name": "qwerty"
}
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "description": "myDescription",
    "keysArray": [
        "asdf",
        "foo"
    ],
    "name": "qwerty"
}
```

#### Error code

| **Error**               | **Type**           | **Reason**                                                               |
| ----------------------- | ------------------ | ------------------------------------------------------------------------ |
| 401 Unauthorized        |                    | Not authorized: you are not logged in.                                   |
| 403 Forbidden           |                    | You do not have the required permissions to write key-value store data.  |
| 400 Bad Request         |                    | Request body could not be loaded.                                        |
| 400 Bad Request         | "unknownDataField" | An unknown field was provided in the request body.                       |
| 400 Bad Request         | "missing"          | `id`, `name`, or `keysArray` is missing.                                 |
| 400 Bad Request         | "invalidValue"     | `name` is empty.                                                         |
| 400 Bad Request         | "invalidFormat"    | `name` or `description` is not a string, or `keysArray` is not an array. |
| 503 Service Unavailable | "internalError"    | `id` is invalid.                                                         |

### DELETE storage/groups/\{id}

This endpoint deletes an existing key group by its ID.

The associated key-value entries remain in the system; only the group assignment is removed. On success, a JSON object with `success: true` is returned.

Delete permissions for key-value store data are required to use this endpoint.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/storage/groups/1
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "success": true
}
```

#### Error code

| **Error**               | **Type**        | **Reason**                                                               |
| ----------------------- | --------------- | ------------------------------------------------------------------------ |
| 401 Unauthorized        |                 | Not authorized: you are not logged in.                                   |
| 403 Forbidden           |                 | You do not have the required permissions to delete key-value store data. |
| 400 Bad Request         | "missing"       | `id` was not provided.                                                   |
| 503 Service Unavailable | "internalError" | `id` is invalid.                                                         |
| 404 Not Found           |                 | The group with `id`=`{id}` was not found.                                |

## Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: [Zum Kundenportal](https://websale.atlassian.net/servicedesk/customer/portal/6)

Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.