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.

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

ResultNext action
Authentication required or expiredRefresh or renew your Backbuild session, then retry with its access token. Do not substitute a provider key.
Permission or feature unavailableConfirm 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 requiredConnect 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 requestCorrect 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 failureHonor 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

ParameterTypeDescription
limitintegerMax results (1 to 100)
offsetintegerPagination 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

StatusMeaning
201Skill created; the full record is returned
400Validation error (missing/invalid field, an unknown body key, or a model not included in the active plan)
401Authentication required
403Caller lacks the required permission to create skills
500Unexpected 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

StatusMeaning
201Dataset created; the full record is returned
400Validation error (missing/invalid field, vector_count out of range, or an unknown distribution)
401Authentication required
403Caller lacks the benchmark permission
500Unexpected 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.