Management-API
Über das Chatten hinaus kann ein Schlüssel mit passendem Geltungsbereich Ressourcen anlegen und konfigurieren: Agenten, Wissenssammlungen, Modelle, Aufgaben, Schwärme, Webhooks und Zeitpläne. Damit richten Sie BasePeak.AI aus dem Code ein, statt sich durch die Admin-Oberfläche zu klicken.
Die OpenAPI-Spezifikation ist die Referenz
Jede Instanz liefert ihre eigene maschinenlesbare Spezifikation aus, erzeugt aus derselben Tabelle, die auch die Routenregistrierung steuert – sie kann daher nicht von dem abweichen, was der Server tatsächlich anbietet:
curl -sS https://your-instance.platform.basepeak.ai/api/openapi.json
curl -sS https://your-instance.platform.basepeak.ai/api/openapi.yaml
Beide sind ohne Authentifizierung erreichbar. Ziehen Sie sie jeder Tabelle in dieser Dokumentation vor, wenn beide sich bei Form von Anfrage oder Antwort widersprechen: Die Spezifikation ist generiert, der Text hier von Hand geschrieben.
Die Spezifikation deckt alles ab, was ein API-Schlüssel erreichen kann –
nicht nur die Management-Routen dieser Seite. Die Operationen sind nach
Oberfläche gruppiert (tags):
| Tag | Inhalt | Seite |
|---|---|---|
Chat | Invoke-API: einen Zug an einen Agenten senden | Invoke-API |
OpenAI | OpenAI-kompatible Routen unter /v1 | OpenAI-kompatible API |
Threads | Unterhaltungen auflisten, lesen, Ereignisse erneut abspielen, abbrechen | Threads |
Files | Arbeitsbereich-Dateien an Agent und Unterhaltung | Dateien |
Projects | Projektbezogener Chat, Arbeitsbereich, Wissen, Umgebung, Aufgaben | Projekte |
Management | Der Katalog: Agenten, Wissenssammlungen, Modelle, Werkzeuge, Aufgaben, Schwärme, Auslöser | diese Seite |
Nicht enthalten ist das Anlegen von Schlüsseln (/api/account/apikeys):
Das ist bewusst an eine angemeldete Sitzung gebunden und weist API-Schlüssel
ab, eine Aufnahme in die Spezifikation würde also einen garantierten 403
dokumentieren. Schlüssel entstehen in der Oberfläche – siehe
API-Schlüssel.
Jede Operation trägt die Erweiterung x-required-scope mit dem benötigten
Scope – admin bedeutet, dass kein Schlüssel sie erreicht.
Zwei Routen-Schreibweisen sind absichtlich nicht in der Spezifikation:
/api/invoke/{id}/thread/{thread} (Singular) und die /file/-Varianten der
Datei-Routen. Sie funktionieren weiterhin, sind aber gleichwertige Altformen
der dokumentierten Plural-Schreibweise; beide aufzuführen würde jeden
generierten Client verdoppeln, ohne eine einzige neue Fähigkeit zu ergänzen.
Einen typisierten Client zu generieren ist der vorgesehene Weg:
# Python
openapi-python-client generate --url https://your-instance.platform.basepeak.ai/api/openapi.json
# TypeScript
npx openapi-typescript https://your-instance.platform.basepeak.ai/api/openapi.json -o bpai.d.ts
# Go
oapi-codegen -package bpai <(curl -sS https://your-instance.platform.basepeak.ai/api/openapi.yaml) > bpai.gen.go
Management-Scopes
Neun Management-Berechtigungen lassen sich in einen Schlüssel aufnehmen. Jede
ist ein Paar resource:action, das die ersten beiden Segmente eines Scopes
bildet:
| Scope | Erlaubt |
|---|---|
agent:create:* | Agenten anlegen, auflisten, lesen, kopieren, exportieren und importieren |
agent:update:* | Agenten ändern: Manifest, Standard-Kennzeichen, Zuordnung von Wissenssammlungen, Berechtigungen |
agent:delete:* | Agenten löschen |
knowledgeset:manage:* | Vollständiger Lebenszyklus von Wissenssammlungen, Dateien, Im- und Exporte |
tool-reference:manage:* | Werkzeuge und MCP-Server registrieren, ändern, löschen, aktualisieren |
model-provider:manage:* | Modelle verwalten sowie Modellanbieter konfigurieren und prüfen |
trigger:manage:* | Webhooks, E-Mail-Empfänger und Cronjobs |
task:manage:* | Aufgaben und Aufgabenausführungen |
team:manage:* | Agenten-Schwärme |
Management-Scopes müssen * im ID-Segment verwenden – mit einer Ausnahme,
siehe unten. Zum Anlegen eines Schlüssels müssen Sie die zugrunde liegende
Berechtigung aktuell selbst besitzen; ein Schlüssel kann daher nie mehr
gewähren, als das erstellende Konto besitzt.
Einen Schlüssel auf einen Agenten festlegen
agent:update ist die einzige Management-Berechtigung, die eine konkrete ID
statt * akzeptiert:
| Scope | Reichweite |
|---|---|
agent:update:* | Darf jeden Agenten ändern, den das zugehörige Konto ändern darf |
agent:update:a17jlm7 | Darf nur Agent a17jlm7 ändern |
Jede agent:update-Route trägt den Agenten als ersten Pfadparameter, sodass
die festgelegte ID pro Anfrage geprüft wird – ein festgelegter Schlüssel
erhält bei jedem anderen Agenten 403.
In beiden Fällen wirkt der Schlüssel mit den Rechten, die sein Konto zum
Zeitpunkt der Anfrage auf dem Agenten hat: der globalen Berechtigung
agent:update (auf nicht beschränkten Agenten) oder einer Bearbeiter- bzw.
Besitzerrolle. Verliert das Konto diese Rechte, verliert sie auch der Schlüssel.
Das existiert für den Fall des sich selbst verbessernden Agenten: Ein Agent, der seine eigenen Anweisungen umschreibt, sollte einen Schlüssel besitzen, der ihn selbst ändern darf und nichts sonst.
{
"name": "self-improve",
"scopes": ["agent:chat:a17jlm7", "agent:update:a17jlm7"]
}
Ein Schlüssel darf mehrere Scopes tragen; es gibt keine Begrenzung auf einen.
Der Routenkatalog
Die Management-Routen für Schlüssel, nach Ressource gruppiert. {…} sind
Pfadparameter.
Agenten
| Methode | Pfad | Scope |
|---|---|---|
POST | /api/agents | agent:create |
GET | /api/agents | agent:create |
GET | /api/agents/{id} | agent:create |
PUT | /api/agents/{id} | agent:update |
DELETE | /api/agents/{id} | agent:delete |
POST | /api/agents/{id}/copy | agent:create |
GET | /api/agents/{id}/export | agent:create |
POST | /api/agents/import | agent:create |
PUT | /api/agents/{id}/setdefault | agent:update |
POST | /api/agents/{id}/knowledge-sets/{knowledge_set_id}/attach | agent:update |
DELETE | /api/agents/{id}/knowledge-sets/{knowledge_set_id}/detach | agent:update |
GET | /api/agents/{id}/authorizations | agent:create |
POST | /api/agents/{id}/authorizations/add | agent:update |
POST | /api/agents/{id}/authorizations/remove | agent:update |
Export und Import verwenden einen Agenten-Umschlag in YAML oder JSON, sodass ein Agent als Datei zwischen Instanzen verschoben werden kann.
Wissenssammlungen
| Methode | Pfad | Scope |
|---|---|---|
POST GET | /api/knowledge-sets | knowledgeset:manage |
GET PUT DELETE | /api/knowledge-sets/{id} | knowledgeset:manage |
GET | /api/knowledge-sets/{id}/knowledge-files | knowledgeset:manage |
POST DELETE | /api/knowledge-sets/{id}/knowledge-files/{file...} | knowledgeset:manage |
POST GET | /api/knowledge-sets/{id}/exports | knowledgeset:manage |
GET DELETE | /api/knowledge-sets/{id}/exports/{export_id} | knowledgeset:manage |
POST GET | /api/knowledge-set-imports | knowledgeset:manage |
GET DELETE | /api/knowledge-set-imports/{import_id} | knowledgeset:manage |
Modelle und Anbieter
| Methode | Pfad | Scope |
|---|---|---|
POST | /api/models | model-provider:manage |
PUT DELETE | /api/models/{id} | model-provider:manage |
GET | /api/models | eines von agent:create, agent:update, model-provider:manage (oder eine angemeldete Sitzung) |
GET | /api/models/{id} | nur Administratoren |
GET | /api/model-providers | model-provider:manage |
GET | /api/model-providers/{model_provider_id} | model-provider:manage |
POST | /api/model-providers/{id}/configure | model-provider:manage |
POST | /api/model-providers/{id}/validate | model-provider:manage |
configure und validate erwarten eine flache Zuordnung von
Umgebungsvariablen als Anfragekörper.
Werkzeuge und MCP-Server
| Methode | Pfad | Scope |
|---|---|---|
POST | /api/tool-references | tool-reference:manage |
PUT DELETE | /api/tool-references/{id} | tool-reference:manage |
POST | /api/tool-references/{id}/force-refresh | tool-reference:manage |
POST | /api/tool-references/test-mcp | tool-reference:manage |
GET | /api/tool-references | eines von agent:create, agent:update, tool-reference:manage (oder eine angemeldete Sitzung); ohne tool-reference:manage enthält die MCP-Server-URL nur Schema und Host, Header-Werte fehlen |
GET | /api/tool-references/{id} | wie die Liste; MCP-Konfiguration wie oben gekürzt ohne tool-reference:manage |
Einen entfernten MCP-Server zu registrieren ist ein Anlegen unter
tool-references – MCP-Server werden als Werkzeuge modelliert und nicht als
eigene Ressource.
POST /api/tool-references/test-mcp prüft einen Server-Kandidaten, bevor Sie
ihn speichern. Senden Sie {"url": "https://…"}; die Antwort enthält
reachable, authRequired, dcrSupported und einen detail-Text, sodass ein
Bereitstellungsskript bei einem nicht erreichbaren Endpunkt früh abbrechen kann.
Aufgaben
| Methode | Pfad | Scope |
|---|---|---|
GET | /api/tasks | task:manage |
GET PUT DELETE | /api/tasks/{id} | task:manage |
POST | /api/tasks/{id}/run | task:manage |
GET | /api/tasks/{id}/runs | task:manage |
GET DELETE | /api/tasks/{id}/runs/{run_id} | task:manage |
Ein Schlüssel mit task:manage sieht nur die Aufgaben des zugehörigen Kontos;
die Gesamtsicht ist Administratoren mit Browser-Sitzung vorbehalten.
POST /{id}/run erwartet freies JSON als Eingabe ({} für keine) und liefert
die Ausführung zurück – praktisch, um eine bestehende Aufgabe aus einer
CI-Pipeline auszulösen.
Schwärme
| Methode | Pfad | Scope |
|---|---|---|
GET POST | /api/teams | team:manage |
GET PUT DELETE | /api/teams/{id} | team:manage |
Schwärme sind privat: Sie gehören der Person, die sie erstellt hat, und die
Routen liefern ohne weiteres nur deren eigene Schwärme. team:create genügt, um
eigene Schwärme anzulegen, zu ändern und zu löschen; team:manage ergänzt
GET /api/teams?all=true (alle Schwärme auflisten) und das Löschen fremder
Schwärme – nie aber Lesen oder Chatten in ihnen. Die Felder hopCap und
costCeiling (0 = unbegrenzt) begrenzen eine Gesprächsrunde. Die Chat-Routen
der Schwärme sind eine eigene Endnutzer-Oberfläche und nicht Teil der Management-API.
Teams
Premium-FunktionDie Routen der Teams (Gruppen von Menschen mit
gemeinsamem Arbeitsbereich; im Code spaces) bedient die Oberfläche mit einer
Browser-Sitzung. Die Team-Routen sind ausschließlich für Browser-Sitzungen
gedacht und werden für API-Schlüssel abgelehnt; es gibt dafür keinen eigenen
Management-Scope. Was ein API-Schlüssel sonst erreicht, steht in
/api/openapi.json. Alle Routen sind
funktionsgebunden (pro Instanz freizuschalten) und prüfen die Mitgliedschaft im
Handler: Wer kein Mitglied ist, erhält 404.
| Methode | Pfad | Zweck |
|---|---|---|
GET POST | /api/spaces | Eigene Teams auflisten (inklusive des Persönlichen Teams) bzw. ein Team anlegen – je nach Einstellung „Wer Teams erstellen darf“ |
GET | /api/spaces/can-create | Darf der Aufrufer Teams erstellen? |
GET | /api/spaces/principals | Benutzer und Gruppen für die Admin-Konsole (space:manage) |
GET PUT DELETE | /api/spaces/{space_id} | Ein Team lesen, ändern, löschen (Löschen nur Admins) |
GET POST | /api/spaces/{space_id}/members | Mitglieder auflisten, hinzufügen |
PUT DELETE | /api/spaces/{space_id}/members/{member_id} | Rolle ändern, Mitglied entfernen |
GET | /api/spaces/{space_id}/groups-available | Gruppen, die sich hinzufügen lassen |
GET POST | /api/spaces/{space_id}/agents | Dem Team zugewiesene Agenten auflisten, einen Agenten zuweisen |
GET | /api/spaces/{space_id}/agents/grantable | Agenten, die sich zuweisen lassen |
DELETE | /api/spaces/{space_id}/agents/{agent_id} | Zuweisung eines Agenten aufheben |
GET POST | /api/spaces/{space_id}/invitations | Einladungen auflisten, einen Einladungslink erzeugen |
DELETE | /api/spaces/{space_id}/invitations/{code} | Einladung widerrufen |
GET | /api/space-invitations/{code} | Eine Einladung ansehen (der Code ist die Berechtigung) |
POST | /api/space-invitations/{code}/accept | Einladung annehmen |
POST | /api/spaces/{space_id}/projects/{project_id}/move | Ein Projekt in das Team verschieben |
* | /api/spaces/{space_id}/projects/{project_id}/... | Die Projekt-Routen im Kontext des Teams (404, wenn das Projekt nicht zum Team gehört) |
GET PUT | /api/settings/workspaces | „Wer Teams erstellen darf“ lesen und ändern (creationMode: off, everyone, groups; plus creationGroups) |
GET | /api/catalog/agents | Agenten im Team-Katalog |
PUT | /api/agents/{id}/catalog | Einen Agenten im Katalog freigeben (nur Administratoren) |
Chats in einem Team bleiben privat; weder diese Routen noch Team-Admins geben Einsicht in die Chats anderer Mitglieder.
Auslöser
| Methode | Pfad | Scope |
|---|---|---|
POST GET | /api/webhooks | trigger:manage |
GET PUT DELETE | /api/webhooks/{id} | trigger:manage |
POST GET | /api/email-receivers | trigger:manage |
GET PUT DELETE | /api/email-receivers/{id} | trigger:manage |
POST GET | /api/cronjobs | trigger:manage |
GET PUT DELETE | /api/cronjobs/{id} | trigger:manage |
Anlegen und Ändern von Webhooks akzeptieren neben dem Manifest ein Feld
token, das nur geschrieben und beim Lesen nie zurückgegeben wird.
Beispiel: einen Agenten vollständig bereitstellen
Mit einem Schlüssel, der agent:create:*, agent:update:*,
knowledgeset:manage:* und agent:chat:* trägt:
import httpx, pathlib
api = httpx.Client(
base_url="https://your-instance.platform.basepeak.ai",
headers={"Authorization": f"Bearer {TOKEN}"},
timeout=60,
)
# 1. Den Agenten anlegen.
agent = api.post("/api/agents", json={
"name": "Support-Assistent",
"description": "Beantwortet Fragen aus dem Support-Handbuch",
"prompt": "Du bist ein Support-Assistent. Antworte nur aus deinem Wissen.",
}).raise_for_status().json()
agent_id = agent["id"]
# 2. Eine Wissenssammlung anlegen.
ks = api.post("/api/knowledge-sets", json={
"name": "Support-Handbuch",
}).raise_for_status().json()
ks_id = ks["id"]
# 3. Dokumente hochladen – roher Anfragekörper, Dateiname im Pfad.
for doc in pathlib.Path("handbuch").glob("*.pdf"):
api.post(f"/api/knowledge-sets/{ks_id}/knowledge-files/{doc.name}",
content=doc.read_bytes(),
headers={"Content-Type": "application/pdf"}).raise_for_status()
# 4. Die Sammlung dem Agenten zuordnen.
api.post(f"/api/agents/{agent_id}/knowledge-sets/{ks_id}/attach").raise_for_status()
# 5. Verwenden. Die Verarbeitung läuft asynchron – planen Sie Zeit ein,
# bevor Sie mit Abruf aus dem Wissen rechnen.
answer = api.post(f"/api/invoke/{agent_id}",
headers={"Accept": "application/json",
"Content-Type": "text/plain"},
content="Wie lange ist unsere Rückgabefrist?").raise_for_status().json()
print("".join(e.get("content", "") for e in answer["items"]))
Die Feldnamen für AgentManifest, KnowledgeSetManifest und die übrigen
Typen stammen aus der Spezifikation – prüfen Sie /api/openapi.json für Ihre
Version, statt sie von hier zu übernehmen.
Was Administratoren vorbehalten bleibt
Kein API-Schlüssel erreicht das Folgende, unabhängig von seinen Scopes – es
erfordert eine Administrator-Sitzung im Browser. (Was davon in der
Spezifikation steht, trägt x-required-scope: admin; einiges steht dort gar
nicht.)
- Ein einzelnes Modell lesen (
GET /api/models/{id}) - Workflows auflisten, ändern und löschen (eine Anlege-Route gibt es nicht)
GET /api/settingsund alle Instanzeinstellungen- Verwaltung von Benutzerkonten, Gruppen und Authentifizierungsanbietern
- API-Schlüssel ausstellen – ein Schlüssel kann keine weiteren Schlüssel erzeugen
Wer über settings:manage verfügt, kann fünf operative Feineinstellungen über
PUT /api/settings/runtime schreiben (Synchronisierungs-/Verarbeitungs-Zeitlimits,
das Ingestion-Limit und die maximale Importgröße). Platzkontingente
(max_users) und Funktionsmerkmale bleiben schreibgeschützt und werden vom
Abonnement gesteuert: Es gibt keine Route, über die eine Instanz ihre eigenen
Grenzen erhöhen könnte.
Weiterführende Dokumentation
- API-Schlüssel – Scope-Grammatik und Ausstellung
- Dateien – Uploads in Wissenssammlungen im Detail
- Invoke-API – die bereitgestellten Agenten ausführen