# Listen und Felder

Die Methoden dieser Seite arbeiten mit dem Schema einer Liste — ihrem Namen und ihren Feldern. Wie Felder aufgebaut sind und welche Typen es gibt, steht auf der Seite [Listen](https://support.watbot.org/de/api/lists#feldtypen).

## getListSchemas

Gibt die Listen aller Projekte zurück, deren Inhaber der Schlüsselinhaber ist, 50 pro Seite.

```endpoint
GET POST https://watbot.org/de/api/v1/getListSchemas
```

| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `page` | Ganzzahl | nein | Seitennummer, standardmäßig `1` |

```bash title="Anfrage"
curl -X POST "https://watbot.org/de/api/v1/getListSchemas" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"page": 1}'
```

```json title="Antwort 200"
{
  "data": [
    {
      "id": "6650a1f2c3d4e5f6a7b8c9d0",
      "fields": {
        "bezeichnung": {
          "name": "Bezeichnung",
          "type": "string",
          "is_required": true,
          "is_hidden": false,
          "is_encryptable": false
        },
        "preis": {
          "name": "Preis",
          "type": "money",
          "currency": "EUR",
          "is_required": true,
          "is_hidden": false,
          "is_encryptable": false
        }
      },
      "name": "Speisekarte des Cafés",
      "bot_id": 12345,
      "project": "3f2b8c1e-5a7d-4e9b-8c6f-1d2e3f4a5b6c",
      "is_menu": false,
      "created_at": "2026-10-01T09:15:00+00:00",
      "updated_at": "2026-10-02T11:40:12+00:00"
    }
  ],
  "links": {
    "first": "…/v1/getListSchemas?page=1",
    "last": "…/v1/getListSchemas?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "…/v1/getListSchemas",
    "per_page": 50,
    "to": 1,
    "total": 1
  }
}
```

Felder einer Liste in der Antwort:

| Feld | Beschreibung |
|---|---|
| `id` | ID der Liste |
| `fields` | Felder: Der Schlüssel ist der `slug`, der Wert enthält den Namen (`name`), den Typ (`type`) und die Einstellungen. Ein Geldfeld hat zusätzlich `currency`. Felder, die im Konto erstellt wurden, können weitere Schlüssel haben |
| `name` | Name der Liste |
| `bot_id` | Bot, in dem die Liste erstellt wurde; `null`, wenn die Liste im Projekt erstellt wurde |
| `project` | UUID des Projekts, zu dem die Liste gehört |
| `is_menu` | Veraltete Kennzeichnung, ohne Einfluss auf die Liste |
| `created_at`, `updated_at` | Wann die Liste erstellt und zuletzt geändert wurde |

Besonderheiten:

- Eine Seite enthält 50 Listen, das lässt sich nicht ändern. Die Gesamtzahl der Seiten steht in `meta.last_page`, die Adresse der nächsten Seite in `links.next`.
- Listen von Projekten, in die Sie als Teammitglied eingeladen wurden, sind nicht enthalten: Die API arbeitet nur mit den Projekten des Schlüsselinhabers.

## getListSchema

Gibt eine Liste mit ihren Feldern zurück.

```endpoint
GET POST https://watbot.org/de/api/v1/getListSchema
```

| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `schema_id` | String | ja | ID der Liste |

```bash title="Anfrage"
curl -X POST "https://watbot.org/de/api/v1/getListSchema" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"schema_id": "6650a1f2c3d4e5f6a7b8c9d0"}'
```

```json title="Antwort 200"
{
  "data": {
    "id": "6650a1f2c3d4e5f6a7b8c9d0",
    "fields": {
      "bezeichnung": {
        "name": "Bezeichnung",
        "type": "string",
        "is_required": true,
        "is_hidden": false,
        "is_encryptable": false
      },
      "preis": {
        "name": "Preis",
        "type": "money",
        "currency": "EUR",
        "is_required": true,
        "is_hidden": false,
        "is_encryptable": false
      }
    },
    "name": "Speisekarte des Cafés",
    "bot_id": 12345,
    "project": "3f2b8c1e-5a7d-4e9b-8c6f-1d2e3f4a5b6c",
    "is_menu": false,
    "created_at": "2026-10-01T09:15:00+00:00",
    "updated_at": "2026-10-02T11:40:12+00:00"
  }
}
```

```json title="Antwort 404"
{
  "message": "Schema not found",
  "error": "Schema not found",
  "errors": {
    "schema_id": ["Schema not found"]
  }
}
```

Fehler:

- Die Liste existiert nicht oder wurde gelöscht — `404`. Der Fehlertext steht in `error` und `message`; aus Kompatibilitätsgründen auch in `errors.schema_id`.
- Die Liste gehört zu einem fremden Projekt — `403`.

## createListSchema

Erstellt eine Liste mit Feldern — in einem Projekt oder in einem Bot.

```endpoint
GET POST https://watbot.org/de/api/v1/createListSchema
```

| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `name` | String | ja | Name der Liste, bis zu 255 Zeichen |
| `project_uuid` | String | ja, wenn `bot_id` fehlt | UUID des Projekts, in dem die Liste erstellt wird |
| `bot_id` | Ganzzahl | ja, wenn `project_uuid` fehlt | ID des Bots: Die Liste kommt in das Projekt dieses Bots und wird als in ihm erstellt gekennzeichnet. Werden beide Parameter übergeben, gilt `bot_id` |
| `fields` | Array | ja | Felder der Liste — 1 bis 30 |
| `fields[].name` | String | ja | Name des Feldes, bis zu 255 Zeichen |
| `fields[].slug` | String | ja | Feldname: Buchstaben, Ziffern, `-` und `_`, bis zu 255 Zeichen; am besten lateinische Buchstaben. Darf sich in der Liste nicht wiederholen und nicht mit den [internen Namen](https://support.watbot.org/de/api/lists#einschränkungen) übereinstimmen |
| `fields[].type` | String | ja | Feldtyp: `string`, `number`, `bool`, `date`, `datetime`, `money`, `file`, `image`, `contact`, `bot` |
| `fields[].currency` | String | nein | Nur für `money`: dreibuchstabiger Währungscode nach ISO 4217 — `EUR`, `USD`, `CHF`. Standardmäßig `USD`. Ein unbekannter Code — `422` |
| `fields[].is_required` | Boolean | nein | Pflichtfeld. Standardmäßig `true` |
| `fields[].is_hidden` | Boolean | nein | Feld in der Oberfläche ausblenden. Standardmäßig `false` |
| `fields[].is_encryptable` | Boolean | nein | Wert verschlüsselt speichern. Standardmäßig `false` |
| `is_menu` | Boolean | nein | Veraltete Kennzeichnung, ohne Einfluss auf die Liste |

```bash title="Anfrage"
curl -X POST "https://watbot.org/de/api/v1/createListSchema" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "project_uuid": "3f2b8c1e-5a7d-4e9b-8c6f-1d2e3f4a5b6c",
    "name": "Speisekarte des Cafés",
    "fields": [
      {"name": "Bezeichnung", "slug": "bezeichnung", "type": "string"},
      {"name": "Preis", "slug": "preis", "type": "money", "currency": "EUR"},
      {"name": "Foto", "slug": "foto", "type": "image", "is_required": false},
      {"name": "Verfügbar", "slug": "verfuegbar", "type": "bool", "is_required": false}
    ]
  }'
```

```json title="Antwort 201"
{
  "data": {
    "id": "6650a1f2c3d4e5f6a7b8c9d0",
    "fields": {
      "bezeichnung": {
        "name": "Bezeichnung",
        "type": "string",
        "is_required": true,
        "is_hidden": false,
        "is_encryptable": false
      },
      "preis": {
        "name": "Preis",
        "type": "money",
        "is_required": true,
        "is_hidden": false,
        "is_encryptable": false,
        "currency": "EUR"
      },
      "foto": {
        "name": "Foto",
        "type": "image",
        "is_required": false,
        "is_hidden": false,
        "is_encryptable": false
      },
      "verfuegbar": {
        "name": "Verfügbar",
        "type": "bool",
        "is_required": false,
        "is_hidden": false,
        "is_encryptable": false
      }
    },
    "name": "Speisekarte des Cafés",
    "bot_id": null,
    "project": "3f2b8c1e-5a7d-4e9b-8c6f-1d2e3f4a5b6c",
    "is_menu": false,
    "created_at": "2026-10-03T08:00:00+00:00",
    "updated_at": "2026-10-03T08:00:00+00:00"
  }
}
```

```json title="Antwort 422"
{
  "message": "The slug is reserved.",
  "errors": {
    "fields.0.slug": ["The slug is reserved."]
  }
}
```

Besonderheiten und Fehler:

- Die Felder werden in der Reihenfolge angelegt, in der sie übergeben werden.
- Eine Liste können Sie nur in Ihrem eigenen Projekt oder Ihrem eigenen Bot erstellen. Ein Bot oder Projekt eines anderen Kontos, auch eines, in das Sie als Teammitglied eingeladen wurden, — `403`.
- Eine nicht existierende `bot_id` oder `project_uuid` — `422`.
- Ein wiederholter `slug` — `422` mit einem Fehler am Feld `fields.N.slug`, wobei N die Position des Feldes im Array ab null ist.
- Ein unbekannter Währungscode — `422` mit einem Fehler am Feld `fields.N.currency`.
- Das Projekt hat bereits 5000 Listen — `403`: `{"message": "A project cannot have more than 5000 lists", "error": "A project cannot have more than 5000 lists"}`.
- In einer `GET`-Anfrage werden die Felder so in der Adresse übergeben: `fields[0][name]=Bezeichnung&fields[0][slug]=bezeichnung&fields[0][type]=string`. Bequemer ist `POST` mit JSON.

## deleteListSchema

Löscht eine Liste zusammen mit ihren Einträgen.

```endpoint
GET POST https://watbot.org/de/api/v1/deleteListSchema
```

| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `schema_id` | String | ja | ID der Liste |

```bash title="Anfrage"
curl -X POST "https://watbot.org/de/api/v1/deleteListSchema" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"schema_id": "6650a1f2c3d4e5f6a7b8c9d0"}'
```

```json title="Antwort 404"
{
  "message": "Schema not found",
  "error": "Schema not found",
  "errors": {
    "schema_id": ["Schema not found"]
  }
}
```

Eine erfolgreiche Antwort hat den Code `204` und keinen Inhalt.

Besonderheiten und Fehler:

- Prüfen Sie vor dem Löschen, dass die Liste in keinem Block eines Bots ausgewählt ist: Nach dem Löschen finden die Blöcke keine Einträge mehr.
- Nach dem Löschen findet weder `getListItems` noch die Suche per `item_id` die Einträge der Liste: `updateListItem` und `deleteListItem` antworten mit `404`.
- Die Liste existiert nicht oder wurde bereits gelöscht — `404`, wie bei [`getListSchema`](#getlistschema).
- Die Liste gehört zu einem fremden Projekt — `403`.

## addListSchemaField

Fügt am Ende der Liste ein Feld hinzu.

```endpoint
GET POST https://watbot.org/de/api/v1/addListSchemaField
```

| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `schema_id` | String | ja | ID der Liste |
| `field` | Objekt | ja | Das neue Feld |
| `field.name` | String | ja | Name des Feldes, bis zu 255 Zeichen |
| `field.slug` | String | ja | Feldname: Buchstaben, Ziffern, `-` und `_`, bis zu 255 Zeichen; am besten lateinische Buchstaben |
| `field.type` | String | ja | Feldtyp — wie bei `createListSchema` |
| `field.is_required` | Boolean | nein | Pflichtfeld. Standardmäßig `true` |
| `field.is_hidden` | Boolean | nein | Feld in der Oberfläche ausblenden. Standardmäßig `false` |
| `field.is_encryptable` | Boolean | nein | Wert verschlüsselt speichern. Standardmäßig `false` |
| `field.currency` | String | bei `money` | Nur für `money`: dreibuchstabiger Währungscode nach ISO 4217 — `EUR`, `USD`, `CHF` |

```bash title="Anfrage"
curl -X POST "https://watbot.org/de/api/v1/addListSchemaField" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "6650a1f2c3d4e5f6a7b8c9d0",
    "field": {"name": "Größe, ml", "slug": "volumen", "type": "number", "is_required": false}
  }'
```

```json title="Antwort 422"
{
  "message": "The list already has a field with this slug",
  "errors": {
    "field.slug": ["The list already has a field with this slug"]
  }
}
```

Eine erfolgreiche Antwort hat den Code `204` und keinen Inhalt. Um die Liste mit dem neuen Feld zu sehen, rufen Sie [`getListSchema`](#getlistschema) auf.

Besonderheiten und Fehler:

- Ein Feld mit diesem `slug` gibt es bereits — `422` mit einem Fehler an `field.slug`.
- Ein `money`-Feld braucht eine Währung in `field.currency`: Ohne sie oder mit einem unbekannten Code — `422` mit einem Fehler an `field.currency`.
- Ist das neue Feld ein Pflichtfeld, müssen Sie es bei jedem neuen Eintrag ausfüllen. Bereits vorhandene Einträge ändern sich nicht.
- Die Liste existiert nicht — `404`, wie bei [`getListSchema`](#getlistschema); die Liste gehört zu einem fremden Projekt — `403`.

## deleteListSchemaField

Löscht ein Feld aus der Liste und entfernt seine Werte in allen Einträgen.

```endpoint
GET POST https://watbot.org/de/api/v1/deleteListSchemaField
```

| Parameter | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `schema_id` | String | ja | ID der Liste |
| `slug` | String | ja | Feldname |

```bash title="Anfrage"
curl -X POST "https://watbot.org/de/api/v1/deleteListSchemaField" \
  -H "Authorization: Bearer IHR_API_SCHLÜSSEL" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"schema_id": "6650a1f2c3d4e5f6a7b8c9d0", "slug": "volumen"}'
```

```json title="Antwort 422"
{
  "message": "Field not found",
  "errors": {
    "slug": ["Field not found"]
  }
}
```

Eine erfolgreiche Antwort hat den Code `204` und keinen Inhalt.

> [!WARNING]
> Die Werte des Feldes werden in allen Einträgen auf einmal entfernt. Sie lassen sich nicht wiederherstellen — genau wie beim [Löschen eines Feldes im Konto](https://support.watbot.org/de/lists/create#feld-löschen).

Fehler:

- Ein Feld mit diesem `slug` gibt es nicht — `422` mit einem Fehler an `slug`.
- Die Liste existiert nicht — `404`, wie bei [`getListSchema`](#getlistschema); die Liste gehört zu einem fremden Projekt — `403`.