BSQAI API

The tenant-aware backend API for AI applications, models, tools, speech, knowledge and managed-ingestion workflows.

Agentic Friendly

Component Category

API backend for AI, managed ingestion and tenant administration

Component Description

BSQAI API is the main backend service for Portal AI and managed-ingestion workflows. It integrates identity, tenant selection, model access, usage metering, retrieval, files, storage, tools, speech, code sandboxes, workflows, and observability behind product-facing HTTP and WebSocket APIs. Model installation is part of the same backend and deploys models through KServe.

Why It Is Used

In BullSequana AI, the BSQAI API gives applications one authenticated and authorized integration boundary. Clients do not need direct contracts with model servers, KServe, Docling, Milvus, or other internal services.

Learn More

API surfaces

The default public endpoint is https://api.<platform-domain>. The service exposes:

  • OpenAI-compatible Chat Completions (/v1/chat/completions), Responses, Models, Embeddings, and Rerank routes under /v1.
  • Anthropic-compatible Messages routes under /anthropic.
  • predictive model serving under /v1/serving-endpoints/{id}, with /infer, /invocations, and /http/{path}, and model access on the same prefix: publication, allow rules, Grant Managers, and owner transfer.
  • usage reports and monthly BCU budgets under /v1/usage.
  • API keys under /v1/api-keys and service accounts under /v1/service-accounts.
  • Agents under /v1/agents, Skills under /v1/skills, Deep Research under /api/v1/research, and code sandbox availability under /v1/sandbox.
  • files, folders, and sharing under /v1/files, collections under /v1/collections, and tenant configuration, including embedding reindexes, under /v1/config.
  • managed-ingestion definitions, connections, ingestions, schedules, state recovery and runs under /v1/data-connectors.
  • the data catalog under /v1/data-catalog.
  • tenant administration under /v1/admin/tenants, including each tenant's compute quota, GPU allocation, publishing, and deployment policy.
  • model connections and routes under /v1/admin/model-connections and /v1/admin/model-routes, platform configuration under /v1/admin/platform/configuration, and platform administrators under /v1/admin/platform-administrators, for platform administrators.
  • GPU usage under /v1/gpu-usage.
  • MLflow experiments, runs, registry, prompts, traces, and related operations under /v1/mlflow.
  • model installation, download tracking, and deployment health, pods, and logs under /v1/model-installer, and model presets and resource profiles under /v1/model-presets and /v1/resource-profiles.
  • MCP Server, credential, OAuth, and gateway routes under /v1/mcp.
  • web-search provider configuration and search execution under /v1/web-search.
  • batch and real-time speech-to-text, real-time text-to-speech, and live voice conversations.

JWT users with multiple Keycloak Organization memberships select a tenant with X-Tenant-Id. API keys are bound to one tenant when created and carry the permission scope chosen at creation. When the key's owner belongs to a group, the key names the group that funds its calls. Credential, data-connector, skill, and most tenant-management permissions can never be granted to a key. Applications that need their own identity use service accounts.

Managed ingestion

Studio data ingestion uses this backend for tenant-scoped connector registration, encrypted connection credentials, resource sharing, ingestion configuration and run diagnostics. A dedicated backend worker uses Temporal to coordinate Kubernetes execution; record batches do not flow through Temporal history.

These management routes require an authenticated user session, not an ordinary tenant API key. Functional permissions and resource relationships are checked together. See connector API integration for routes, asynchronous operations and execution identities.

AI-output provenance

Generative HTTP responses include X-AI-Generated and X-AI-Provenance. The structured provenance value records the resolved model, generation time, and backend producer. Browsers can read both headers through CORS.

MLflow and the active organization

/v1/mlflow routes use the MLflow of the active organization. The Global organization uses the installation's MLflow. A customer organization uses its private MLflow, provisioned by the BSQAI Tenant Operator, while its service state is ready. The API never answers from the Global MLflow or from another organization's MLflow in its place.

GET /v1/mlflow/capabilities reports the state for the active organization. Any member of the organization can call it, without an MLflow permission.

FieldValues
availabletrue when /v1/mlflow routes can serve the organization
scopeglobal or tenant
service_statedisabled, provisioning, ready, disabling, or failed

When MLflow cannot serve a request, the API returns 503 with one of these codes.

CodeCause
mlflow_not_enabledThe customer organization has no ready private MLflow. The detail reads "Your organisation does not have this service enabled, contact a tenant administrator to enable it".
mlflow_global_onlyThe feature works only in the Global organization. It covers the Model Installer routes download_s3_model and delete_model.
mlflow_workspaces_disabled, mlflow_webhooks_disabledA workspace or webhook route was called in a customer organization, or the tenant policy has the feature switched off.
mlflow_service_unavailableA platform fault, such as an unconfigured Global MLflow or tenant credentials that the API cannot read.

Model routing

The BSQAI API sends each generation, embedding, and rerank request to the model's server through the model's route. Platform administrators add routes for models that run at a cloud provider or on another server. See Cloud and external models.

Model call admission and usage

Before it forwards a request's first model call, the BSQAI API admits the call:

  1. It checks that the caller may use the model. The model must belong to the caller's organization or be offered to it. A customer organization that owns the model must still serve models, and, for a caller in another organization, a platform administrator must let it publish. An allow rule in the caller's organization must then name the caller, unless the caller is the model's owner. A refused call answers like a call to an unknown model. See Model access.
  2. It checks the monthly BCU caps of the member and, for an API key, of the group that funds the key. A reached cap refuses new calls with 429 usage_cap_reached; calls already admitted are not cut. See Usage budgets.
  3. It records the call as usage.

The BSQAI API writes one usage record for each tenant-attributed API request and for each model invocation. A record carries the tenant, the user, how the caller reached the platform (portal, api_key, user_session, or workload), the API key and its funding group, the reported application, and the model. It never holds a prompt, a response body, a credential, or a raw header. My usage, Analytics, Budgets, and /v1/usage read these records. See Usage analytics.

Model installation

Model registration creates or updates a KServe LLMInferenceService in the active organization's namespace and adds the model's route, so that the BSQAI API serves the model under its name. A customer organization deploys into its own namespace from its own MLflow, and its models are named <slug>/<name>. runtime_config_name selects a platform-managed CPU, GPU, or direct-S3-streaming runtime profile. Supported source schemes are hf://, pvc://, and s3://.

A registered MLflow model version deploys as a predictive KServe InferenceService with a route as well. Applications call it through /v1/serving-endpoints/{id}, in KServe's V2 inference protocol or MLflow's scoring format. See Use predictive models via API.

See Model Installer API.

Workloads and network policies

The BSQAI API release runs these workloads:

  • the API itself, which also serves the Portal's backend routes;
  • the MCP Gateway;
  • the telemetry authorizer, which resolves the storage scope a telemetry query may read for the telemetry query gateway;
  • Temporal workers for file ingestion, reindexing, Deep Research, skill publication, MCP and RAG reconciliation, tenant lifecycle, Keycloak synchronization, and managed ingestion;
  • Docling and Speaches;
  • the sandbox preview proxy, when the site enables the agent sandbox and its previews.

The [network_policy.workloads] table of the llm-backend component lists, for each workload, the services it may call. Each workload's NetworkPolicy admits only those services, and only workloads that call a service are admitted by it. Workloads that call external endpoints, such as model providers, web-search providers, and remote MCP servers, reach external_egress_cidrs on external_ports, 443 and 80 by default. The policies take effect only on a cluster that enforces network policies. See Network policies.

Interacts With

  • Keycloak, for authentication, Organization membership, and service identities.
  • OpenFGA, for tenant-scoped authorization and sharing decisions.
  • External model servers, such as cloud providers, for the models that administrators route to them.
  • KServe and vLLM, for model deployment and execution, in the kserve namespace or the organization's tenant namespace.
  • KAI Scheduler, whose tenant GPU queues bound the GPUs a customer organization's models use.
  • BSQAI Tenant Operator, which reconciles each tenant's runtime from the PlatformTenant resource the API writes.
  • MCP Gateway and MCP Lifecycle Operator, for governed tool calls and managed MCP Server workloads.
  • Milvus, for vector storage and semantic retrieval.
  • Docling, for document conversion and extraction workflows.
  • MLflow, for each organization's experiments and model registry, in the installation's MLflow or the organization's private MLflow, and for GenAI traces.
  • Speaches, for transcription and speech generation.
  • Agent Sandbox, for optional code execution in the coreai-sandboxes namespace.
  • Prometheus, which supplies the measurements for capacity-based BCU metering.
  • Rook-Ceph or external S3-compatible storage, for files, models, and artifacts.
  • PostgreSQL, for tenant-scoped application state.
  • Temporal, for tenant lifecycle, file processing, managed ingestion and other durable workflows.
  • OpenTelemetry, for application traces and metrics.

On this page