REST API

Alles, was App und CLI von weside tun, tun sie über dieselbe HTTP-API. Wenn ein Skript, ein Webhook-Handler oder dein eigenes Werkzeug den Companion-Zustand lesen oder ändern soll, sprichst du direkt mit dieser API.

Was es ist

Eine JSON-REST-API, ausgeliefert von weside-core. Zwei Versionspräfixe laufen nebeneinander:

https://api.weside.ai/api/v1
https://api.weside.ai/api/v2

/api/v1 trägt die ältere Oberfläche: /auth, /users, /companions, /circles, /channels, /data-residency, /notes, /voice und weitere (die Memory-Routen hängen unter /companions/{companion_id}/memories). Unter /api/v2 leben Räume, Safety, Events, Suche, Bühne und Sticker — eine Nachricht zu senden ist zum Beispiel POST /api/v2/rooms/{room_id}/messages, keine /chat-Route. Die CLI erreicht die neuere Oberfläche mit weside api --v2. Die vollständige, immer aktuelle Liste über beide Versionen hinweg holst du dir als OpenAPI-Schema unter /openapi.json.

Warum es für dich wichtig ist

Der MCP-Server und die CLI decken die häufigen Fälle ab — einen Companion übernehmen, Erinnerungen lesen, Ziele verfolgen. Die REST-API ist die Schicht darunter: Greif danach, wenn du etwas brauchst, das die beiden nicht offenlegen, oder wenn du weside in ein System verdrahtest, das schon HTTP spricht.

Wie du es nutzt

Authentifiziere dich bei jeder Anfrage mit einem Bearer-Token — dem Supabase-Access-Token aus einer angemeldeten weside-Session:

curl https://api.weside.ai/api/v1/auth/me \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"

GET /api/v1/auth/me gibt den aktuellen Nutzer zurück — ein schneller Weg, um zu bestätigen, dass dein Token funktioniert.

Die Companions deines Kontos auflisten:

curl https://api.weside.ai/api/v1/companions \
  -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN"

Die Antwort trägt die Companion-IDs, die du dann gegen die companion-gebundenen Routen nutzt (Chat, Erinnerung, Skills). Jeder Endpunkt gibt JSON zurück; Fehler folgen den Problem Details nach RFC 9457, ein Fehler-Body trägt also ein maschinenlesbares type und detail, auf das du verzweigen kannst.

Grenzen & Sonderfälle

• Auth ist das Supabase-JWT, kein statischer API-Key. Tokens laufen ab — erneuere sie über die Supabase-Session, denselben Ablauf, den die App nutzt. (Um deinen Companion stattdessen auf einem eigenen LLM laufen zu lassen, siehe den eigenen Modell-Key verbinden.)
• Rate Limits gelten je Route; lesende und schreibende Endpunkte haben getrennte Budgets. Ein 429 heißt: langsamer machen.
• Row Level Security wird serverseitig durchgesetzt. Du siehst immer nur deine eigenen Daten — ein Token erreicht nie den Companion einer anderen Person.
• Behandle /openapi.json als Quelle der Wahrheit. Routen kommen laufend dazu; diese Seite dokumentiert die Form, keine erschöpfende Liste.

Nächste Schritte

• MCP Server
• CLI
• Verbinde deinen eigenen Modell-Key