Chat

Build assistants that remember. chat.* operations create and continue persisted chats grounded in your documents and data, and manage their history.

Overview

Conversation powers Chat with Documents. Each chat keeps its messages, knowledge sources, and attachments, so users and agents can pick up where they left off.

Key features:

Persisted chats - History, titles, and bookmarks for chats and messages
Chat with Documents - Answers grounded in your documents and records, with citations
Retrieval - VectorDB embeddings and vector search, FTS5 keyword search, and hybrid retrieval through docsets
Attachments - Bring in uploaded files, URLs, or inline text
Modes - Free chat, cited answers (RAG), or strict knowledge-base answers
Models - Choose a model available in the deployed catalog

Use cases: Shopping and support assistants, document Q&A, onboarding guides, internal knowledge bots

On your website: The Chat Box web component embeds Chat with Documents in your site.

Access: chat.* operations are public: a valid project key is enough. Chats are scoped to the project and the user in the bearer token.

WARNING

Without a bearer token, a chat is not tied to any user. In browser and mobile apps, send the signed-in user's ID token with every chat.* request.

For one-off answers that are not saved, use chat.ask. It takes the same retrieval, attachments, and modes.

Operations

Operation	Description	Required payload
`chat.ask`	Ask without saving a conversation	`message`
`chat.prepare`	Prepare context and starter questions	None
`chat.send`	Start a conversation or continue one	`message`
`chat.list`	List conversations	None
`chat.get`	Get a conversation and its messages	Exactly one of `chat_id`/`_id` or `key`
`chat.update`	Rename or bookmark a conversation	`chat_id`, a change
`chat.bookmark`	Bookmark or unbookmark a conversation	`chat_id`, `bookmarked`
`chat.delete`	Delete a conversation	`chat_id`
`chat.bookmark_message`	Bookmark or unbookmark one message	`chat_id`, `message_id`, `bookmarked`
`chat.delete_message`	Delete one message	`chat_id`, `message_id`
`chat.remove_attachment`	Remove a saved attachment from a conversation	`chat_id`, `attachment_id`

chat_id also accepts the alias _id.

chat.ask

Get a single answer. Nothing is saved, so there is no history to manage.

json

{
  "operation": "chat.ask",
  "payload": {
    "message": "Explain an HTTP 429 response in one sentence."
  }
}

Example - Answer from a docset, by meaning:

json

{
  "operation": "chat.ask",
  "payload": {
    "message": "Something for a laptop and a daily commute",
    "mode": "rag",
    "retrieval": [{ "source": "docset", "ids": "products" }]
  }
}

Parameters:

Field	Description
`message`	The question (required)
`system_message`	System instructions
`mode`	`chat` (default), `rag`, or `kb`. See Modes
`retrieval`	Knowledge sources, such as docsets
`attachments`	Up to 5 attachments. Always one turn
`followups`	`true`, or 1 to 5, to suggest follow-up questions
`model`, `params`	Model and model parameters
`format`	`text`, `json`, or `markdown`

Retrieval and attachments apply to this request only. To keep a thread going, use chat.send.

chat.send

Send a message. Without chat_id, a new conversation starts. With chat_id, the conversation continues.

Example - Start a conversation:

json

{
  "operation": "chat.send",
  "payload": {
    "message": "Help me plan an API integration.",
    "title": "Integration planning",
    "system_message": "Be concise."
  }
}

The response includes the chat's _id.

Example - Continue it:

json

{
  "operation": "chat.send",
  "payload": {
    "chat_id": "chat_123",
    "message": "What should I build first?"
  }
}

Parameters:

Field	Description
`message`	The user's message (required)
`chat_id`	Continue an existing chat. Alias `_id`
`system_message`	System instructions
`title`	Chat title
`mode`	`chat` (default), `rag`, or `kb`. See Modes
`retrieval`	Knowledge sources. See Retrieval
`attachments`	Up to 5 attachments. See Attachments
`followups`	`true`, or 1 to 5, to suggest follow-up questions. Default `false`
`include_messages`	Include the message history in the response
`model`, `params`	Model and model parameters
`format`	`text`, `json`, or `markdown`
`metadata`	Custom chat metadata

Modes

mode controls how the answer uses retrieval sources and attachments.

Mode	Behavior
`chat`	Sources may help, and the model can also use general knowledge. Default
`rag`	The model prefers and cites sources. It may use general knowledge when sources don't answer, and says so
`kb`	The model answers only from sources and says when the answer isn't there. Requires at least one source or attachment

Use kb when answers must stay inside your content.

Retrieval

Ground answers in your data with retrieval. Each entry has a source.

Retrieval sent to chat.send is saved on the chat and applies to later turns until you replace it. Send retrieval: [] to clear it.

Docsets

A docset is a named knowledge base over your project collections. It is how agents and apps query your data by meaning or by keyword. Project admins create docsets in the console; apps and agents reference them by slug, without seeing collection names or filters.

What a docset defines:

Setting	Description
`slug`, `name`	How you reference it, for example `products`
`collections`	1 to 10 collections to search
`search`	`kdb` for FTS5 full-text search (default), or `vector` for vector retrieval with full-text fallback for other collections
`filter`, `document_ids`	Narrow the searchable records, for example `{"status": "published"}`
`limit`	Passages per answer, 1 to 20. Default `6`
`acl`	Who may use it: `admin`, `user` (default), `agent`, or `nobody`

Example - A shopping assistant searching by meaning:

json

{
  "operation": "chat.send",
  "payload": {
    "message": "Something for a laptop and a daily commute",
    "mode": "rag",
    "retrieval": [{ "source": "docset", "ids": "products" }]
  }
}

Example - A support assistant answering only from knowledge:

json

{
  "operation": "chat.send",
  "payload": {
    "message": "How do I cancel my plan?",
    "mode": "kb",
    "retrieval": [
      { "source": "docset", "ids": ["support", "billing"] }
    ]
  }
}

Rules:

ids takes one slug or ID, or a list of up to 5.
Docsets must exist, be enabled, and allow the caller. Agent keys count as agent.
Send IDs only. Embedded docsets definitions are rejected (INVALID_RETRIEVAL).
A missing, disabled, or inaccessible docset returns DOCSET_NOT_FOUND (HTTP 422).

Search and hybrid retrieval

Singlebase supports three retrieval paths for chat:

Search path	How it finds context
FTS5 full-text search	`search: "kdb"` docsets search collection text for words and phrases through the database full-text query path
VectorDB embeddings and vector search	`search: "vector"` docsets embed the question and search the project's indexed document chunks by similarity; Smart Bucket file content is searched through its file vectors
Hybrid retrieval	A vector docset combines vector results with full-text results from collections that have neither collection vector indexing nor Smart Bucket file sources. Multiple docsets can also combine keyword and semantic results in the same answer

The console labels the vector docset option Hybrid search. Its API value remains "vector"; docset search accepts only "kdb" or "vector". Vector mode uses full-text fallback for the other collections described above; it does not automatically run both searches over every indexed collection. Retrieved passages are combined as model context; there is no configurable keyword/vector weighting parameter in this API.

For example, create two accessible docsets in the console: support-keywords with search: "kdb", and support-semantic with search: "vector" over your indexed support collection. Then combine them:

json

{
  "operation": "chat.ask",
  "payload": {
    "message": "How do I fix error E104 when uploading a document?",
    "mode": "kb",
    "retrieval": [
      { "source": "docset", "ids": ["support-keywords", "support-semantic"] }
    ]
  }
}

Keyword retrieval finds the exact error code, while vector retrieval can find related troubleshooting text with different wording. Both docsets must exist and permit the caller. Collection embeddings must be available for vector retrieval; see Data overview.

Sources by key type

Caller	Allowed sources
Web key (`wk_`)	`docset`, `attachments`, `docs`, `json`, `csv`, `data`
Server or agent key	All of the above, plus `kdb`, `vector`, `s3`, `generate`

Raw collections, vector indexes, storage objects, and generated prompts need a trusted key. Public apps should use docsets.

type is accepted as an alias for source. If both are sent, they must match.

Attachments

Attach up to 5 items to a message.

json

{
  "operation": "chat.send",
  "payload": {
    "message": "Compare these documents.",
    "mode": "rag",
    "attachments": [
      {
        "type": "content",
        "name": "notes.txt",
        "mime": "text/plain",
        "content": "Version 2 adds file uploads and token rotation."
      },
      {
        "type": "file_id",
        "file_id": "7b21f51e730d40d0b0e373ef720e43d5",
        "name": "contract.pdf"
      },
      {
        "type": "url",
        "url": "https://example.com/terms",
        "save_attachment": false
      }
    ]
  }
}

Type	Required field	Optional fields	Rules
`content`	`content`	`name`, `mime`, `size`, `save_attachment`	Up to 512,000 UTF-8 bytes
`file_id`	`file_id`	`name`, `save_attachment`	A file the user owns. Admins can use any project file
`url`	`url`	`name`, `save_attachment`	HTTPS only

Behavior:

save_attachment defaults to true: the attachment stays available on later turns. Set it to false for one turn only.
The response may include data.attachments with each attachment's id, type, name, mime, size, saved, and status.
Extraction failures may appear as attachment-level errors. Payload validation and file ownership failures reject the request before the turn runs; FILE_FORBIDDEN is not an attachment that can simply be skipped.

chat.prepare

Prepare context before the first message, and optionally generate starter questions. Use the returned _id in a later chat.send.

json

{
  "operation": "chat.prepare",
  "payload": {
    "title": "Product support",
    "mode": "kb",
    "retrieval": [{ "source": "docset", "ids": "support" }],
    "starters": 3
  }
}

The support docset must exist, be enabled, and allow your caller. starters accepts true, false, or a count from 1 to 6. refresh can refresh starter generation; the response includes the prepared chat's state.

Chat keys

A key is a per-user application identifier, such as support-widget. It needs a signed-in user. chat.send and chat.prepare can use it to address a chat, and chat.get accepts exactly one of key or a chat ID. Keys are 1 to 128 characters, start with a letter or digit, and allow letters, digits, ., _, :, and -. chat.ask refuses key because it does not persist a chat.

Manage Conversations

Use the same credentials that created the chat.

chat.list

json

{
  "operation": "chat.list",
  "payload": {
    "bookmarked": true,
    "limit": 20,
    "offset": 0
  }
}

All fields are optional. Lists chats without their messages, most recently modified first.

chat.get

json

{
  "operation": "chat.get",
  "payload": { "chat_id": "chat_123" }
}

Returns the chat with its active messages, saved attachments, and mode.

chat.update

json

{
  "operation": "chat.update",
  "payload": {
    "chat_id": "chat_123",
    "title": "API integration checklist",
    "bookmarked": true
  }
}

Send title, bookmarked, or both.

chat.bookmark

json

{
  "operation": "chat.bookmark",
  "payload": { "chat_id": "chat_123", "bookmarked": true }
}

bookmarked is required. Use false to remove the bookmark.

chat.delete

json

{
  "operation": "chat.delete",
  "payload": { "chat_id": "chat_123" }
}

Deletes the chat and all its messages.

chat.bookmark_message

json

{
  "operation": "chat.bookmark_message",
  "payload": {
    "chat_id": "chat_123",
    "message_id": "msg_456",
    "bookmarked": true
  }
}

The message must belong to the chat.

chat.delete_message

json

{
  "operation": "chat.delete_message",
  "payload": { "chat_id": "chat_123", "message_id": "msg_456" }
}

The message must belong to the chat.

chat.remove_attachment

json

{
  "operation": "chat.remove_attachment",
  "payload": { "chat_id": "chat_123", "attachment_id": "att_789" }
}

Removes a saved attachment from the chat. The underlying file is not deleted; use files.delete for that.

Common Errors

Message	Meaning
`INVALID_PAYLOAD`	The payload does not match the operation
`KB_SOURCE_REQUIRED`	`kb` mode has no retrieval source or attachment
`RETRIEVAL_SOURCE_FORBIDDEN`	A web-key caller used a server-only source
`RETRIEVAL_SOURCE_MISMATCH`	`source` and `type` disagree
`DOCSET_NOT_FOUND`	A docset is missing, disabled, or not available to the caller
`INVALID_RETRIEVAL`	Invalid docset IDs, or the client sent docset definitions
`INVALID_QUERY_FOR_SOURCE`	The retrieval query does not fit its source
`ATTACHMENT_LIMIT`	More than 5 attachments, or too many on the chat
`ATTACHMENT_TOO_LARGE`	Inline or extracted attachment content is too large
`FILE_FORBIDDEN`	The user does not own the attached file
`LLM_REQUEST_FAILED`	The LLM service failed (HTTP 502)

Validation errors from the LLM service return HTTP 422 with the service's message. See Responses for the error envelope.

Next Steps

LLM - One-off answers, generation, and embeddings
Files - Upload documents to use as attachments
Data - Store the content your docsets search
Agents - Give AI agents scoped chat permissions

Compatibility

The former conversation.* namespace has been removed. Deprecated llm.* chat aliases remain available.

Vector docsets use the project index, combining indexed collection fields and attached Smart Bucket file text with full-text fallback. File text is embedded only once under __files. See Data overview.

Chat ​

Overview ​

Operations ​

chat.ask ​

chat.send ​

Modes ​

Retrieval ​

Docsets ​

Search and hybrid retrieval ​

Sources by key type ​

Attachments ​

chat.prepare ​

Chat keys ​

Manage Conversations ​

chat.list ​

chat.get ​

chat.update ​

chat.bookmark ​

chat.delete ​

chat.bookmark_message ​

chat.delete_message ​

chat.remove_attachment ​

Common Errors ​

Next Steps ​

Compatibility ​

Chat

Overview

Operations

chat.ask

chat.send

Modes

Retrieval

Docsets

Search and hybrid retrieval

Sources by key type

Attachments

chat.prepare

Chat keys

Manage Conversations

chat.list

chat.get

chat.update

chat.bookmark

chat.delete

chat.bookmark_message

chat.delete_message

chat.remove_attachment

Common Errors

Next Steps

Compatibility