API-Überblick
BasePeak.AI bietet zwei Wege, per HTTP mit einem Agenten zu sprechen, sowie eine Management-Schnittstelle zum Anlegen und Konfigurieren von Ressourcen. Alle drei authentifizieren sich mit demselben Token mit eingeschränktem Geltungsbereich (siehe API-Schlüssel).
Welche Schnittstelle soll ich verwenden?
| Sie möchten … | Verwenden Sie | Seite |
|---|---|---|
| BasePeak.AI in Code einbinden, der bereits OpenAI spricht | POST /v1/chat/completions | OpenAI-kompatible API |
| Werkzeugaufrufe, Schritte und Rückfragen streamen – nicht nur Text | POST /api/invoke/{id} | Invoke-API |
| Einen langen Auftrag anstoßen, ohne die Verbindung offen zu halten | POST /api/invoke/{id}?async=true | Invoke-API |
| Mehrere unabhängige Unterhaltungen parallel führen | Thread-Adressierung auf beiden Schnittstellen | Threads |
| Einem Agenten Dokumente zur Verfügung stellen | Upload in eine Wissenssammlung | Dateien |
| Agenten, Wissenssammlungen oder Aufgaben anlegen | die Management-API | Management-API |
| Dieselbe Unterhaltung führen, die der Browser in einem Projekt führt – geteilter Arbeitsbereich, Aufgaben, Anmeldedaten, Modelleinstellungen inklusive | POST /api/projects/{project_id}/invoke | Projekte |
Kurz gesagt: Nutzen Sie /v1/chat/completions, wenn Sie einen
bestehenden OpenAI-Client haben, und /api/invoke/{id}, wenn Sie den
vollständigen Ereignisstrom des Agenten benötigen – Werkzeugaufrufe,
Schrittwechsel und OAuth-Rückfragen sind dort sichtbar, auf der
OpenAI-Schnittstelle absichtlich nicht.
Beide Schnittstellen führen denselben Agenten aus. Sie unterscheiden sich nur im Wire-Format.
Basis-URL
Jede Instanz läuft unter ihrem eigenen Hostnamen:
https://your-instance.platform.basepeak.ai
Die OpenAI-kompatiblen Routen liegen unter /v1/…, alles andere unter
/api/….
Authentifizierung in einer Minute
curl -sS https://your-instance.platform.basepeak.ai/api/invoke/a17jlm7 \
-H "Authorization: Bearer sk-bpai-1-42-…" \
-H "Content-Type: text/plain" \
--data 'Fasse unsere Rückgabebedingungen zusammen.'
Das Token erstellen Sie in der Oberfläche unter Profil → API-Schlüssel, beschränkt auf den Agenten, den Sie aufrufen möchten. Das vollständige Token-Modell, die Scope-Grammatik und der Audit-Verlauf stehen unter API-Schlüssel.
Ein Schlüssel mit nur agent:chat:… verliert stillschweigend jedes Werkzeug,
das ein gespeichertes Credential benötigt. Ergänzen Sie credential:use:*,
wenn Ihre Anbindung darauf angewiesen ist – siehe
Credential-Scopes.
Voraussetzung: API-Zugriff ist eine Premium-Funktion
Der programmatische API-Zugriff ist eine Premium-Funktion und über das
Merkmal apiAccess Ihrer Instanz freigeschaltet. Alles auf diesen Seiten
setzt ihn voraus. Ist er deaktiviert, gilt:
- Das Anlegen eines Schlüssels antwortet mit
403– API access is disabled for this instance - Die Nutzung eines bestehenden Schlüssels antwortet mit
403 auth/api-access-disabled
Das Merkmal wird über die Bereitstellung verwaltet (es folgt Ihrem Abonnement); es gibt keinen Schalter zur Selbstverwaltung – auch eine Workspace-Administratoren können es nicht in den Einstellungen aktivieren. Wenden Sie sich bei diesem Fehler an Ihren BasePeak.AI-Kontakt.
Was ein API-Schlüssel erreichen kann – und was nicht
Ein sk-bpai-…-Schlüssel ist auf eine ausdrückliche Positivliste von Routen
beschränkt,
unabhängig davon, was das zugehörige Konto im Browser tun könnte. Alles außerhalb
dieser Liste antwortet mit 403, selbst wenn die Scopes des Schlüssels
Zugriff nahelegen würden.
Mit einem Schlüssel erreichbar:
| Schnittstelle | Routen |
|---|---|
| Chat / Invoke | POST /api/invoke/{id}, POST /api/invoke/{id}/thread/{thread} (auch /threads/), POST /v1/chat/completions |
| Chat / Invoke in einem Projekt | POST /api/projects/{project_id}/invoke, POST /api/projects/{project_id}/invoke/thread/{thread} (auch /threads/) – siehe Projekte |
| Modell- und Embedding-Proxys | GET /v1/models, GET /v1/models/{id}, POST /v1/embeddings, POST /v1/audio/transcriptions |
| Agenten- und Thread-Dateien | GET /api/agents/{id}/files, GET/POST/DELETE /api/agents/{id}/files/{path}, GET /api/threads/{id}/files, GET/POST/DELETE /api/threads/{id}/files/{path} – siehe Dateien |
| Dateien, Wissen, Aufgaben und Umgebungsvariablen eines Projekts | /api/projects/{project_id}/files…, /api/projects/{project_id}/knowledge…, /api/projects/{project_id}/tasks…, /api/projects/{project_id}/env – siehe Projekte |
| Threads | GET /api/threads, GET /api/threads/{id}, GET /api/threads/{id}/events, POST /api/threads/{id}/abort – siehe Threads |
| Management | die unter Management-API aufgeführten Routen |
Mit einem Schlüssel nicht erreichbar – nur mit Browser-Sitzung:
| Nicht verfügbar | Konsequenz |
|---|---|
PUT /api/threads/{id}, DELETE /api/threads/{id} | Threads lassen sich über die API nicht umbenennen oder löschen. Lesen, Verlauf abspielen und Abbrechen sind möglich – siehe oben. |
| Projekt-Mitglieder, -Einladungen, -Anmeldedaten (Verwaltung) | Diese drei ändern, wer ein Projekt erreicht, oder geben gespeicherte Geheimnisse heraus – siehe Projekte. |
Diese Einschränkungen beschreiben das heutige Verhalten, keine dauerhafte Festlegung.
Maschinenlesbar: die OpenAPI-Spezifikation
Jede Instanz liefert eine OpenAPI-3.1-Spezifikation aus, die jede Operation
beschreibt, die ein Schlüssel erreichen kann – Chat, /v1, Unterhaltungen,
Dateien, Projekte und die Management-Routen:
curl -sS https://your-instance.platform.basepeak.ai/api/openapi.json
Ohne Authentifizierung erreichbar, erzeugt aus derselben Tabelle, die die Routen registriert. Wenn Sie einen Client generieren wollen statt Aufrufe von Hand zu schreiben, fangen Sie hier an: Management-API → Die OpenAPI-Spezifikation ist die Referenz.
Weiterführende Dokumentation
- API-Schlüssel – Tokens, Scopes, Audit
- OpenAI-kompatible API –
/v1/chat/completions - Invoke-API – der native Ereignisstrom
- Threads – mehrere Züge, mehrere Unterhaltungen
- Dateien – Dokumente an einen Agenten geben
- Management-API – Ressourcenverwaltung
- Projekte – die Unterhaltung, die der Browser führt, auch über die API