API-Übersicht

Der Studio-Server stellt dieselbe REST-API bereit, die auch die Weboberfläche verwendet. Dieses Dokument richtet sich an Integrationsentwickler, die die API direkt aufrufen möchten.

Basisadresse

Die Studio-API lautet /api/v1.

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

Auch der alte Pfad /api/... funktioniert weiterhin (Alias). Beispiele in diesem Dokument, die noch mit /api/... angegeben sind, können weiterhin verwendet werden. Für neuen Code verwenden Sie jedoch /api/v1.

Nicht mit dem v5 der Plattform verwechseln

Es handelt sich nicht um zwei Versionen derselben API, sondern um unterschiedliche Produkte mit unterschiedlichen Listenern.

	Was	Pfad
Studio-API	Die API des Studios selbst (dieses Dokument)	/api/v1
Plattform-API	Ein Proxy, den von Studio erstellte Apps auf ihrer eigenen Herkunft aufrufen	/api/v5

Authentifizierung

Senden Sie das Sitzungstoken als Header.

Authorization: Bearer <token>

Wenn das Token fehlt oder abgelaufen ist, gibt der Server 401 zurück. Die Weboberfläche löscht bei 401 das gespeicherte Token und kehrt zum Anmeldebildschirm zurück. Bei direkten Aufrufen wird dasselbe Vorgehen empfohlen – 401 lässt sich nicht durch erneutes Senden beheben.

Antwortformat

Erfolgreiche Antworten werden in einer data-Hülle geliefert.

{
  "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": "프로젝트를 찾을 수 없습니다." }
  ]
}

Für den Client ist es sicher, den HTTP-Status zusammen mit errors[0].message zu betrachten. Es gibt Fälle, in denen der Server keine Meldung liefert; nur dann verwendet die Weboberfläche ihren eigenen Ersatztext.

Streaming-Ereignisse

Der Fortschritt, während der Agent arbeitet, wird per Streaming übertragen. Dazu gehören Konversationen (/api/session/{id}/message, /api/ask) und Benachrichtigungen (/api/notifications/stream).

Es gibt sieben Arten von Ereignissen.

type	Enthaltener Wert	Bedeutung
assistant_text	text	Textfragment, das der Agent geschrieben hat
tool_call	name, input	Ein Werkzeug wurde aufgerufen
tool_result	name, ok, summary	Werkzeugergebnis. ok gibt an, ob erfolgreich
file_change	path	Eine Datei wurde geändert
commit	hash, message	Die Änderung wurde committet
done	—	Diese Runde ist beendet
error	message	Fehler während der Verarbeitung

Lesen Sie, bis done oder error eintrifft.

Anhänge

Anhänge wie Bilder werden als base64 inline übertragen.

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

Dokumentationsstruktur

Dokument	Behandelt
Sitzung	Lebenszyklus von Arbeitssitzungen, Dateien, Verlauf, Rückgängig
Projekte und Bereitstellung	App-Erstellung, Bereitstellung, Rollback, Laufzeit
Konversation	Dialog mit dem Agenten, Abfrageverlauf
Fähigkeiten	Registrierung, Extraktion und Import von Feld-Fähigkeiten
Plattform-Integration	Datenbank der PlantPulse-Plattform, semantische Suche
Verwaltung	Einstellungen, Benutzer, Wächter, Audit, Benachrichtigungen