Knowledge Chat API

An AI chat widget that answers strictly from the Knowledge Base collections you choose, plus a server API to search the KB and manage documents and threads. Your sk_* key routes the request to your workspace (or paired sandbox for sk_test_*).

Scopes

Scope	Allows
`service.smart-chat.messages.send`	Send a message to the chatbot.
`service.smart-chat.threads.view`	View chat threads.
`service.smart-chat.threads.manage`	Manage chat threads.
`service.smart-chat.kb.view`	Search the Knowledge Base and list documents.
`service.smart-chat.kb.manage`	Manage Knowledge Base documents.
`service.smart-chat.agents.view`	View AI agents.
`service.smart-chat.agents.manage`	Manage AI agents.

Render the chat widget with one script tag. It answers only from the KB collections bound to that pk_* key, with the per-key title, colour and quick questions set in the dashboard.

<script src="https://app.softsolz.uk/softsolz.js"
  data-service-id="smart-chat"
  data-public-key="pk_live_…"
  data-mode="floating"></script>

data-mode="floating" gives a bottom-right bubble; omit it for an inline widget. See Embeds for the loader and allowlist rules.

Send a message (server)

POST /api/v1/services/smart-chat/messages · scope service.smart-chat.messages.send

curl -X POST https://app.softsolz.uk/api/v1/services/smart-chat/messages \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "message": "How do I reset my password?", "kb_only": true }'

This endpoint returns a single buffered JSON reply once the answer is fully generated; it does not stream.

Request body fields:

Field	Type	Required	Description
`message`	string	required	The user message / question (min length 1).
`history`	array	optional	Prior turns as `{ role, content }` pairs.
`collection_ids`	array	optional	KB collection ids to ground in. Falls back to the API key config when omitted.
`kb_only`	boolean	optional	When true (the default), answer strictly from the KB.
`include_citations`	boolean	optional	Whether to return page-level citations.

Response fields:

Field	Type	Description
`reply`	string	The assistant reply text.
`citations`	array	Page-level KB citations.
`usage`	object	Model token usage, e.g. `{ prompt_tokens, completion_tokens, total_tokens }`.
`model`	string \| null	Model that produced the reply.

Search the Knowledge Base (server)

POST /api/v1/services/smart-chat/kb/search · scope service.smart-chat.kb.view

curl -X POST https://app.softsolz.uk/api/v1/services/smart-chat/kb/search \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "query": "refund policy", "top_k": 5 }'

Returns matched chunks with citations and similarity scores.

Request body fields:

Field	Type	Required	Description
`query`	string	required	The search query (min length 1).
`top_k`	integer	optional	Max chunks to return, 1-50 (default 6).
`document_ids`	array	optional	Restrict to specific document ids.
`tags`	array	optional	Restrict to documents with these tags.
`folders`	array	optional	Restrict to these folders.

Response fields:

Field	Type	Description
`hits`	array	Matched chunks, each with `file_name`, `page_number`, `score`, `snippet` and `text`.
`model`	string \| null	Embedding model used.

Method & path	Scope	Does
`GET /api/v1/services/smart-chat/kb/documents`	`kb.view`	List Knowledge Base documents.
`POST /api/v1/services/smart-chat/kb/documents`	`kb.manage`	Upload a document.

API-key callers see only visibility=tenant documents.

Create an agent

POST /api/v1/services/smart-chat/agents · scope service.smart-chat.agents.manage

curl -X POST https://app.softsolz.uk/api/v1/services/smart-chat/agents \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "name": "AR Assistant",
        "instructions": "You are an AR assistant that helps chase overdue invoices.",
        "allowed_tables": ["invoices", "customers"] }'

Request body fields:

Field	Type	Required	Description
`name`	string	required	Agent name (max 120 chars).
`instructions`	string	required	System instructions / persona (max 8000 chars).
`description`	string \| null	optional	Short description (max 500 chars).
`allowed_tables`	array	optional	Tenant tables the agent may read (unknown names are dropped).
`visibility`	string	optional	One of `private`, `tenant`, `shared` (default `tenant`).
`shared_user_ids`	array	optional	Member ids (required when visibility is `shared`).
`shared_role_ids`	array	optional	Role ids (when visibility is `shared`).

Webhook events

Event	When
`smart-chat.message.received`	The chatbot answers a message.
`smart-chat.thread.created`	A new chat thread is opened.
`smart-chat.kb.document.ready`	A Knowledge Base document finishes processing.
`smart-chat.kb.document.failed`	A Knowledge Base document fails to process.
`smart-chat.agent.invoked`	An AI agent runs.

See Webhooks for payload + signature format.

Knowledge Chat API

Scopes

Chat widget

Send a message (server)

Search the Knowledge Base (server)

Create an agent

Webhook events