API-Überblick

Der Studio-Server stellt dieselbe REST API bereit, die auch die Web-UI nutzt. Dieses Dokument richtet sich an Integrationsentwickler, die diese API direkt aufrufen möchten.

Basisadresse

Alle Pfade beginnen unterhalb der Studio-Serveradresse mit /api.

https://<studio-host>/api/...

Authentifizierung

Das Session-Token wird im Header übertragen.

Authorization: Bearer <token>

Fehlt das Token oder ist es abgelaufen, antwortet der Server mit 401. Erhält die Web-UI eine 401, verwirft sie das gespeicherte Token und kehrt zum Anmeldebildschirm zurück. Für eigene Aufrufe wird dasselbe Vorgehen empfohlen — eine 401 lässt sich nicht durch Wiederholen beheben.

Antwortformat

Erfolgreiche Antworten kommen in einem data-Umschlag.

{
  "data": { "id": "prj_01H...", "name": "라인 모니터" }
}

Fehlerantworten enthalten ein errors-Array. Das message des ersten Eintrags ist die für Menschen lesbare Meldung.

{
  "errors": [
    { "code": "project_not_found", "message": "프로젝트를 찾을 수 없습니다." }
  ]
}

Clients werten am besten HTTP-Status und errors[0].message gemeinsam aus. Da der Server mitunter keine Meldung liefert, verwendet die Web-UI nur in diesem Fall einen eigenen Fallback-Text.

Streaming-Ereignisse

Der Fortschritt während der Arbeit des Agenten wird per Streaming übertragen. Das betrifft Konversationen (/api/session/{id}/message, /api/ask) und Benachrichtigungen (/api/notifications/stream).

Es gibt die folgenden sieben Ereignisse.

type	Enthaltener Wert	Bedeutung
assistant_text	text	Vom Agenten geschriebenes Textfragment
tool_call	name, input	Ein Werkzeug wurde aufgerufen
tool_result	name, ok, summary	Werkzeugergebnis. ok gibt den Erfolg an
file_change	path	Eine Datei wurde geändert
commit	hash, message	Änderung wurde committet
done	—	Dieser Turn ist beendet
error	message	Fehler bei der Verarbeitung

Es genügt, bis zum Eintreffen von done oder error zu lesen.

Anhänge

Anhänge wie Bilder werden base64-kodiert inline übertragen.

{
  "name": "설비사진.png",
  "mime": "image/png",
  "dataBase64": "iVBORw0KGgo..."
}

Dokumentaufbau

Dokument	Inhalt
Session	Lebenszyklus der Arbeitssession, Dateien, Historie, Rückgängigmachen
Projekte und Deployment	App-Erstellung, Deployment, Rollback, Runtime
Konversation	Konversation mit dem Agenten, Abfragehistorie
Skills	Vor-Ort-Skills registrieren, extrahieren, importieren
Platform-Anbindung	PlantPulse Platform-Datenexploration, semantische Suche
Administration	Einstellungen, Benutzer, Watcher, Audit, Benachrichtigungen