# API-Referenz

REST- und WebSocket-API für Agenten, Chats, Wissensdatenbank, Tools, Telefonnummern und Webhooks

> Full REST + WebSocket API reference: https://api.happ.tools/reference

Happ bietet eine REST- und WebSocket-API, um Agenten zu verwalten, Nachrichten zu senden, den KI-Modus zu steuern und Happ in Ihre Abläufe zu integrieren. Die vollständige Referenz zum Ausprobieren finden Sie in Scalar — sie ist maßgeblich für alle Endpunkte, Schemas und Beispiele.

**[api.happ.tools/reference](https://api.happ.tools/reference)**

## Ressourcengruppen [#resource-groups]

Die öffentliche Referenz umfasst diese Gruppen:

* **Auth** — Anmeldung, Token erneuern
* **Companies** — Workspaces, Mitglieder, Einladungen
* **Access Tokens** — langlebige Tokens für Integrationen
* **Assistants** — `GET/POST /api/assistants-new`, `PATCH /api/assistants-new/{id}`
* **Assistant tools** — `/api/assistant-tools-new`
* **Assistant knowledge** — `/api/assistant-knowledge-new`
* **Chats** — Chats auflisten, Nachrichten senden und auflisten, KI-Steuerung umschalten (`PATCH /api/chats/{id}` `isUnderAiControl`)
* **Calls** — einen ausgehenden Anruf starten: `POST /api/assistants/{id}/originate`

Alles Weitere auf der Plattform (Telefonnummern, Integrationen, Abrechnung, Analytik) wird über das Dashboard gesteuert, nicht über die öffentliche API.

## Authentifizierung [#authentication]

Jede Anfrage erfordert einen **Access Token**, den Sie in den Kontoeinstellungen unter [my.happ.tools](https://my.happ.tools) erzeugen. Senden Sie ihn im Header:

```
X-Access-Token: happ_your_token_here
```

Basis-URL (Produktion): `https://api.happ.tools`.

## WebSocket [#websocket]

Verbinden Sie sich über Socket.IO mit `wss://api.happ.tools` (Standard-Namespace, kein Pfadsuffix): Authentifizieren Sie sich mit Ihrem Token, übergeben Sie `auth: { companyId }` und empfangen Sie dann die Ereignisse `MESSAGE_CREATED`, `CHAT_MODE_CHANGED` und `CHAT_CREATED`. Siehe [Chats > Echtzeit-Updates](/docs/workspace/chats).

## Mit KI nutzen [#use-with-ai]

Sie bauen die Integration mit einem KI-Tool (Claude, Cursor, Copilot)? Geben Sie ihm unsere maschinenlesbaren Quellen, statt Dokumentation hineinzukopieren:

* **OpenAPI-Spezifikation** — `https://api.happ.tools/api/swagger-json` (alle Endpunkte, Schemas und Auth-Regeln)
* **Docs-Index** — `https://docs.happ.tools/llms.txt`

Start-Prompt:

```text
You are integrating with the Happ Platform API.
Spec: https://api.happ.tools/api/swagger-json
Docs: https://docs.happ.tools/llms.txt
Auth: send the header X-Access-Token: happ_...
Task: <describe what you want to build>
```

## Weiter [#next]

* [Chats](/docs/workspace/chats) — der Posteingang, den diese Endpunkte steuern
* [Webhooks](/docs/integrations/webhooks) — Ereignisse an Ihren Server senden