DocsDocs

API-Referenz

API-Referenz

Öffentliche API-Familien, Authentifizierung und Konventionen, abgeleitet aus Route Map und Routendateien.

Status

Authentifizierung

Die öffentlichen /api/v1 Endpunkte erwarten einen OIDC Bearer Token oder einen passenden API-Schlüssel mit Scope. Tenant, User und Rolle werden serverseitig aus dem geprüften Token, dem API-Schlüssel oder gespeicherten Mitgliedschaften abgeleitet.

curl
curl https://api.oap.exoscale.cloud/api/v1/agents \
  -H "Authorization: Bearer $TOKEN"

Basis und Konventionen

Die API-Basis ist /api/v1. Der Ingress leitet Pfadfamilien an Services wie oap-iam, oap-agent-mgmt, oap-runtime, oap-knowledge, oap-tools, oap-models und oap-governance. Fehler erscheinen in den Routendokumenten überwiegend als feste Error-Codes mit Message. Pagination und Filter sind pro Service implementiert und nicht als ein globales Format zu erfinden.

Tenant-Kontext wird nicht als vertrauenswürdiger Body-Wert behandelt. Clients verwenden den gesetzten Login-Kontext, API-Key-Scope oder explizit erlaubte Tenant-Auswahl.

Agent Management

GET/api/v1/agentsoap-agent-mgmt

Agenten des aktuellen Kontextes listen.

POST/api/v1/agentsoap-agent-mgmt

Agent anlegen oder Entwurf erstellen, abhängig von Rolle und Servicevalidierung.

GET/api/v1/agents/:idoap-agent-mgmt

Agentendetails abrufen.

PATCH/api/v1/agents/:idoap-agent-mgmt

Agentendaten aktualisieren.

POST/api/v1/agents/:id/deployoap-agent-mgmt

Agent freigeben oder bereitstellen, wenn Gates erfüllt sind.

Runtime und Sessions

GET/api/v1/sessionsoap-runtime

Chat-Sitzungen listen.

POST/api/v1/sessionsoap-runtime

Sitzung erstellen.

POST/api/v1/sessions/:id/messagesoap-runtime

Nachricht senden, Streaming läuft über die Runtime-Routen.

GET/api/v1/open-botoap-runtime

Open-Bot-Flächen und Kontext abrufen.

POST/v1/chat/completionsoap-runtime

OpenAI-kompatibler Chat-Completions-Endpunkt.

Wissen und Dateien

GET/api/v1/knowledge-basesoap-knowledge

Wissensbasen listen.

POST/api/v1/knowledge-basesoap-knowledge

Wissensbasis anlegen.

GET/api/v1/vector-storesoap-knowledge

Vektor-Stores abrufen.

POST/api/v1/file-searchoap-knowledge

Dateisuche ausführen.

Werkzeuge, Kanäle und Verbindungen

GET/api/v1/toolsoap-tools

Werkzeugkatalog abrufen.

GET/api/v1/connectionsoap-tools

Verbindungen listen, wenn Connections aktiviert ist.

POST/api/v1/connections/oauth/startoap-tools

OAuth-Fluss für eine Verbindung starten.

POST/api/v1/connections/oauth/callbackoap-tools

OAuth-Callback aus der Web-Callback-Seite abschließen.

DELETE/api/v1/connections/:idoap-tools

Verbindung lokal widerrufen und Vendor-Revocation versuchen.

IAM und Governance

GET/api/v1/auth/verifyoap-iam

Token prüfen.

GET/api/v1/tenantsoap-iam

Mandanten im erlaubten Kontext listen.

GET/api/v1/usersoap-iam

Nutzerverwaltung, rollenabhängig.

GET/api/v1/auditoap-iam

Audit-Ereignisse lesen.

GET/api/v1/guardrailsoap-governance

Guardrail-Konfiguration abrufen.

GET/api/v1/cost-reportingoap-governance

Kosten- und Verbrauchsdaten abrufen.

Modelle und Gateway

GET/api/v1/models/catalogoap-models

Modellkatalog abrufen.

GET/api/v1/models/registrationsoap-models

Registrierte Modelle abrufen.

GET/api/v1/tenant-gatewayoap-models

Tenant-Gateway-Konfiguration.

GET/v1/modelsoap-runtime

OpenAI-kompatible Modellliste.

Aus dem Quellcode erzeugt: commit 04b00786

Grundlage im Repository
  • docs/platform/route-map.md
  • apps/oap-iam/src/routes/auth.ts
  • apps/oap-agent-mgmt/src/routes
  • apps/oap-runtime/api/src/routes/sessions
  • apps/oap-knowledge/api/src/routes
  • apps/oap-tools/src/connections/oauth/routes.ts

API reference

API reference

Public API families, authentication and conventions, derived from the route map and route files.

Status

Authentication

Public /api/v1 endpoints expect an OIDC bearer token or a suitable scoped API key. Tenant, user and role are derived server side from the verified token, API key or stored memberships.

curl
curl https://api.oap.exoscale.cloud/api/v1/agents \
  -H "Authorization: Bearer $TOKEN"

Base URL and conventions

The API base is /api/v1. Ingress routes path families to services such as oap-iam, oap-agent-mgmt, oap-runtime, oap-knowledge, oap-tools, oap-models and oap-governance. Errors in the route documents mostly use fixed error codes with messages. Pagination and filters are implemented per service and should not be invented as one global format.

Tenant context is not trusted from a body value. Clients use the selected login context, API-key scope or an explicitly allowed tenant selection.

Agent management

GET/api/v1/agentsoap-agent-mgmt

List agents in the current context.

POST/api/v1/agentsoap-agent-mgmt

Create an agent or draft, depending on role and service validation.

GET/api/v1/agents/:idoap-agent-mgmt

Read agent details.

PATCH/api/v1/agents/:idoap-agent-mgmt

Update agent data.

POST/api/v1/agents/:id/deployoap-agent-mgmt

Deploy or release an agent when gates are satisfied.

Runtime and sessions

GET/api/v1/sessionsoap-runtime

List chat sessions.

POST/api/v1/sessionsoap-runtime

Create a session.

POST/api/v1/sessions/:id/messagesoap-runtime

Send a message, with streaming handled by runtime routes.

GET/api/v1/open-botoap-runtime

Read Open Bot surfaces and context.

POST/v1/chat/completionsoap-runtime

OpenAI-compatible chat completions endpoint.

Knowledge and files

GET/api/v1/knowledge-basesoap-knowledge

List knowledge bases.

POST/api/v1/knowledge-basesoap-knowledge

Create a knowledge base.

GET/api/v1/vector-storesoap-knowledge

Read vector stores.

POST/api/v1/file-searchoap-knowledge

Execute file search.

Tools, channels and connections

GET/api/v1/toolsoap-tools

Read the tool catalog.

GET/api/v1/connectionsoap-tools

List connections when Connections is enabled.

POST/api/v1/connections/oauth/startoap-tools

Start an OAuth flow for a connection.

POST/api/v1/connections/oauth/callbackoap-tools

Complete OAuth callback from the web callback page.

DELETE/api/v1/connections/:idoap-tools

Revoke locally and attempt vendor revocation.

IAM and governance

GET/api/v1/auth/verifyoap-iam

Verify a token.

GET/api/v1/tenantsoap-iam

List tenants in the allowed context.

GET/api/v1/usersoap-iam

User management, role dependent.

GET/api/v1/auditoap-iam

Read audit events.

GET/api/v1/guardrailsoap-governance

Read guardrail configuration.

GET/api/v1/cost-reportingoap-governance

Read cost and usage data.

Models and gateway

GET/api/v1/models/catalogoap-models

Read the model catalog.

GET/api/v1/models/registrationsoap-models

Read registered models.

GET/api/v1/tenant-gatewayoap-models

Tenant gateway configuration.

GET/v1/modelsoap-runtime

OpenAI-compatible model list.

Generated from source: commit 04b00786

Repository sources
  • docs/platform/route-map.md
  • apps/oap-iam/src/routes/auth.ts
  • apps/oap-agent-mgmt/src/routes
  • apps/oap-runtime/api/src/routes/sessions
  • apps/oap-knowledge/api/src/routes
  • apps/oap-tools/src/connections/oauth/routes.ts