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

# Einführung

> Authentifiziere dich, erstelle einen Chat, sende Nachrichten und streame Antworten mit der homie REST API.

Mit der homie REST API erstellst du Chats, sendest Nachrichten an einen Assistenten und empfängst Antworten programmatisch. Nutze sie, wenn du eine eigene Integration bauen möchtest statt des einbettbaren Widgets.

<Note>
  **Der API-Zugang ist ausschließlich für Enterprise-Kunden verfügbar.** API-Keys werden von homie erstellt und vergeben — du kannst sie nicht selbst erzeugen. Wende dich an dein homie-Account-Team, um Zugang anzufragen.
</Note>

## Authentifizierung

Jede Anfrage muss deinen API-Key im `x-api-key`-Header enthalten. Keys werden von homie an deine Organisation vergeben — halte sie geheim und nutze sie nur serverseitig.

```bash theme={null}
curl https://api.yourhomie.ai/v1/chats \
  -H "x-api-key: homie_sk_live_8f3a..." \
  -H "Content-Type: application/json"
```

<Warning>
  Halte deinen API-Key geheim. Er gewährt Zugriff auf die Daten deiner Organisation, nutze ihn also nur serverseitig und gib ihn niemals im Browser oder in einer Mobile-App preis.
</Warning>

## Der Chat-Ablauf

Eine typische Integration folgt drei Schritten:

<Steps>
  <Step title="Chat erstellen">
    Rufe [Chat erstellen](/de/api-reference/backend/chats/create-chat) mit deiner `chatbotId` auf. Du erhältst eine `chatId`, die die Konversation identifiziert.
  </Step>

  <Step title="Nachricht hinzufügen">
    Rufe [Nachricht hinzufügen](/de/api-reference/backend/messages/send-message) mit der `chatId`, der `message` des Nutzers und der `currentUrl` auf. Der Assistent beginnt, eine Antwort zu generieren.
  </Step>

  <Step title="Events abhören">
    Öffne den [Nachrichten-Events](/de/api-reference/backend/messages/message-events)-Stream für die `chatId`, um die Antwort des Assistenten und Tool-Aktivität in Echtzeit über Server-Sent Events zu empfangen.
  </Step>
</Steps>

## Fehlerformat

Fehler liefern einen HTTP-Status außerhalb des 2xx-Bereichs und einen JSON-Body mit einer `message`, die beschreibt, was schiefgelaufen ist:

```json theme={null}
{
  "message": "Chat not found"
}
```

Häufige Statuscodes:

| Status | Bedeutung                                                |
| ------ | -------------------------------------------------------- |
| `401`  | Fehlender oder ungültiger API-Key.                       |
| `404`  | Die angeforderte Ressource existiert nicht.              |
| `422`  | Der Request-Body hat die Validierung nicht bestanden.    |
| `429`  | Das Nachrichtenkontingent deines Plans ist aufgebraucht. |

<Info>
  Die API-Nutzung zählt auf das monatliche Nachrichtenkontingent deines Plans. Ist das Kontingent erreicht, liefern die Nachrichten-Endpunkte einen Fehler, bis es zurückgesetzt wird oder du deinen Plan upgradest. Den Verbrauch siehst du unter **Nutzung** auf der Plattform.
</Info>

## Paginierung

List-Endpunkte liefern einen paginierten Umschlag zurück. Das `items`-Array enthält die Ergebnisse der aktuellen Seite, die übrigen Felder beschreiben die Gesamtmenge:

```json theme={null}
{
  "items": [],
  "totalItems": 42,
  "size": 20,
  "totalPages": 3,
  "currentPage": 1,
  "hasPrevPage": false,
  "hasNextPage": true,
  "prevPage": null,
  "nextPage": 2
}
```

`prevPage` und `nextPage` sind `null`, wenn es keine vorherige bzw. nächste Seite gibt.

## Bezeichner

Alle Ressourcen-IDs (`chatId`, `chatbotId`, `userId`, `organizationId`) sind eindeutige String-IDs, zum Beispiel `5e9c1a2b-3d4e-4f60-b2f2-9f4b1c2d3e4f`.

## Endpunkte

<CardGroup cols={2}>
  <Card title="Chat erstellen" icon="plus" href="/de/api-reference/backend/chats/create-chat">
    Starte eine neue Konversation für einen Chatbot.
  </Card>

  <Card title="Chat abrufen" icon="magnifying-glass" href="/de/api-reference/backend/chats/get-chat">
    Rufe einen Chat anhand seiner ID ab.
  </Card>

  <Card title="Nachricht hinzufügen" icon="paper-plane" href="/de/api-reference/backend/messages/send-message">
    Sende eine Nutzernachricht an den Assistenten.
  </Card>

  <Card title="Nachrichten auflisten" icon="list" href="/de/api-reference/backend/messages/list-messages">
    Blättere durch den Nachrichtenverlauf eines Chats.
  </Card>

  <Card title="Nachrichten-Events" icon="bolt" href="/de/api-reference/backend/messages/message-events">
    Streame Assistenten-Antworten über SSE.
  </Card>

  <Card title="PDP-Fragenset abrufen" icon="circle-question" href="/de/api-reference/backend/pdp-questions/get-pdp-questions">
    Rufe öffentliche Produktfragen für eine Seite ab.
  </Card>
</CardGroup>