AI & Assistant
The AI assistant provides a real-time conversational interface. Conversations are persistent and grounded in your organization’s data.
Make a read-only first request
Start with a signed-in Backbuild session for the organization you intend to
use. Send its access token in the Authorization header for REST
requests. A provider API key is a separate credential: it does not sign you
in to Backbuild or give you access to an organization.
See API Authentication for the
sign-in and token lifecycle.
GET https://api.backbuild.ai/v1/assistant/conversations?limit=10&offset=0
Authorization: Bearer <access_token> A successful response lists the conversations you may access. An empty list is a valid result for a new account. This request reads history; it does not ask a model to generate a response or prove that your provider connection can run inference. Keep access tokens out of source control, screenshots, support messages, and request logs.
Choose how the AI work is paid for
Authentication, model availability, and payment are separate checks. Being signed in does not supply a provider credential, and having credits does not grant permission to use a model or feature.
| Choice | What to check before running work |
|---|---|
| Your own provider account or API key | Connect the account supported by the tool you are using. Confirm that the provider account has access to the selected model and can cover its usage. Provider charges and limits apply separately from Backbuild container runtime. |
| Backbuild usage credits | Use this choice where the Backbuild feature offers it and your organization permits it. Check the feature’s displayed availability and your usable balance before starting. Buying credits does not enable an unavailable funding option. |
A Virtual Worker’s coding tools in a container need a provider account you link, because Backbuild usage credits do not pay for those tools’ model inference. An In-app assistant worker can run on credits. Container runtime is a separate cost even when the agent uses your own provider account. See Virtual Worker AI and Budgets and Universal Usage Credits.
Check the model configuration
GET https://api.backbuild.ai/v1/ai-model-config
Authorization: Bearer <access_token> Where AI model configuration is available to your organization, read its current providers, models, and default model before choosing a model for your integration. Use the identifiers returned by your organization’s configuration. A model appearing in the catalog is not a successful inference test: the requested feature, permissions, provider credentials, and funding must also be available.
For the assistant experience and skills, see AI Assistant, Skills & Agents. If you publish a SaaS product, its separate package-level model controls are documented in AI Model Configuration.
Recover from a refused request
Inspect the response status and message before retrying. Keep the request identifier if one is returned, together with the time and endpoint, when asking for support. Remove credentials and private conversation content.
| Result | Next action |
|---|---|
| Authentication required or expired | Refresh or renew your Backbuild session, then retry with its access token. Do not substitute a provider key. |
| Permission or feature unavailable | Confirm the selected organization and ask its administrator to check your access and feature availability. Adding credits does not change permissions. |
| Provider sign-in or key required | Connect or renew your own account for that tool. Check the provider’s model access and balance; never paste its key into a conversation or support ticket. |
| Invalid request | Correct the field named in the response. For conversation lists, use a limit from 1 to 100 and a non-negative offset. |
| Rate limit or temporary failure | Honor a retry delay when supplied. Avoid an immediate retry loop, and check whether a state-changing operation completed before repeating it. |
WebSocket Connection
GET /v1/assistant/ws?token=YOUR_ACCESS_TOKEN Upgrade to a WebSocket connection for real-time assistant interaction. The access token is passed as a query parameter because the browser WebSocket API does not support custom headers during the upgrade handshake.
The connection maintains conversation state and streams responses in real time.
Security Notes
- Access tokens are short-lived
- The access token is fully validated on connection
- WSS (TLS) transport mandatory
List Conversations
GET /v1/assistant/conversations Query Parameters
| Parameter | Type | Description |
|---|---|---|
limit | integer | Max results (1 to 100) |
offset | integer | Pagination offset |
Get Conversation
GET /v1/assistant/conversations/:id Returns the full conversation history including all messages and assistant responses.
Custom Skills
GET /v1/skills List custom AI skills configured for the organization. Skills are reusable prompt templates with configurable model settings per pricing plan.
POST /v1/skills
Create a custom AI skill with a prompt template, model selection, and plan
gating. System-assigned fields (id, org_id,
version, created_at, updated_at) are
never supplied by the caller; the organization comes from the
authenticated session and the rest are assigned by the server.
Request Body
{
"name": "Summarize Spec",
"description": "Summarizes a specification document",
"skill_type": "agent",
"overall_prompt": "You are a helpful summarizer...",
"default_model": "..."
} Response
On success (201 Created) the complete created skill is returned.
{
"success": true,
"data": {
"id": "...",
"org_id": "...",
"name": "Summarize Spec",
"description": "Summarizes a specification document",
"skill_type": "agent",
"config": { /* prompt, model, and visibility settings */ },
"is_enabled": true,
"version": 1,
"created_by": "...",
"created_at": "2026-06-20T12:00:00Z",
"updated_at": "2026-06-20T12:00:00Z"
}
} Response Codes
| Status | Meaning |
|---|---|
201 | Skill created; the full record is returned |
400 | Validation error (missing/invalid field, an unknown body key, or a model not included in the active plan) |
401 | Authentication required |
403 | Caller lacks the required permission to create skills |
500 | Unexpected server error |
AI Model Configuration
GET /v1/ai-model-config Get the current AI model configuration for the organization.
PUT /v1/ai-model-config Update the AI model configuration when your organization and permissions allow it. Read the configuration back after saving to confirm the model and provider settings.
Semantic Search
Searchable content is indexed for semantic search. Content is indexed automatically in the background as soon as it is created or updated and is kept up to date without any manual action.
Vector Search Benchmarks
Generate synthetic datasets and benchmark vector-index techniques, then retrieve chart-ready results.
POST /v1/benchmarks/generate
Generate a synthetic vector dataset. This creates a benchmark dataset record.
System-assigned fields (id, org_id,
generated_at) are never supplied by the caller; the
organization comes from the authenticated session and the rest are assigned
by the server.
Request Body
{
"name": "Uniform 100k",
"vector_count": 100000,
"dimensions": 1024,
"distribution": "uniform"
} Response
On success (201 Created) the complete created dataset record is returned.
{
"success": true,
"data": {
"id": "...",
"org_id": "...",
"name": "Uniform 100k",
"description": "Synthetic uniform dataset with 100000 vectors of 1024 dimensions",
"vector_count": 100000,
"dimensions": 1024,
"distribution": "uniform",
"seed": null,
"generation_time_ms": 0,
"generated_at": "2026-06-20T12:00:00Z",
"created_at": "2026-06-20T12:00:00Z",
"updated_at": "2026-06-20T12:00:00Z"
}
} Response Codes
| Status | Meaning |
|---|---|
201 | Dataset created; the full record is returned |
400 | Validation error (missing/invalid field, vector_count out of range, or an unknown distribution) |
401 | Authentication required |
403 | Caller lacks the benchmark permission |
500 | Unexpected server error |
POST /v1/benchmarks/run
Run a benchmark suite against a dataset across the selected index techniques.
This executes a run and returns the run summary (200 OK);
detailed results are retrieved via GET /v1/benchmarks/results.
GET /v1/benchmarks/results List benchmark results for the organization.
GET /v1/benchmarks/runs/:runId/charts Get chart data for a benchmark run.