Management-API

Premium-Funktion

Über das Chatten hinaus kann ein Schlüssel mit passendem Geltungsbereich Ressourcen anlegen und konfigurieren: Agenten, Wissenssammlungen, Modelle, Aufgaben, Teams, 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, Teams, 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-Teams

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.

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, /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	ohne Token abrufbar (öffentlich)
GET	/api/tool-references/{id}	nur Administratoren

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.

Teams

Methode	Pfad	Scope
GET POST	/api/teams	team:manage
GET PUT DELETE	/api/teams/{id}	team:manage

Teams gelten workspace-weit, ein Schlüssel mit team:manage verwaltet daher jedes Team. Die Chat-Routen der Teams sind eine eigene Endnutzer-Oberfläche und nicht Teil der Management-API.

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.)

• Modelle auflisten und eine einzelne Werkzeugreferenz lesen (die lesenden Kataloge)
• Workflows auflisten, ändern und löschen (eine Anlege-Route gibt es nicht)
• GET /api/settings und 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