AI & Assistant

The AI assistant provides a real-time conversational interface. Conversations are persistent and grounded in your organization’s data.

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

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

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. Available models depend on the subscription tier.

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

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.