Canonical page: https://docs.singlebase.io/ Singlebase documentation # Give your agents a data foundation. Singlebase is a backend platform for applications and AI agents. It brings your data, files, users, and AI together through one JSON API. [>_ Make your first request Connect a project and use the REST API from your backend.](/quickstart) [{ } Connect an agent Give an agent access to the collections and operations it needs.](/agents) ## One platform, shared context Singlebase provides a JSON document database with VectorDB embeddings, vector search, FTS5 full-text search, and hybrid retrieval, plus file storage, user authentication and account management, AI generation and embeddings, and chat with retrieval from your knowledge sources. Your application and agents use these services through the same API, with access controlled by API keys and user permissions. ### Database Store JSON documents, compute totals, and find context with VectorDB embeddings, vector search, FTS5 full-text search, and hybrid retrieval. [DocumentDB reference →](/data) ### Agents & retrieval Scope agent keys by collection and operation, or connect over MCP. Ground chat answers in named docsets using vector, FTS5 keyword, or hybrid retrieval with access rules. [Agent access →](/agents) · [MCP →](/mcp-guide) · [Docsets →](/chat#docsets) ### Intelligence Generate and summarize content, extract structured JSON, create embeddings, and keep conversations. [LLM reference →](/llm) · [Chat reference →](/chat) ### Identity & storage Sign users in, manage their accounts, upload files, and convert documents to Markdown. [Authentication →](/auth) · [Files →](/files) ## One endpoint, one request shape Send a `POST` request to your project's endpoint with `X-API-KEY` and a JSON body: ```json { "operation": "data.query", "payload": { "collection": "product_catalog", "filter": { "category": "bags" }, "per_page": 5 } } ``` Use a server key from your backend, or an agent key with `read` permission on `product_catalog`. A web key needs a signed-in user's bearer token for this query and returns that user's documents. See [API keys and access](/api.md#api-keys). ## Choose your next step - [Quickstart](/quickstart.md): create a document and query it from server code. - [API overview](/api.md): request headers, key types, responses, errors, and batches. - [API reference](/api-reference.md): operations grouped by service. - [JavaScript SDK](/sdk-javascript.md): connect with `sbc.data`, `sbc.llm`, and `sbc.chat`; see the quickstart for JavaScript and Python. - [Data](/data.md) and [Query syntax](/queries.md): find and update your records. - [Agents](/agents.md): give an agent its own scoped access. - [MCP](/mcp-guide): connect agent runtimes with scoped discovery, document tools, and answers with sources. - [Conversation](/chat.md): use knowledge sources, attachments, and persisted chats. - [LLM](/llm.md): generate text, extract JSON, and create embeddings. - [Authentication](/auth.md), [Users](/users.md), and [Files](/files.md): build the application around your data. ## Documentation for AI tools Use [llms.txt](/llms.txt) for a compact reading guide, [llms-full.txt](/llms-full.txt) for the complete reference, or the Markdown link on each page for its plain-text source. Examples use placeholders and illustrative values; resource names must exist in your project. --- Canonical page: https://docs.singlebase.io/quickstart # Make your first API request Create a document and read it back using the same endpoint. This guide runs from your **backend or terminal** with a server key. Keep server and agent keys out of browser code. ## 1. Prepare your project In the [Singlebase console](https://console.singlebase.io), choose your project and create or select a `notes` collection. Copy the project API endpoint and an enabled server key from project settings. Set the credentials in your terminal environment or secret manager: ```sh export SINGLEBASE_API_URL='https://v1.api.singlebase.io/api/' export SINGLEBASE_SERVER_KEY='sk_' ``` Replace the placeholders with your own values. The snippets below use `notes`; use your actual collection name if it differs. ## 2. Check the request format Every operation is a JSON `POST` to the same URL. The operation name goes in `operation`; its parameters go inside `payload`. ```sh curl --fail-with-body "$SINGLEBASE_API_URL" \ -H 'Content-Type: application/json' \ -H "X-API-KEY: $SINGLEBASE_SERVER_KEY" \ --data '{"operation":"ping","payload":{}}' ``` Ping returns `data: "pong"`. It checks connectivity and request handling; it does not validate your project's credentials. The next request uses your project and collection. ## 3. Create a document ```sh curl --fail-with-body "$SINGLEBASE_API_URL" \ -H 'Content-Type: application/json' \ -H "X-API-KEY: $SINGLEBASE_SERVER_KEY" \ --data '{"operation":"data.insert","payload":{"collection":"notes","data":{"title":"First note","status":"active"}}}' ``` The created record receives an `_id`. With this server key and no bearer token, it has no user owner unless you assign an existing user with payload-level `_user_id`. See [Ownership](/data.md#ownership). ## 4. Read it back ```sh curl --fail-with-body "$SINGLEBASE_API_URL" \ -H 'Content-Type: application/json' \ -H "X-API-KEY: $SINGLEBASE_SERVER_KEY" \ --data '{"operation":"data.query","payload":{"collection":"notes","filter":{"title":"First note"},"limit":1}}' ``` Queries return an array in `data`, even with `limit: 1`. Use the returned `_id` for an exact lookup: ```json { "operation": "data.query", "payload": { "collection": "notes", "filter": { "_id": "" }, "limit": 1 } } ``` ## JavaScript SDK example Install the existing JavaScript SDK: ```sh npm install @singlebase/singlebase-sdk ``` Run this on your backend with the environment variables above. `baseUrl` is the complete project endpoint; omit `urlAccessKey` because it is already in that URL. Passing `bearer: null` keeps these calls under the server key. ```javascript import { SinglebaseClient } from "@singlebase/singlebase-sdk"; const sbc = SinglebaseClient({ baseUrl: process.env.SINGLEBASE_API_URL, apiKey: process.env.SINGLEBASE_SERVER_KEY, }); const created = await sbc.data.insert({ collection: "notes", data: { title: "First note", status: "active" }, }, { bearer: null }); console.log(created); const notes = await sbc.data.query({ collection: "notes", filter: { title: "First note" }, limit: 1, }, { bearer: null }); console.log(notes); ``` The SDK returns `data` directly and throws a `SinglebaseError` for API errors. See [JavaScript SDK](/sdk-javascript.md). ## Python example Copy the small client from [Python SDK](/sdk-python.md) into `singlebase.py`. It uses the standard library and returns the full `Result` envelope. ```python import asyncio import os from singlebase import singlebaseClient, Result async def main(): sbc = singlebaseClient( api_key=os.environ["SINGLEBASE_SERVER_KEY"], api_url=os.environ["SINGLEBASE_API_URL"], ) created: Result = await sbc.call("data.insert", { "collection": "notes", "data": {"title": "First note", "status": "active"}, }, options={}) if created.error: raise RuntimeError(created.error["message"]) print(created.data) notes: Result = await sbc.call("data.query", { "collection": "notes", "filter": {"title": "First note"}, "limit": 1, }, options={}) if notes.error: raise RuntimeError(notes.error["message"]) print(notes.data) asyncio.run(main()) ``` ## Give an agent access Create an agent key in the console with `read` on `notes`. Use that key in `X-API-KEY` to make the query above from the agent's server-side tool handler. Add `write` only if it also needs to create notes. For generation such as `llm.summarize`, an agent needs `ai.generate`. For `chat.ask` and persisted chats it needs `ai.chat`. See [Agent permissions](/agents.md#permissions). ## Connect a signed-in user Browser and mobile clients use a web key (`wk_`) plus `Authorization: Bearer ` for user-scoped operations. A signed-in insert automatically belongs to that user; reads and mutations are scoped to their documents. See [Authentication](/auth.md) for signup and signin, and [API overview](/api.md) for headers and errors. --- Canonical page: https://docs.singlebase.io/api # Singlebase API **A database for agents. A backend for builders.** Examples use illustrative values and placeholders. Replace IDs, credentials, and configured resource names with your own. Response samples illustrate the envelope, not fixed IDs, totals, or timings. Singlebase gives your AI agents access to data, knowledge, and context, and gives your application the same foundation to build on. Store records once. Let agents query them by meaning. Let your app create and update them. ## Overview **One connected foundation:** | Product | What it does | API | |---|---|---| | **DocumentDB** | Flexible JSON documents for app data and agent context | [`data.*`](/data.md) | | **Full-text search** | Find names, phrases, and keywords in your data | [`data.query` + `search`](/data.md#full-text-search) | | **VectorDB** | Retrieve records by meaning with similarity search | [Docsets](/chat.md#docsets), [`llm.embed`](/llm.md#embeddings) | | **Identity** | Sign-up, sign-in, sessions, and user management | [`auth.*`, `user.*`](/auth.md), [`users.*`](/users.md) | | **Storage** | Files your users upload and content your agents generate | [`files.*`](/files.md) | | **Intelligence** | Model access, generation, Document to Markdown, embeddings | [`llm.*`](/llm.md) | | **Conversation** | Chat with Documents: persisted chats with RAG and attachments | [`chat.*`](/chat.md) | | **Agents** | Give each agent its own access and permissions | [Agent keys](/agents.md) | **Built for agents and developers:** - One endpoint and one request shape for every operation - Per-agent keys scoped to the collections and features you choose - Structured queries, full-text search, and similarity search over the same data - Predictable JSON responses and stable error codes that agents can act on - Templates and helper functions to compute values on write - Batch up to 10 operations in one request --- ## How It Fits Together **1. Create your data.** Store the records your app runs on and your agents need as context. ```json { "operation": "data.insert", "payload": { "collection": "product_catalog", "data": { "name": "Everyday backpack", "description": "A compact bag with a padded laptop sleeve, weather-resistant fabric, and room for your daily essentials.", "category": "bags" } } } ``` **2. Give your agent access.** Create an [agent key](/agents.md) whose permissions only allow reading `product_catalog`: ```json { "name": "shopping-agent", "collections": { "product_catalog": ["read", "search"] }, "permissions": ["ai.chat"] } ``` **3. Query by meaning.** Create a `products` [docset](/chat.md#docsets) over `product_catalog` with vector search and `acl: "agent"`. The agent asks in plain language and gets an answer grounded in your records: ```json { "operation": "chat.ask", "payload": { "message": "Something for a laptop and a daily commute", "mode": "kb", "retrieval": [{ "source": "docset", "ids": "products" }] } } ``` Your application keeps creating and updating the same `product_catalog` with its own keys and signed-in users. --- ## Quick Start ### 1. Create a project [Sign up](https://console.singlebase.io) and create a project. In the project settings, copy: - **API endpoint** - Your project URL, `https://v1.api.singlebase.io/api/` - **API key** - Sent in the `X-API-KEY` header on every request ### 2. Make your first request Every operation is a `POST` to the same endpoint: ```http POST https://v1.api.singlebase.io/api/ Content-Type: application/json X-API-KEY: Authorization: Bearer ``` ```json { "operation": "data.query", "payload": { "collection": "product_catalog", "filter": { "category": "bags" }, "per_page": 20 } } ``` `Authorization` is only needed for operations that act as a signed-in user. Get an ID token from [`auth.signin`](/auth.md#auth-signin). ### 3. Call the API from your application Use the REST helper below from server code. Use a web key plus a signed-in user token for browser requests; server and agent keys stay on your backend. ### 4. A reusable request helper This helper works with every operation in these docs: ```javascript const API_URL = 'https://v1.api.singlebase.io/api/'; const API_KEY = ''; async function singlebase(operation, payload = {}, idToken) { const response = await fetch(API_URL, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-API-KEY': API_KEY, ...(idToken ? { Authorization: `Bearer ${idToken}` } : {}) }, body: JSON.stringify({ operation, payload }) }); const result = await response.json(); if (!response.ok || result.error) { throw new Error(result.error?.message || `HTTP ${response.status}`); } return result; } // Sign in, then read the user's notes const session = await singlebase('auth.signin', { email: 'jane@example.com', password: 'ExamplePass123!' }); const notes = await singlebase('data.query', { collection: 'notes', per_page: 20 }, session.data.id_token); ``` --- ## Request Format Every request uses the same envelope: ```json { "operation": "data.insert", "payload": { "collection": "notes", "data": { "title": "First note" } }, "options": {} } ``` | Field | Required | Description | |---|---|---| | `operation` | Yes | Operation name, `namespace.action`, such as `data.query` or `auth.signin` | | `payload` | Yes | Operation parameters. Use `{}` when there are none | | `options` | No | Request options, such as `_batch_key` in a batch | Only `operation`, `payload`, and `options` belong at the top level. All parameters go inside `payload`. Most operations ignore unknown payload fields; some stricter payloads, including `files.delete`, reject them. Use only the fields documented for the operation. ### Namespaces | Namespace | Purpose | Docs | |---|---|---| | `data.*` | DocumentDB: store, query, search, and update JSON documents | [Data](/data.md) | | `auth.*` | Identity: signup, signin, sessions, codes, OAuth | [Authentication](/auth.md) | | `user.*` | Identity: the signed-in user's own profile | [Authentication](/user.md) | | `users.*` | Identity: admin user management (server and agent keys) | [Users](/users.md) | | `files.*` | Storage: uploads, signed URLs, Markdown conversion | [Files](/files.md) | | `llm.*` | Intelligence: generation and embeddings; deprecated chat aliases | [LLM](/llm.md) | | `chat.*` | Intelligence: one-off answers, persisted chats, and retrieval | [Conversation](/chat.md) | --- ## API Keys Each project has several key types. The key prefix decides what the caller can do. | Key | Prefix | Use it from | Access | |---|---|---|---| | Web | `wk_` | Browsers and mobile apps | Public operations; signed-in user operations with a bearer token | | Server | `sk_` | Your backend | Admin access to the project | | Agent | `agk_` | AI agents and automations | Admin access, limited to the key's permissions. See [Agents](/agents.md) | **Rules to know:** - Web keys require an `Origin` or `Referer` on the project's authorized domain list, over HTTPS. `localhost` and `127.0.0.1` may use HTTP. - Keep server and agent keys out of browser code. - When a request includes a bearer token, the API acts as that signed-in user, whatever the key type. - An invalid, disabled, or unknown key returns `404 PROJECT_NOT_FOUND`. --- ## Access Levels Each operation has an access level. These pages state it per operation. | Level | Who can call it | |---|---| | Public | Anyone with a valid project key. Project settings and ownership rules still apply | | User | A signed-in user (bearer token required) | | Admin | Server or agent keys | Some public operations still need a user. For example, `data.query` requires a bearer token unless the key is a server or agent key. --- ## Responses Successful requests return `data`, `meta`, and `exec_time` (seconds). The shape of `data` depends on the operation. ```json { "data": { "count": 3 }, "meta": {}, "exec_time": 0.012 } ``` Queries return an array in `data` and pagination in `meta.pagination`. A query with no matches returns an empty array. ### Errors Errors use the HTTP status code and an `error` object: ```json { "error": { "type": "BAD_REQUEST", "status": 400, "message": "INVALID_PAYLOAD", "details": [], "trace_id": null }, "meta": {}, "exec_time": 0.003 } ``` - **message** - A stable error code, such as `INVALID_PAYLOAD` or `FILE_FORBIDDEN` - **details** - Optional extra information, such as validation errors - **trace_id** - Include it when you contact support | Status | Typical cause | What to do | |---|---|---| | `400` | Invalid envelope, payload, filter, or selector | Fix the request | | `401` | Missing session, invalid token, or invalid credentials | Sign in or refresh the session | | `403` | Access level, project setting, domain, or agent scope | Check keys, permissions, and settings | | `404` | Unknown operation, project, or resource | Check the endpoint, key, operation, and ID | | `409` | Conflict with existing data | Resolve the conflict, then retry | | `413` | Request or file too large | Reduce the size | | `415` | File type not allowed | Use an allowed type | | `422` | Invalid attachment, retrieval, or file state | Fix the input or wait for processing | | `429` | Rate limit exceeded | Retry with exponential backoff and jitter | | `500`, `502`, `503` | Server, upstream, or maintenance error | Retry later; keep the `trace_id` | **Limits:** - The JSON body must be smaller than 10 MB. Upload file bytes directly to storage with the [upload workflow](/files.md#upload-workflow). - Rate limits depend on your project's plan. --- ## Batch Requests Run 1 to 10 operations in order with `batch`: ```json { "operation": "batch", "payload": { "operations": [ { "operation": "data.query", "payload": { "collection": "notes", "per_page": 5 }, "options": { "_batch_key": "notes" } }, { "operation": "data.count", "payload": { "collection": "notes" }, "options": { "_batch_key": "total" } } ] } } ``` **Response:** ```json { "data": [ { "__batch_key": "notes", "data": [{ "_id": "note_123", "title": "First note" }], "meta": { "pagination": {} }, "message": null }, { "__batch_key": "total", "data": { "count": 12 }, "meta": {}, "message": null } ], "meta": { "batch": true }, "exec_time": 0.031 } ``` **Behavior:** - Operations run in order and share the request's credentials. A signin inside a batch does not authenticate later items. - Outer `options` override item `options`. - Execution stops at the first error. Earlier writes are kept, so a batch is not a transaction. --- ## Check Connectivity ```json { "operation": "ping", "payload": {} } ``` Returns `data: "pong"`. Ping does not validate project credentials. --- ## Next Steps **Database:** - [Data](/data.md) - DocumentDB, full-text search, and data operators - [Query Syntax](/queries.md) - Filters, sorting, pagination, and search - [Templates](/templates.md) - Expressions and helper functions for computed values **Identity and Storage:** - [Authentication](/auth.md) - Sign users in and manage sessions - [Users](/users.md) - Manage users from your server or agent - [Files](/files.md) - Store uploads and agent-generated content **Intelligence and Agents:** - [LLM](/llm.md) - Model access, generation, and embeddings - [Conversation](/chat.md) - Chat with Documents, docsets, and attachments - [Agents](/agents.md) - Give each agent its own access and permissions **Components:** Add Singlebase to your website with the [Auth UI](https://singlebase.io/components/auth-ui/), [File Uploader](https://singlebase.io/components/file-uploader/), and [Chat Box](https://singlebase.io/components/chat-box/) web components. --- Canonical page: https://docs.singlebase.io/agents # Agents **Their own access. Your boundaries.** Give every agent its own database access and permissions. Each agent works with the part of your data you choose, on the same foundation as your application. ## Overview AI agents, such as shopping assistants, support bots, LLM tool-calling loops, MCP servers, and background workers, need context from your data without holding a full server key. An **agent key** gives one agent exactly the collections and operations its job requires. **Example policy:** | Collection | Shopping agent | Support agent | |---|---|---| | `product_catalog` | `read`, `search` | `read` | | `orders` | No access | `read` | | `support_articles` | No access | `read`, `search` | The shopping agent can query products without seeing orders or support content. **What agents can do with Singlebase:** - **Read context** from DocumentDB with filters and full-text search - **Query by meaning** through vector [docsets](/chat.md#docsets) built for agents - **Write results** back as documents, or save reports and files to [Storage](/files.md) - **Use models** for generation and embeddings with [LLM](/llm.md), and hold chats with [Conversation](/chat.md) - **Manage users** for support and ops workflows with [Users](/users.md) **Key features:** - One named key per agent, with an `agk_` prefix - Per-collection permissions: `read`, `search`, `write`, `delete` - Per-feature permissions for LLM, files, and users - Every operation is checked, including each item in a batch - Enable, disable, rotate, or delete a key without touching other keys - Usage tracked with `last_used_at` - Optional expiry, extended through the existing key update operation **Use cases:** Support agents that look up orders, content agents that draft and publish documents, ingestion agents that upload files, ops agents that manage users **How it works:** 1. **Define the task** - Decide what the agent should help with. 2. **Choose its access** - Create an agent key in the console with the collections and permissions it needs. 3. **Connect the agent** - It calls the normal API with `X-API-KEY: agk_...`. 4. **Review and adjust** - Singlebase allows the call only if the key's permissions cover it. Otherwise it returns `403 AGENT_SCOPE_DENIED`. Update the scope as the agent's task changes. A project can store up to 50 agent keys. --- ## Calling the API Agents use the same endpoint and [request format](/api.md#request-format) as any client. Send the agent key in `X-API-KEY` and no `Authorization` header. ### Connect with MCP Agent runtimes can also connect to `https://v1.api.singlebase.io/mcp/` using `Authorization: Bearer agk_…` or `X-API-KEY: agk_…`. Enable MCP for the project first. The server lists only tools and collection choices allowed by the key and applies the same gateway rules to every call. See [MCP](/mcp-guide) for Claude Code, Cursor, Claude Desktop, and raw HTTP examples. ```http POST https://v1.api.singlebase.io/api/ Content-Type: application/json X-API-KEY: agk_ ``` ```json { "operation": "data.query", "payload": { "collection": "orders", "filter": { "customer_email": "jane@example.com" }, "per_page": 10 } } ``` **Within its permissions, an agent key has admin-level access:** - `data.query` and `data.count` read across all users. Scope a request to one user with payload-level `"_user_id": ""`, alongside `filter`. Ownership fields inside `filter` are rejected. - `data.insert` can set an owner with payload-level `_user_id`. A single update-by-ID can reassign an owner with `data._user_id`; the user must exist. Payload-level `_user_id` on update selects an owner rather than changing it. - Conversations and `chat.ask` can use every [retrieval source](/chat.md#sources-by-key-type), including raw collections. - `files.*` can act on any project file. Grant only what the agent needs. --- ## Permissions An agent key has two permission sets. It needs at least one entry in either. ### Collection permissions `collections` maps collection names to allowed actions. They apply to `data.*` operations using `payload.collection`. ```json { "orders": ["read", "search"], "support_notes": ["read", "write"], "drafts": ["read", "write", "delete"] } ``` | Permission | Allows | |---|---| | `read` | `data.query`, `data.count`, `data.aggregate` | | `search` | `data.query` and `data.count` with a non-empty `search`. Also grants `read` | | `write` | `data.insert`, `data.update`, `data.upsert` | | `delete` | `data.archive`, `data.delete` | Collections that are not listed are denied. Internal system collections cannot be granted. ### Operation permissions `permissions` lists features the agent may use. | Permission | Allows | |---|---| | `ai.generate` | `llm.generate`, `llm.write`, `llm.translate`, `llm.summarize`, `llm.categorize`, `llm.extract`, `llm.analyze` | | `ai.chat` | All `chat.*` operations and their deprecated `llm.*` aliases, including preparation | | `ai.embed` | `llm.embed` | | `files.read` | `files.get_signed_url` | | `files.list` | `files.query` | | `files.upload` | `files.initiate_upload`, `files.complete_upload`, `files.fail_upload`, `files.update`, `files.reprocess` | | `files.delete` | `files.delete` | | `users.list` | `users.query`, `users.get_details` | | `users.create` | `users.create` | | `users.update` | `users.update`, `users.update_status`, `users.update_password`, `users.link_provider`, `users.unlink_provider` | | `users.delete` | `users.delete` | For `files.reprocess`, agent keys always follow owner rules even with an admin role: they cannot retry another owner's file or a completed pipeline, and are limited to four starts per file. Recently active processing is refused for all callers; processing at least 30 minutes old can be restarted. ### Always denied Agent keys can never call: - `auth.*` and `user.*` (agents don't sign in as users) - `users.get` and the user token operations - Console operations **Batches:** Every operation in a [batch](/api.md#batch-requests) is checked before any runs. One denied item denies the whole request. **Docsets:** In [retrieval](/chat.md#docsets), agent keys count as `agent`. They can use docsets whose `acl` is `agent`, but not `user` or `admin` docsets. --- ## Managing Agent Keys Manage agent keys in the [Singlebase console](https://console.singlebase.io), in your project's settings. Project owners and admins can create, update, rotate, and delete them. The key secret is shown in the `key` field; store it right away. **Key record:** ```json { "_id": "agt_3f9a1c", "name": "support-bot", "description": "Answers order questions in the help widget", "enabled": true, "key": "agk_3f9a1c_", "collections": { "orders": ["read", "search"], "support_notes": ["read", "write"] }, "permissions": ["ai.chat", "files.read"], "expires_at": "2027-01-10T12:00:00Z", "last_used_at": "2026-10-03T12:00:00+00:00", "_created_at": "2026-09-01T09:00:00+00:00", "_modified_at": "2026-09-15T14:30:00+00:00" } ``` **Rules:** - Names are unique per project, ignoring case. - A project can have up to 50 agent keys. - Updating `collections` or `permissions` replaces the whole list; it does not merge. - Rotating a key issues a new secret. The old key stops working right away. - Rotation preserves `expires_at`. - Disabled, rotated, and deleted keys return `404 PROJECT_NOT_FOUND`. - Expired keys return `401 AGENT_KEY_EXPIRED` before scope checks and usage tracking. ### Expiry and extension Create and update accept `expires_at`, an absolute ISO 8601 time with `Z` or a timezone offset. The stored value is returned in UTC with `Z`. `null` means never expires, and is the default for new keys. Older keys without this field continue to work without expiry. The timestamp must be in the future, allowing up to one minute of clock skew at save time. Naive or older timestamps return `400 INVALID_EXPIRY`; invalid syntax returns `INVALID_PAYLOAD`. Authentication rejects at the exact expiry time. Use `console.update_agent_key { id, expires_at }` to extend an expired key. The same secret works immediately afterward. Omitting the field keeps its current value; sending `null` removes the expiry. Expiration does not delete the key. --- ## Example: Tool for an LLM Agent Expose Singlebase to a tool-calling model with one generic tool. The agent key's permissions remain the real security boundary. **Tool definition:** ```json { "name": "singlebase", "description": "Call the Singlebase backend API. Use operation names such as data.query, data.insert, files.query, llm.summarize. Put all parameters in payload.", "input_schema": { "type": "object", "properties": { "operation": { "type": "string", "description": "Operation name, for example data.query" }, "payload": { "type": "object", "description": "Operation parameters, for example {\"collection\": \"orders\", \"filter\": {\"status\": \"open\"}}" } }, "required": ["operation", "payload"] } } ``` **Tool handler (JavaScript SDK, server-side):** ```javascript import { SinglebaseClient, SinglebaseError } from "@singlebase/singlebase-sdk"; const sbc = SinglebaseClient({ baseUrl: process.env.SINGLEBASE_API_URL, apiKey: process.env.SINGLEBASE_AGENT_KEY, }); async function singlebase(operation, payload) { try { const data = await sbc.dispatch({ operation, payload }, { bearer: null }); return { data }; } catch (error) { if (error instanceof SinglebaseError) { return { error: error.code, status: error.status }; } throw error; } } ``` The JavaScript SDK returns `data` directly and throws API errors. Keep this agent handler on your server. See [JavaScript SDK](/sdk-javascript.md) for connection options. **Example calls the agent might make:** ```json { "operation": "data.query", "payload": { "collection": "orders", "filter": { "status": "open" }, "per_page": 5 } } ``` ```json { "operation": "data.insert", "payload": { "collection": "support_notes", "data": { "order_id": "ord_123", "note": "Customer asked for a refund." } } } ``` ```json { "operation": "llm.summarize", "payload": { "content": "", "input": "Three bullets." } } ``` --- ## Quick Reference for AI Agents A compact summary of the API for models that read these docs. **Request:** `POST `, headers `Content-Type: application/json` and `X-API-KEY: `, body `{"operation": "", "payload": {...}}`. **Success:** `{"data": ..., "meta": {...}}`. **Error:** `{"error": {"type", "status", "message"}}`; `message` is a stable code. **Common operations:** | Goal | Operation | Minimal payload | |---|---|---| | Find documents | `data.query` | `{"collection": "c", "filter": {...}}` | | Get one document | `data.query` | `{"collection": "c", "filter": {"_id": "id"}, "limit": 1}` | | Search by keyword | `data.query` | `{"collection": "c", "search": "words"}` | | Count | `data.count` | `{"collection": "c", "filter": {...}}` | | Totals | `data.aggregate` | `{"collection": "c", "compute": {"n": {"$count": "*"}}}` | | Create | `data.insert` | `{"collection": "c", "data": {...}}` | | Patch by ID | `data.update` | `{"collection": "c", "data": {"_id": "id", "field": "value"}}` | | Create or update | `data.upsert` | `{"collection": "c", "filter": {...}, "insert_data": {...}, "update_data": {...}}` | | Delete | `data.delete` | `{"collection": "c", "id": "id"}` | | List files | `files.query` | `{"per_page": 20}` | | File download URL | `files.get_signed_url` | `{"id": "file_id"}` | | Summarize text | `llm.summarize` | `{"content": "..."}` | | Extract JSON | `llm.extract` | `{"content": "...", "format": "json"}` | | Search by meaning | `chat.ask` | `{"message": "...", "mode": "kb", "retrieval": [{"source": "docset", "ids": "slug"}]}` | | Find a user | `users.query` | `{"search": "email or name"}` | **Syntax reminders:** - Filters: `{"field": value}`, `{"field:$gte": 10}`, `{"$or": [{...}, {...}]}`. See [Query Syntax](/queries.md). - Update operators: `"count:$incr": 1`, `"tags:$push": "x"`, `"old:$unset": true`. See [Data Operators](/data.md#data-operators). - Templates: `"{{ field }}"` (string), `"&:{{ a * b }}"` (native), `"{{ $now() }}"` (helper). See [Templates](/templates.md). **Error handling:** | Message | What the agent should do | |---|---| | `AGENT_SCOPE_DENIED` | Stop. The key lacks permission; don't retry | | `INVALID_PAYLOAD` | Check `details`, fix the payload, retry once | | `MISSING_COLLECTION_NAME` | Add `payload.collection` | | HTTP `429` | Wait with exponential backoff, then retry | | HTTP `5xx` | Retry later with backoff | --- ## Best Practices - **Least privilege** - Start with `read` on one collection and add permissions as needed. - **One key per agent** - Separate keys make usage, auditing, and revocation simple. - **Keep keys server-side** - Store agent keys in environment variables or a secret manager, never in prompts, client code, or logs. - **Use docsets for knowledge** - Give agents curated [docsets](/chat.md#docsets) with `acl: "agent"` instead of broad collection access. - **Rotate regularly** - Rotate keys on a schedule and right away if one leaks. - **Return errors to the model** - Error codes are stable, so agents can recover from `INVALID_PAYLOAD` on their own. --- ## Next Steps - [Data](/data.md) - Operations available to collection permissions - [LLM](/llm.md) - Generation, answers, and embeddings - [Conversation](/chat.md) - Chats, docsets, and attachments - [Files](/files.md) - Upload and serve files - [Users](/users.md) - Admin user management --- Canonical page: https://docs.singlebase.io/data # Data Store JSON documents in collections and work with them through `data.*` operations. The same records power your application and give your agents context. ## Overview **DocumentDB** gives your applications and agents three ways to work with the same data: structured JSON queries, similarity search by meaning, and full-text search for words and phrases. Eligible document content is vectorized into embeddings for VectorDB similarity search, while the database's FTS5 index supports keyword search. Embeddings power similarity search; FTS5 uses its own text index. Your app creates and updates records; your agents read the ones you allow. Store your data once, then retrieve the context that fits the task through configured collections and [docsets](/chat.md#docsets). Vector indexing and full-text search depend on your project configuration. **One database, three ways in:** - **Structured queries** - [Filters](/queries.md), sorting, pagination, and aggregation - **FTS5 full-text search** - Match names, phrases, and keywords with [`search`](#full-text-search) - **VectorDB embeddings and vector search** - Point a vector [docset](/chat.md#docsets) at a collection for similarity search **Hybrid retrieval** combines these search paths when grounding chat answers. A vector docset searches indexed collections and Smart Bucket file vectors, and uses full-text search for its other collections. You can also combine keyword and vector docsets in one request. See [Chat search and hybrid retrieval](/chat.md#search-and-hybrid-retrieval). **Key features:** - Schemaless JSON documents identified by `_id` - Single or bulk inserts and updates - [Data operators](#data-operators) such as `views:$incr` and `tags:$push` - [Templates](/templates.md) that compute values on write - Per-user ownership with `_user_id` - Per-agent, per-collection access with [agent keys](/agents.md) - Soft deletes with configurable retention **Use cases:** Product catalogs, knowledge records, orders, user content, agent memory and notes, app state --- ## Operations Every `data.*` operation requires `payload.collection`. | Operation | Description | Required payload | |---|---|---| | `data.query` | Retrieve documents | `collection` | | `data.count` | Count matching documents | `collection` | | `data.aggregate` | Compute aggregate values | `collection`, `compute` | | `data.insert` | Insert one or more documents | `collection`, `data` | | `data.update` | Update documents by `_id` or filter | `collection`, `data` | | `data.upsert` | Update matches, or insert when nothing matches | `collection`, `filter`, `insert_data` | | `data.archive` | Archive documents with optional retention | `collection`, one selector | | `data.delete` | Archive documents with seven-day retention | `collection`, one selector | --- ## Document Fields Singlebase sets these fields. You can read these fields. Use `_user_id` at the payload root to select an owner; other fields can be used in filters and sorting. Updates and upserts ignore `_created_at` and `_modified_at`. | Field | Description | |---|---| | `_id` | Document ID | | `_user_id` | Owner's user ID, when set. See [Ownership](#ownership) | | `_created_at` | Creation time | | `_modified_at` | Last update time | --- ## Ownership `_user_id` links a document to a user. How it behaves depends on the caller. **Signed-in users:** - Reads (`data.query`, `data.count`, `data.aggregate`) and mutations (`data.update`, `data.upsert`, `data.archive`, `data.delete`) are limited to the signed-in user's documents. - `data.insert` automatically assigns the signed-in user's ID, even when `_user_id` is omitted. A caller-supplied owner is replaced with that ID. - A payload-level `_user_id` on scoped reads or mutations must equal the signed-in user's ID; another value returns `USER_ID_MISMATCH`. - Changing ownership through `data.update` is refused (`USER_ID_UPDATE_REQUIRES_ADMIN`). - Reading, updating, upserting, archiving, or deleting without a bearer token requires a privileged server or agent key (`AUTHENTICATION_REQUIRED` otherwise). **Server and agent keys without a bearer token:** - Read and mutate across owners, subject to the agent key's collection permissions. - Scope a request to one existing project user by sending `_user_id` at the **payload root**, alongside `filter`. This selects an owner; it does not reassign ownership. - Set an owner on insert with payload-level `_user_id` or `data._user_id`. - Reassign an owner only with a single update-by-ID object containing `data._user_id`. The new user must exist. Filter-based or bulk owner changes return `OWNER_CHANGE_REQUIRES_SINGLE_DOCUMENT`. **Ownership selectors:** Never put `_user_id` inside `filter`, including nested filters or `_user_id:$in`; this returns `INVALID_USER_ID_FILTER`. Use the payload root instead: ```json { "operation": "data.query", "payload": { "collection": "notes", "_user_id": "", "filter": { "status": "active" }, "per_page": 20 } } ``` For scoped mutations, selecting more matching documents than the scope limit allows returns `SCOPE_TOO_LARGE`. A requested update ID outside the selected owner returns `DOCUMENT_NOT_FOUND`. --- ## data.query Retrieve documents from a collection. ```json { "operation": "data.query", "payload": { "collection": "notes", "filter": { "status": "active" }, "sort": "_created_at desc", "page": 1, "per_page": 20 } } ``` **Parameters:** | Field | Description | |---|---| | `collection` | Collection name (required) | | `filter` | Match conditions. See [Query Syntax](/queries.md) | | `search` | Full-text search string | | `sort` | Sort expression. Default `_created_at desc` | | `page`, `per_page` | Page-based pagination. Defaults `1` and `20` | | `limit`, `offset` | Offset-based pagination | | `compute` | Computed fields | | `lookups` | Lookups into related collections | | `archive_only` | Return archived documents only. Default `false` | | `_user_id` | Scope the request to one user; send at the payload root | **Response:** ```json { "data": [ { "_id": "note_123", "_user_id": "user_123", "title": "First note", "status": "active", "_created_at": "2026-10-03T12:00:00+00:00", "_modified_at": "2026-10-03T12:00:00+00:00" } ], "meta": { "pagination": { "total_items": 84, "count": 20, "per_page": 20, "page": 1, "total_pages": 5, "next_page": 2, "prev_page": null } }, "exec_time": 0.018 } ``` **Example - Get one document:** ```json { "operation": "data.query", "payload": { "collection": "notes", "filter": { "_id": "note_123" }, "limit": 1 } } ``` The result is still an array. --- ## data.count Count documents that match a filter. ```json { "operation": "data.count", "payload": { "collection": "notes", "filter": { "status": "active" } } } ``` **Response:** ```json { "data": { "count": 42 } } ``` `filter` and full-text `search` select the records to count. The [ownership](#ownership) rules of `data.query` apply. --- ## data.aggregate Compute values such as totals and averages. ```json { "operation": "data.aggregate", "payload": { "collection": "orders", "filter": { "status": "paid" }, "compute": { "orders": { "$count": "*" }, "revenue": { "$sum": "total" }, "average_order": { "$avg": "total" } } } } ``` **Parameters:** | Field | Description | |---|---| | `collection` | Collection name (required) | | `compute` | Named aggregate definitions (required) | | `filter` | Match conditions | | `archive_only` | Aggregate archived documents only | | `include_archive` | Include archived documents | | `cache` | Cache the result for this many seconds | The aggregate result is returned in `data`. An empty result returns `data: {}`. ::: warning `data.aggregate` is scoped to the signed-in user. With a server or agent key, use payload-level `_user_id` for totals belonging to one user. Never put ownership inside `filter`. ::: --- ## data.insert Insert one document or an array of documents. ```json { "operation": "data.insert", "payload": { "collection": "notes", "data": { "title": "First note", "status": "active", "views": 0, "tags": ["draft"] } } } ``` **Parameters:** | Field | Description | |---|---| | `collection` | Collection name (required) | | `data` | A document object, or an array of documents (required) | | `_user_id` | Owner for every inserted document. See [Ownership](#ownership) | | `unique_fields` | Fields that must be unique, such as `["email"]` | | `on_conflict` | What to do when a unique field conflicts. Default `"error"` | | `ttl_seconds` | Expire documents after this many seconds | | `metadata` | Hidden document metadata, stored in `_metadata` | With a bearer token, this insert automatically belongs to the signed-in user. With a server or agent key and no bearer token, send an existing user ID in payload-level `_user_id` to assign an owner; omit it for an unowned document. **Response:** ```json { "data": [ { "_id": "note_123", "_user_id": "user_123", "title": "First note", "status": "active", "views": 0, "tags": ["draft"] } ] } ``` **Example - Bulk insert with a unique field:** ```json { "operation": "data.insert", "payload": { "collection": "subscribers", "data": [ { "email": "ada@example.com", "plan": "free" }, { "email": "grace@example.com", "plan": "pro" } ], "unique_fields": ["email"] } } ``` --- ## data.update Update documents by `_id`, or patch every document that matches a filter. **Example - Update by ID:** ```json { "operation": "data.update", "payload": { "collection": "notes", "data": { "_id": "note_123", "title": "Updated note", "views:$incr": 1 } } } ``` **Example - Update several documents by ID:** ```json { "operation": "data.update", "payload": { "collection": "notes", "data": [ { "_id": "note_123", "status": "active" }, { "_id": "note_456", "status": "archived" } ] } } ``` **Example - Update by filter:** ```json { "operation": "data.update", "payload": { "collection": "notes", "filter": { "status": "draft" }, "data": { "status": "active" }, "max_docs": 100 } } ``` **Parameters:** | Field | Description | |---|---| | `collection` | Collection name (required) | | `data` | A patch object, or an array of patches (required) | | `filter` | Select documents to patch. When set, use one patch object | | `max_docs` | Maximum number of documents to change | | `_user_id` | Select documents owned by this user; send at the payload root | **Rules:** - Without `filter`, every patch needs a non-empty `_id` (`MISSING_DOCUMENT_ID`). - An empty `filter: {}` counts as a filter and can match many documents. Use a narrow filter and `max_docs`. - Plain nested objects merge with existing values. Use `:$replace` to replace an object. Returns the updated documents in `data`. --- ## data.upsert Update matching documents, or insert a new one when nothing matches. ```json { "operation": "data.upsert", "payload": { "collection": "page_views", "filter": { "slug": "release-notes" }, "insert_data": { "slug": "release-notes", "views": 1 }, "update_data": { "views:$incr": 1 }, "max_docs": 1 } } ``` **Parameters:** | Field | Description | |---|---| | `collection` | Collection name (required) | | `filter` | Match conditions (required) | | `insert_data` | Document to insert when nothing matches (required) | | `update_data` | Patch applied to matches | | `max_docs` | Maximum number of documents to update | Upsert scopes matches to the signed-in user and assigns that user to a new document. Server or agent callers can scope the request with payload-level `_user_id`. Ownership conditions inside `filter` are rejected. Upsert cannot reassign an existing owner. --- ## data.archive Archive documents. Archived documents are hidden from normal queries. ```json { "operation": "data.archive", "payload": { "collection": "notes", "ids": ["note_123", "note_456"], "ttl_seconds": 2592000 } } ``` **Parameters:** | Field | Description | |---|---| | `collection` | Collection name (required) | | `id`, `ids`, or `filter` | Exactly one selector (required) | | `ttl_seconds` | Keep archived documents this many seconds before removal | | `max_docs` | Maximum number of documents to archive | **Response:** ```json { "data": { "count": 2, "deleted_count": 2, "items": [], "txn_id": "txn_123" } } ``` Read archived documents with `data.query` and `archive_only: true`. There is no unarchive operation. --- ## data.delete Delete documents. `data.delete` archives them with a fixed seven-day retention (604800 seconds), then they are removed. ```json { "operation": "data.delete", "payload": { "collection": "notes", "id": "note_123" } } ``` Requires exactly one of `id`, `ids`, or `filter` (`EXACTLY_ONE_ARCHIVE_SELECTOR_REQUIRED`). `max_docs` is optional; `ttl_seconds` is ignored. The response matches `data.archive`. --- ## Full-text Search Find documents by the words in them. Add `search` to `data.query`, and combine it with `filter` to narrow the results. ```json { "operation": "data.query", "payload": { "collection": "product_catalog", "search": "laptop backpack", "filter": { "category": "bags" }, "per_page": 10 } } ``` Full-text search uses SQLite FTS5 and depends on the collection's search configuration. Agent keys need the `search` permission on the collection. **VectorDB embeddings and vector search:** Collection indexing creates embeddings from document content and stores chunks in the project vector index. Vector retrieval depends on enabled indexing and available embeddings. To find records that match the intent of a request, even when the words differ, create a [docset](/chat.md#docsets) with vector search over the collection and use it from `chat.send` or `chat.ask`. Docsets can also use full-text search, and an answer can draw on several docsets. --- ## Data Operators Change a field in place with `field:$operator` keys in `data`, `update_data`, or `insert_data`. Use dot notation for nested fields. ```json { "operation": "data.update", "payload": { "collection": "posts", "data": { "_id": "post_123", "stats.views:$incr": 1, "tags:$push": "featured", "draft_notes:$unset": true } } } ``` | Operator | Effect | Example | |---|---|---| | `field` or `field:$set` | Set a value | `"status": "active"` | | `field:$replace` | Replace a value, including a whole object | `"settings:$replace": {"theme": "dark"}` | | `field:$unset` | Remove the field | `"obsolete:$unset": true` | | `field:$incr` | Add a number (alias `$inc`) | `"views:$incr": 1` | | `field:$decr` | Subtract a number (alias `$dec`) | `"stock:$decr": 2` | | `field:$push` | Append one item to an array | `"tags:$push": "reviewed"` | | `field:$lpush` | Prepend one item to an array | `"tags:$lpush": "pinned"` | | `field:$extend` | Append several items | `"tags:$extend": ["api", "docs"]` | | `field:$lextend` | Prepend several items | `"tags:$lextend": ["new", "hot"]` | | `field:$pop` | Remove the last array item | `"tags:$pop": true` | | `field:$remove` | Remove matching array items | `"tags:$remove": "draft"` | | `field:$clear` | Empty an array | `"tags:$clear": true` | | `field:$rename` | Move the value to another path | `"old_title:$rename": "title"` | | `field:$copy` | Copy the value to another path | `"title:$copy": "original_title"` | **Merge behavior:** ```javascript // Existing: { "settings": { "theme": "light", "lang": "en" } } { "settings": { "theme": "dark" } } // Result: { "settings": { "theme": "dark", "lang": "en" } } { "settings:$replace": { "theme": "dark" } } // Result: { "settings": { "theme": "dark" } } ``` ::: warning Not atomic Writes that use operators or templates read the current documents, apply the changes, then save them. A concurrent write can land in between, so `$incr` is not an atomic counter. ::: --- ## Templates Compute values from the document itself with [templates](/templates.md). Templates work in `data.insert`, `data.update`, and `data.upsert`. ```json { "operation": "data.insert", "payload": { "collection": "orders", "data": { "product": "Notebook", "price": 12, "quantity": 3, "label": "{{ product }} x {{ quantity }}", "total": "&:{{ price * quantity }}", "slug": "{{ $slugify(product) }}", "created_on": "{{ $now() | date_format('YYYY-MM-DD') }}" } } } ``` **Result:** ```json { "product": "Notebook", "price": 12, "quantity": 3, "label": "Notebook x 3", "total": 36, "slug": "notebook", "created_on": "2026-10-03" } ``` Plain values and operators are applied first, then templates are rendered against the result. See [Templates](/templates.md) for the full syntax and helper list. --- ## Automations When enabled for the project and configured for a collection, automations can copy fields, generate slugs, or run AI tasks. Eligible local actions on insert run before persistence and can affect the returned document. Deferred actions, including AI work, run in the background after the write. Later queries can see their results. --- ## Common Errors | Message | Meaning | |---|---| | `MISSING_COLLECTION_NAME` | `payload.collection` is missing or blank | | `AUTHENTICATION_REQUIRED` | A scoped read or mutation has neither a signed-in user nor a privileged key | | `USER_NOT_FOUND` | A payload-level owner or reassignment names an unknown project user | | `USER_ID_UPDATE_REQUIRES_ADMIN` | A signed-in user tried to change `_user_id` | | `MISSING_DOCUMENT_ID` | An update without `filter` has a patch with no `_id` | | `MISSING_UPSERT_INSERT_DATA` | `insert_data` is missing | | `USER_ID_MISMATCH` | Requested scope differs from the signed-in user | | `INVALID_USER_ID_FILTER` | Ownership was placed inside a filter | | `OWNER_CHANGE_REQUIRES_SINGLE_DOCUMENT` | Owner reassignment was attempted with a filter, bulk update, or upsert | | `SCOPE_TOO_LARGE` | Scoped mutation selection exceeds its limit | | `DOCUMENT_NOT_FOUND` | A selected document is not owned by the scoped user | | `EXACTLY_ONE_ARCHIVE_SELECTOR_REQUIRED` | Archive or delete needs exactly one of `id`, `ids`, `filter` | Empty results are not errors: queries and writes return `data: []` and aggregate returns `data: {}`, with `message: "NO_DATA"`. --- ## Next Steps - [Query Syntax](/queries.md) - Filter operators, sorting, pagination, and search - [Templates](/templates.md) - Expressions and helper functions - [Authentication](/auth.md) - Get the ID token that scopes data to a user - [Agents](/agents.md) - Grant collection access to AI agents - [Conversation](/chat.md#docsets) - Search by meaning with docsets --- Canonical page: https://docs.singlebase.io/queries # Query Syntax Select documents with `filter`, then sort, paginate, and search the results. ## Overview **Filters** are JSON objects that describe which documents to match. The same syntax works everywhere a `filter` is accepted. **Where filters work:** - `data.query`, `data.count`, `data.aggregate`, `data.update`, `data.upsert`, `data.archive`, `data.delete` - `files.query` (fields belong to [file records](/files.md#files-query)) - `users.query` (fields must start with `data.`, see [Users](/users.md#users-query)) **Key features:** - Bare values mean equality - Inline operators: `"price:$gte": 10` - Comparison, array, string, type, and logical operators - Shortcuts for dates, missing values, and empty arrays or strings - Page-based or offset-based pagination **Example:** ```json { "operation": "data.query", "payload": { "collection": "products", "filter": { "status": "active", "price:$between": [10, 100], "tags:$includes": "sale" }, "sort": "price asc", "per_page": 20 } } ``` --- ## Filter Syntax Multiple conditions are joined with AND. ```json { "status": "active", "stats.views:$gte": 10, "tags:$includes": "api" } ``` Write an operator inline as `field:$operator`, or as a nested object. These are equivalent: ```json { "price:$gte": 10, "price:$lt": 100 } ``` ```json { "price": { "$gte": 10, "$lt": 100 } } ``` **Field paths:** - Dot notation for nested fields: `profile.city` - `[]` for array traversal: `people[].name`. `[*]` is not valid --- ## Complete Operator Index The following operators and shortcuts are accepted by `lib_kokoa.py`. Names are case-sensitive. Use `field:$operator` or a nested operator object, except logical operators, which belong at filter level. | Group | Supported names | |---|---| | Equality | `$eq`, `$ne` | | Ordered comparison | `$gt`, `$gte`, `$lt`, `$lte`, `$between` | | Presence and type | `$exists`, `$type` | | Membership | `$in`, `$nin`, `$includes`, `$nincludes`, `$all`, `$any`, `$none` | | Arrays | `$elemMatch`, `$size` | | Strings | `$startsWith`, `$endsWith`, `$contains`, `$ilike`, `$istartsWith`, `$iendsWith`, `$icontains`, `$regex` | | Logical | `$and`, `$or`, `$nor`, `$not` | | Date aliases | `$before`, `$after`, `$since`, `$until` | | Missing and empty values | `$orMissing`, `$nex`, `$empty`, `$blank` | | Range complement | `$outside` | ### Nested arrays and missing values ```json { "operation": "data.query", "payload": { "collection": "orders", "filter": { "items:$elemMatch": {"sku:$istartsWith": "bag-", "qty:$gte": 2}, "tags:$none": ["internal", "test"], "discount:$orMissing": {"$lte": 10}, "summary:$blank": false, "price:$outside": [20, 50] } } } ``` `$blank` checks the empty string, not whitespace. `$outside` uses strict comparisons beyond the two bounds. `$orMissing` also accepts a bare scalar, which means equality or absent/null. Use `$elemMatch` when several conditions must apply to the same array element; `people[].name` traverses an array field. ## Comparison and Presence | Operator | Matches | Example | |---|---|---| | `$eq` | Equal value | `"status:$eq": "active"` | | `$ne` | Present and different | `"status:$ne": "draft"` | | `$gt`, `$gte` | Greater than / greater than or equal | `"price:$gte": 10` | | `$lt`, `$lte` | Less than / less than or equal | `"price:$lt": 100` | | `$between` | Inclusive range | `"price:$between": [10, 100]` | | `$exists` | Present (`true`) or absent/null (`false`) | `"summary:$exists": true` | | `$type` | Value type | `"price:$type": "number"` | **Rules:** - Ordered comparisons accept numbers or strings, not booleans. - `$between` takes exactly two bounds. - `$ne` only matches documents where the field is present. Use `$nex` to include missing fields. - `$type` accepts `number`, `boolean`, `string`, `array`, `object`, `null`, `integer`, `real`, `text`, `true`, and `false`. --- ## Arrays and Membership | Operator | Matches | Example | |---|---|---| | `$in` | Value is in the list | `"status:$in": ["active", "draft"]` | | `$nin` | Value is not in the list | `"status:$nin": ["deleted"]` | | `$includes` | Array contains the value | `"tags:$includes": "api"` | | `$nincludes` | Array does not contain the value | `"tags:$nincludes": "internal"` | | `$all` | Array contains every listed value | `"tags:$all": ["api", "docs"]` | | `$any` | Array contains at least one listed value | `"tags:$any": ["api", "docs"]` | | `$none` | Array contains none of the listed values | `"tags:$none": ["internal", "draft"]` | | `$size` | Array length | `"tags:$size": {"$gte": 2}` | | `$elemMatch` | One array element matches a filter | `"items:$elemMatch": {"sku": "A1", "qty:$gte": 2}` | **Rules:** - List operands must not be empty. - `$size` accepts an integer, or an object using `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, and `$lte`. --- ## Strings | Operator | Matches | Example | |---|---|---| | `$startsWith` | Prefix | `"sku:$startsWith": "A-"` | | `$endsWith` | Suffix | `"email:$endsWith": "@example.com"` | | `$contains` | Substring | `"title:$contains": "API"` | | `$istartsWith`, `$iendsWith`, `$icontains` | Case-insensitive versions | `"title:$icontains": "api"` | | `$ilike` | Case-insensitive LIKE pattern | `"title:$ilike": "%api%"` | | `$regex` | Regular expression | `"slug:$regex": "^release-[0-9]+$"` | `$ilike` keeps `%` and `_` as LIKE wildcards. Invalid regular expressions are rejected. --- ## Logical Operators Use `$and`, `$or`, `$nor`, and `$not` at the filter level. ```json { "operation": "data.query", "payload": { "collection": "notes", "filter": { "status": "active", "$or": [ { "tags:$includes": "api" }, { "stats.views:$gte": 100 } ], "$not": { "title:$startsWith": "Internal" } } } } ``` | Operator | Takes | Matches when | |---|---|---| | `$and` | Non-empty array of filters | Every filter matches | | `$or` | Non-empty array of filters | At least one filter matches | | `$nor` | Non-empty array of filters | No filter matches | | `$not` | One filter object | The filter does not match | All top-level conditions still apply. Logical operators cannot be placed inside a field's operator object. --- ## Shortcuts Shortcuts expand into standard filters. | Shortcut | Meaning | Example | |---|---|---| | `$before`, `$after` | `$lt`, `$gt` | `"_created_at:$before": "2026-01-01"` | | `$since`, `$until` | `$gte`, `$lte` | `"_created_at:$since": "2026-01-01"` | | `$nex` | Not equal, or absent/null | `"plan:$nex": "free"` | | `$orMissing` | Matches the condition, or absent/null | `"price:$orMissing": {"$lt": 100}` | | `$empty` | `true`: array absent, null, or empty. `false`: present and non-empty | `"tags:$empty": true` | | `$blank` | `true`: string absent, null, or `""`. `false`: present and non-empty | `"summary:$blank": true` | | `$outside` | Below or above an inclusive range | `"price:$outside": [10, 100]` | `$orMissing` cannot contain another shortcut that expands into a logical clause. **Example - Documents created this year that are not marked free:** ```json { "filter": { "_created_at:$since": "2026-01-01", "plan:$nex": "free" } } ``` --- ## Sorting Pass `sort` to `data.query` as `" asc"` or `" desc"`. The default is `_created_at desc`. ```json { "operation": "data.query", "payload": { "collection": "products", "sort": "price asc" } } ``` --- ## Pagination Use page-based or offset-based pagination. Pick one style per request. **Page-based:** ```json { "operation": "data.query", "payload": { "collection": "notes", "page": 2, "per_page": 20 } } ``` **Offset-based:** ```json { "operation": "data.query", "payload": { "collection": "notes", "limit": 20, "offset": 20 } } ``` Pages start at 1. `data.query` defaults to `page: 1` and `per_page: 20`. **Pagination metadata:** ```json { "meta": { "pagination": { "total_items": 84, "count": 20, "per_page": 20, "page": 2, "total_pages": 5, "next_page": 3, "prev_page": 1 } } } ``` **Loop through documents with the JavaScript SDK:** The SDK returns `data` directly, so this offset loop stops when a batch is shorter than the requested limit. For a stable traversal, avoid concurrent inserts/deletes and choose a deterministic sort for your data. See [JavaScript SDK](/sdk-javascript.md). ```javascript const all = []; const limit = 100; for (let offset = 0; ; offset += limit) { const documents = await sbc.data.query({ collection: "notes", limit, offset, sort: "_id asc", }); all.push(...documents); if (documents.length < limit) break; } ``` **Other operations:** | Operation | Pagination | |---|---| | `files.query` | `page`/`per_page` (defaults `1` and `20`) or `limit`/`offset` | | `users.query` | `page`/`per_page` or `limit`/`offset`, no API defaults | | `chat.list` | `limit`/`offset` only | --- ## Search Use `search` with `data.query` for full-text search. Combine it with `filter` to narrow the matches. ```json { "operation": "data.query", "payload": { "collection": "articles", "search": "API documentation", "filter": { "status": "published" }, "per_page": 10 } } ``` Full-text search depends on the collection's configuration. To match text in one field, use a string operator such as `$icontains`. --- ## Next Steps - [Data](/data.md) - Query, update, and archive documents - [Templates](/templates.md) - Compute values on write - [Files](/files.md) - Query file records --- Canonical page: https://docs.singlebase.io/templates # Templates Templates compute values when you write documents. Use them to combine fields, do math, format dates, generate IDs, and clean up text, all inside the request. ::: v-pre ## Overview **Templates** are strings that contain `{{ ... }}` expressions. Singlebase renders them against the document being written, then saves the result. **Where templates work:** - `data` in [`data.insert`](/data.md#data-insert) and [`data.update`](/data.md#data-update) - `insert_data` and `update_data` in [`data.upsert`](/data.md#data-upsert) **Quick grammar:** | Syntax | Meaning | |---|---| | `{{ ... }}` | Expression. The result is a string | | `&:{{ ... }}` | Native expression. Keeps the type: number, boolean, array, object, or null | | `{{ $function() }}` | Helper function call | | `{{ $func1($func2(value)) }}` | Nested helper calls | | `{{ value \| len }}` | Filter | | `{{ $now() \| date_shift('2days') }}` | Helper call followed by a filter | **Example:** ```json { "operation": "data.insert", "payload": { "collection": "orders", "data": { "customer": "ada lovelace", "price": 12, "quantity": 3, "label": "{{ quantity }} x Notebook", "total": "&:{{ price * quantity }}", "customer_name": "{{ $titlecase(customer) }}", "order_ref": "{{ $uppercase($shortid()) }}", "due_on": "{{ $now() | date_shift('14days') | date_format('YYYY-MM-DD') }}" } } } ``` **Saved document:** ```json { "customer": "ada lovelace", "price": 12, "quantity": 3, "label": "3 x Notebook", "total": 36, "customer_name": "Ada Lovelace", "order_ref": "9F2C41AB", "due_on": "2026-10-17" } ``` --- ## Expression Syntax ### {{ }} - String Expression Evaluates the expression and returns a **string**. You can mix text and several expressions in one value. ```json { "greeting": "Hello {{ first_name }}!", "summary": "{{ title }} ({{ views }} views)" } ``` **Characteristics:** - Always returns a string - Supports interpolation with surrounding text - A missing field renders as an empty string --- ### &:{{ }} - Native Expression Evaluates the expression and returns its **native type**. ```json { "total": "&:{{ subtotal + tax }}", "is_large": "&:{{ total >= 100 }}", "tag_count": "&:{{ tags | len }}" } ``` **Result:** ```json { "total": 125.5, "is_large": true, "tag_count": 3 } ``` **Characteristics:** - Returns a number, boolean, string, array, object, or null - The whole value must be one expression: no surrounding text - Keeps the key even when the result is null or empty --- ### $function() - Helper Calls Call a [helper function](#helper-functions) with a `$` prefix inside any expression. ```json { "slug": "{{ $slugify(title) }}", "id_hash": "{{ $sha256(email) }}", "created": "{{ $now() }}" } ``` Helpers can be nested: ```json { "code": "{{ $uppercase($substring($trim(name), 0, 3)) }}" } ``` --- ### | filter - Filters Pipe a value through one or more [filters](#filters). Filters can follow a field or a helper call. ```json { "name_upper": "{{ name | trim | upper }}", "tag_count": "&:{{ tags | len }}", "expires_at": "{{ $now() | date_shift('30days') }}", "tag_list": "{{ tags | join(', ') }}" } ``` --- ## Expressions Inside `{{ ... }}` you can use: | Kind | Example | Result | |---|---|---| | Field | `{{ title }}` | Value of `title` | | Nested field | `{{ profile.city }}` | Value of `profile.city` | | Array index | `{{ items[0].name }}` | First item's `name` | | Math | `&:{{ price * quantity }}` | `36` | | Comparison | `&:{{ total >= 100 }}` | `true` | | Logic | `&:{{ in_stock and price < 50 }}` | `true` | | String concat | `{{ first_name ~ ' ' ~ last_name }}` | `"Ada Lovelace"` | | Literal | `&:{{ [1, 2, 3] }}` | `[1, 2, 3]` | Math operators are `+`, `-`, `*`, `/`, and `//`, and they only accept numbers. `+` also joins strings. `%`, `**`, and division by zero are not allowed. Logic uses `and`, `or`, and `not`. Templates run in a sandbox. Only `{{ ... }}` expressions are supported; `{% ... %}` blocks are not. **Evaluation order:** 1. Plain values and [data operators](/data.md#data-operators) are applied. 2. Templates are rendered against the result. So templates see the new values: ```javascript // Existing: { "views": 3 } { "views:$incr": 1, "views_label": "{{ views }} views" } // Result: { "views": 4, "views_label": "4 views" } ``` --- ## Helper Functions Call helpers as `$name(...)`. Arguments can be fields, literals, or other helpers. ### Date and Time | Helper | Description | Example | Result | |---|---|---|---| | `$now()` | Current UTC date and time, ISO 8601 | `{{ $now() }}` | `2026-10-03T12:00:00+00:00` | | `$date(value)` | Normalize a date to ISO 8601. Defaults to now | `{{ $date(published) }}` | `2026-01-15T10:00:00+00:00` | | `$date_format(date, format)` | Format a date. Alias `$formatdate` | `{{ $date_format(created, 'YYYY-MM-DD') }}` | `2026-01-15` | | `$date_shift(date, shift)` | Shift a date. Alias `$shiftdate` | `{{ $date_shift($now(), '+1 week') }}` | One week from now | **Formats:** `ISO`, `ISO_DATE`, `ISO_TIME`, `ISO_DATETIME`, or tokens such as `YYYY-MM-DD`, `MMM D, YYYY`, and `HH:mm`. **Shifts:** Combine signed amounts and units: `2days`, `+3 hours`, `-1 week`, `1 day - 3 hours`, `+2.5hours -30min`. Units are `y`/`year`, `mo`/`month`, `w`/`week`, `d`/`day`, `h`/`hour`, `min`/`minute`, and `s`/`second`, singular or plural. ### IDs and Hashing | Helper | Description | Example result | |---|---|---| | `$uuid()` | UUID v4 without dashes | `7918dbc69cdf440386816bbb4f0ec817` | | `$uuid4()` | UUID v4 with dashes | `49059b8c-3932-4784-bbb9-2e02ed05ae01` | | `$uuid7()` | Time-ordered UUID v7 | `01a100cb-f63d-7c03-855a-50e15703d3c5` | | `$shortid()` | 8-character random ID | `32fae10d` | | `$sha256(value)` | SHA-256 hex digest | `b5fc85e5...c41d72` | ### Strings | Helper | Description | Example | Result | |---|---|---|---| | `$uppercase(text)` | Uppercase. Alias `$upper` | `{{ $uppercase('api') }}` | `API` | | `$lowercase(text)` | Lowercase. Alias `$lower` | `{{ $lowercase('API') }}` | `api` | | `$titlecase(text)` | Capitalize each word. Alias `$title` | `{{ $titlecase('ada lovelace') }}` | `Ada Lovelace` | | `$capitalize(text)` | Capitalize the first letter | `{{ $capitalize('ada lovelace') }}` | `Ada lovelace` | | `$trim(text)` | Remove surrounding whitespace | `{{ $trim(' hi ') }}` | `hi` | | `$slugify(text)` | URL-friendly slug | `{{ $slugify('Hello World') }}` | `hello-world` | | `$substring(text, start, end)` | Slice a string | `{{ $substring('lovelace', 0, 4) }}` | `love` | | `$replace(text, old, new)` | Replace text | `{{ $replace('v1', 'v', 'version ') }}` | `version 1` | | `$concat(a, b, ...)` | Join values as text | `{{ $concat(first, ' ', last) }}` | `Ada Lovelace` | | `$truncate(text, words, suffix)` | Keep the first N words | `{{ $truncate(bio, 3, '...') }}` | `Hello world this...` | | `$strip_html(html)` | Remove HTML tags | `{{ $strip_html('Hi') }}` | `Hi` | | `$maskstr(text, visible, char)` | Mask all but the last N characters. Defaults `4`, `*` | `{{ $maskstr(card, 4) }}` | `************1234` | | `$count_words(text)` | Number of words | `&:{{ $count_words(body) }}` | `120` | | `$contains(text, part)` | Text contains a substring | `&:{{ $contains(title, 'API') }}` | `true` | | `$includes(value, item)` | String, array, or object contains an item | `&:{{ $includes(tags, 'api') }}` | `true` | | `$starts_with(text, prefix)` | Starts with a prefix | `&:{{ $starts_with(sku, 'A-') }}` | `true` | | `$ends_with(text, suffix)` | Ends with a suffix | `&:{{ $ends_with(email, '.edu') }}` | `false` | ### Numbers | Helper | Description | Example | Result | |---|---|---|---| | `$incr(value, by)` | Add `by` (default `1`). Missing values start at `0` | `&:{{ $incr(score, 5) }}` | `15` | | `$decr(value, by)` | Subtract `by` (default `1`) | `&:{{ $decr(stock) }}` | `9` | | `$to_int(value, default)` | Convert to an integer | `&:{{ $to_int('42') }}` | `42` | | `$to_float(value, default)` | Convert to a float | `&:{{ $to_float('4.2') }}` | `4.2` | | `$round(x)` | Round to the nearest integer | `&:{{ $round(2.6) }}` | `3` | | `$floor(x)` | Round down | `&:{{ $floor(2.6) }}` | `2` | | `$ceil(x)` | Round up | `&:{{ $ceil(2.1) }}` | `3` | | `$abs(x)` | Absolute value | `&:{{ $abs(-3) }}` | `3.0` | | `$random(min, max)` | Random integer. Defaults `0`, `100` | `&:{{ $random(1, 6) }}` | `4` | | `$to_currency(amount, currency)` | Currency text. Default `USD` | `{{ $to_currency(1234.5) }}` | `USD 1,234.50` | | `$to_percent(value, decimals)` | Percentage text. Default `1` decimal | `{{ $to_percent(0.256) }}` | `25.6%` | | `$to_ordinal(value)` | Ordinal text | `{{ $to_ordinal(3) }}` | `3rd` | ### Arrays and Objects | Helper | Description | Example | Result | |---|---|---|---| | `$len(value)` | Length of a string, array, or object. Alias `$length` | `&:{{ $len(tags) }}` | `3` | | `$sum(array)` | Sum of numbers | `&:{{ $sum(scores) }}` | `6.0` | | `$avg(array)` | Average of numbers | `&:{{ $avg(scores) }}` | `2.0` | | `$min(array)` | Smallest number | `&:{{ $min(scores) }}` | `1.0` | | `$max(array)` | Largest number | `&:{{ $max(scores) }}` | `3.0` | | `$sortby(array, key, reverse)` | Sort objects by a key | `&:{{ $sortby(items, 'qty', true) }}` | Highest `qty` first | | `$groupby(array, key)` | Group objects by a key | `&:{{ $groupby(items, 'type') }}` | `{"a": [...], "b": [...]}` | ### Conditions and Validation | Helper | Description | Example | Result | |---|---|---|---| | `$cond(condition, yes, no)` | If/else. Alias `$condition` | `{{ $cond(total > 100, 'large', 'small') }}` | `large` | | `$default(value, fallback)` | `fallback` when `value` is empty. `0` is kept | `{{ $default(nickname, 'Guest') }}` | `Guest` | | `$is_empty(value)` | Value is empty | `&:{{ $is_empty(tags) }}` | `false` | | `$is_null(value)` | Value is null or empty | `&:{{ $is_null(deleted_at) }}` | `true` | | `$is_truthy(value)` | Value is truthy | `&:{{ $is_truthy(flag) }}` | `true` | | `$is_falsey(value)` | Value is falsy | `&:{{ $is_falsey(flag) }}` | `false` | | `$is_not(value)` | Logical NOT | `&:{{ $is_not(archived) }}` | `true` | | `$is_email(value)` | Valid email address | `&:{{ $is_email(email) }}` | `true` | | `$is_url(value)` | Valid URL | `&:{{ $is_url(website) }}` | `true` | | `$is_ip(value)` | Valid IP address | `&:{{ $is_ip(ip) }}` | `true` | ### Encoding | Helper | Description | Example | Result | |---|---|---|---| | `$b64_encode(text)` | Base64-encode text | `{{ $b64_encode('hi') }}` | `aGk=` | | `$url_encode(text)` | URL-encode text | `{{ $url_encode('a b&c') }}` | `a%20b%26c` | --- ## Filters Apply filters with `|`. Chain them left to right. Filters that take arguments use parentheses. ```json { "title": "{{ raw_title | trim | title }}", "publish_on": "{{ $now() | date_shift('+1 day') | date_format('YYYY-MM-DD') }}" } ``` | Filter | Description | Example | |---|---|---| | `trim` | Remove surrounding whitespace | `{{ name \| trim }}` | | `upper`, `uppercase` | Uppercase | `{{ code \| upper }}` | | `lower`, `lowercase` | Lowercase | `{{ email \| lower }}` | | `title`, `titlecase` | Capitalize each word | `{{ name \| title }}` | | `capitalize` | Capitalize the first letter | `{{ name \| capitalize }}` | | `slugify` | URL-friendly slug | `{{ title \| slugify }}` | | `strip_html` | Remove HTML tags | `{{ body \| strip_html }}` | | `replace(old, new)` | Replace text | `{{ sku \| replace('-', '') }}` | | `truncate(length)` | Shorten to a character length | `{{ title \| truncate(40) }}` | | `len`, `length` | Length | `&:{{ tags \| len }}` | | `join(separator)` | Join an array | `{{ tags \| join(', ') }}` | | `first`, `last` | First or last item | `{{ tags \| first }}` | | `int`, `float`, `string`, `list` | Convert type | `&:{{ qty \| int }}` | | `round`, `abs`, `floor`, `ceil` | Number rounding and sign | `&:{{ price \| round }}` | | `incr(by)`, `decr(by)` | Add or subtract | `&:{{ score \| incr(5) }}` | | `date_format(format)` | Format a date | `{{ created \| date_format('MMM D, YYYY') }}` | | `date_shift(shift)` | Shift a date | `{{ $now() \| date_shift('2days') }}` | | `to_currency(currency)` | Currency text | `{{ price \| to_currency('EUR') }}` | | `to_percent(decimals)` | Percentage text | `{{ rate \| to_percent(2) }}` | | `to_int`, `to_float` | Convert to a number | `&:{{ qty \| to_int }}` | | `sha256` | SHA-256 hex digest | `{{ email \| sha256 }}` | | `b64_encode`, `url_encode` | Encode text | `{{ query \| url_encode }}` | | `default(value)` | Fallback for a missing field | `{{ nickname \| default('Guest') }}` | --- ## Common Patterns ### Display Name ```json { "display_name": "{{ $titlecase($trim(first_name ~ ' ' ~ last_name)) }}" } ``` ### Order Totals ```json { "subtotal": "&:{{ price * quantity }}", "tax": "&:{{ $round(price * quantity * 0.08) }}", "is_free_shipping": "&:{{ price * quantity >= 50 }}" } ``` ### Expiration Date ```json { "expires_at": "{{ $now() | date_shift('30days') }}" } ``` ### Content Preview ```json { "preview": "{{ $truncate($strip_html(body), 25, '...') }}", "word_count": "&:{{ $count_words($strip_html(body)) }}" } ``` ### Masking Sensitive Values ```json { "card_display": "{{ $maskstr(card_last_digits, 4) }}", "email_hash": "{{ $sha256($lowercase(email)) }}" } ``` --- ## Best Practices - **Use `&:` for numbers and booleans.** `{{ }}` always returns a string, so `"{{ price * 2 }}"` saves `"24"`, not `24`. - **Keep expressions short.** Move complex logic to your application code. - **Don't build counters with templates.** Template and operator writes read the document first, so concurrent writes can overlap. ::: --- ## Next Steps - [Data](/data.md) - Insert, update, and upsert documents - [Data Operators](/data.md#data-operators) - `$incr`, `$push`, `$unset`, and more - [Query Syntax](/queries.md) - Filter documents --- Canonical page: https://docs.singlebase.io/llm # LLM Bring model access and AI services alongside your data with `llm.*` operations. ## Overview **Intelligence** connects models to the data and documents your agents and apps already use. You don't need provider keys or prompt plumbing: send content and instructions, and get results back. **Models:** Choose a configured catalog model with `model`, or omit it to use `DEFAULT_MODEL` for generation. Available models depend on the deployed catalog; an unknown generation model is rejected. Embeddings use their own model default. **Key features:** - **Generation** - Write, translate, summarize, categorize, extract, and analyze sentiment - **Structured output** - JSON responses shaped by a JSON Schema - **Embeddings** - Vectors for one or many documents **Use cases:** Content tools, classification pipelines, data extraction, semantic search preparation **Access:** Generation and embeddings require a signed-in user (web key plus bearer token), or a server or permitted agent key without a bearer token. `chat.ask` remains public with a valid project key, subject to retrieval and attachment permissions. For persisted chats with history and Chat with Documents, see [Conversation](/chat.md). --- ## Operations | Operation | Description | Required payload | |---|---|---| | `llm.generate` | Generate content with a named built-in template | `content` or `input` | | `llm.write` | Write content | `content` or `input` | | `llm.translate` | Translate content | `content` or `input` | | `llm.summarize` | Summarize content | `content` or `input` | | `llm.categorize` | Classify content | `content` or `input` | | `llm.extract` | Extract entities or data | `content` or `input` | | `llm.analyze` | Analyze sentiment | `content` or `input` | | `llm.embed` | Create embeddings | `documents` | For chats, see [Conversation](/chat.md). --- ## Generation The seven generation operations share one payload. Each selects a built-in prompt for its task. **Generation parameters:** | Field | Description | |---|---| | `content` | String, object, or list of strings/objects; up to 200,000 converted characters | | `input` | Request, up to 4,000 characters; alias `user_input` | | `output` | `text` (default), `markdown`, or `json`; alias `format` | | `json_schema` | JSON structure; requires `output: "json"` | | `model` | Catalog model key; default `DEFAULT_MODEL` | | `prompt_template` | Built-in template name on `llm.generate` only; default `generic` | | `system` | Own instruction on `llm.generate` only; at most 8,000 characters | `content` is what the model reads, `input` is what you ask it to do with it. At least one is required and nonblank. Objects become structured Markdown; list items are converted without a `Data Records` title and joined with a blank line. Object items in multi-item lists have `## Item N` headings numbered by position; strings and single objects have none. Fixed operations ignore `prompt_template` and `system`. An explicitly sent `prompt_template` wins over `system`, including `generic`; otherwise nonblank `system` wins, falling back to `generic`. `system` alone cannot replace the required content/input. Named templates must exist in the deployed prompt catalog. Unknown names return `PROMPT_NOT_FOUND`. **Breaking change:** `custom_instructions`, `variables`, `prompt_name`, `prompt_md`, `params`, and `options` are silently ignored in generation. Use `input` for instructions. `output` is now an answer shape, not a dot path; `output: null` is invalid. Embedding and chat keep their own payloads. **Response:** ```json {"data": {"result": "SignalPeak\nUptimeLens\nPingWise"}, "meta": {"request_id": "req_123", "exec_time": 0.84}, "exec_time": 0.87} ``` JSON output returns parsed JSON in `data.result`. Each successful generation or embedding call records the existing `LLM_CALL` usage event. See [Templates](/templates.md) for template syntax. ### llm.generate ```json { "operation": "llm.generate", "payload": { "input": "Suggest three names for an API monitoring tool, one per line.", "prompt_template": "generic" } } ``` ### llm.write ```json { "operation": "llm.write", "payload": { "content": {"product": "Wireless headphones", "battery_hours": 30}, "input": "Write a friendly product description, under 60 words." } } ``` ### llm.translate ```json { "operation": "llm.translate", "payload": { "content": "Welcome to our developer platform.", "input": "Translate into French." } } ``` ### llm.summarize ```json { "operation": "llm.summarize", "payload": { "content": "The release adds direct file uploads, faster queries, and rotating refresh tokens. Existing clients must adopt the new request envelope.", "input": "Two bullets.", "output": "markdown" } } ``` ### llm.categorize ```json { "operation": "llm.categorize", "payload": { "content": "I was charged twice for my subscription.", "input": "Choose one: billing, technical, general." } } ``` ### llm.extract ```json { "operation": "llm.extract", "payload": { "content": "Jane Doe ordered two notebooks on October 3, 2026.", "input": "Extract customer, product, quantity, and order date.", "output": "json", "json_schema": { "type": "object", "properties": { "customer": { "type": "string" }, "product": { "type": "string" }, "quantity": { "type": "integer" }, "order_date": { "type": "string" } } } } } ``` ### llm.analyze ```json { "operation": "llm.analyze", "payload": { "content": "Setup was quick and the docs were easy to follow.", "input": "Return the sentiment and a one-sentence reason." } } ``` --- ## Embeddings ### llm.embed **Example - One string:** ```json { "operation": "llm.embed", "payload": { "documents": "A short cancellation policy." } } ``` **Example - Several documents:** ```json { "operation": "llm.embed", "payload": { "documents": [ { "id": "policy-1", "content": "Cancel at any time." }, { "id": "policy-2", "content": "Refunds take five days." } ], "embedding_content_path": "content" } } ``` **Parameters:** | Field | Description | |---|---| | `documents` | A string, an object, or a non-empty array of strings and objects (required) | | `embedding_content_path` | Field to embed in each object. Default `"content"`. Supports dot paths | | `model` | Embedding model | | `dimensions` | Positive vector size, when supported by the selected embedding model | | `params` | Extra provider options | Results keep the input order. Embedding does not store anything; save the vectors yourself if you need them. --- ## Common Errors | Message | Meaning | |---|---| | `AUTHENTICATION_REQUIRED`, `ACCESS_DENIED` | Missing user authentication or insufficient access for generation/embeddings | | `PROMPT_NOT_FOUND` | The generation template does not exist | | `CONTENT_TOO_LARGE` | Converted generation content exceeds 200,000 characters | | `INVALID_LLM_EMBED_PAYLOAD` | Embedding inputs or options are invalid | | `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 | | `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 chat handler failed (HTTP 502) | Model validation failures return HTTP 422. Other generation or embedding failures return HTTP 502 with the underlying error message; do not assume one fixed message for every model failure. See [Responses](/api.md#responses) for the error envelope. --- ## Next Steps - [Conversation](/chat.md) - Persisted chats and Chat with Documents - [Data](/data.md) - Store the content your docsets search - [Agents](/agents.md) - Give AI agents scoped LLM permissions Use [Chat](/chat.md#chat-ask) for one-off answers and persisted conversations, and [JavaScript SDK](/sdk-javascript.md#llm-generation-and-embeddings) for `sbc.llm` calls. --- Canonical page: https://docs.singlebase.io/chat # 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](#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](https://singlebase.io/components/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`](#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](/chat.md#modes) | | `retrieval` | Knowledge sources, such as [docsets](/chat.md#docsets) | | `attachments` | Up to 5 [attachments](/chat.md#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.md#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](#modes) | | `retrieval` | Knowledge sources. See [Retrieval](#retrieval) | | `attachments` | Up to 5 attachments. See [Attachments](#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](/data.md#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](/files.md) 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`](/files.md#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](/api.md#responses) for the error envelope. --- ## Next Steps - [LLM](/llm.md) - One-off answers, generation, and embeddings - [Files](/files.md) - Upload documents to use as attachments - [Data](/data.md) - Store the content your docsets search - [Agents](/agents.md) - 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](/data.md#overview). --- Canonical page: https://docs.singlebase.io/mcp-guide # MCP **Your project's data, ready for agent tools.** Connect an agent runtime to Singlebase with your project's MCP endpoint and an agent key. The tools use the same gateway permissions and data operations as your application's API calls. ## Overview MCP gives AI agents named tools for discovering collections, finding documents, changing records, and answering questions from project knowledge. **Key features:** - Six tools, with descriptions and examples an agent can use immediately. - Tool lists and collection choices tailored to the agent key's permissions. - The same ownership, automations, limits and usage tracking as the JSON API. - A project switch, disabled by default, and a platform-wide availability switch. - Stateless HTTP requests with an agent key on every call. **Use cases:** Coding assistants inspecting an application's data model, support agents answering policy questions, ingestion workers adding documents, and operations agents updating records within their assigned collections. **How it works:** 1. Create an [agent key](/agents.md) with the collections and feature permissions it needs. 2. Enable MCP for the project in the console. 3. Connect your MCP client with the project endpoint and agent key. 4. Let the client discover its tools. Calls go through the normal Singlebase gateway. ## Requirements You need a project endpoint key, an `agk_…` agent key, and MCP enabled for the project. Save `settings.mcp.enabled: true` through the console's project settings. The platform must also have MCP available; a global shutdown prevents projects from enabling it. MCP is for machines and agent runtimes. It has no user login, OAuth flow, or session setup. ## Endpoint and authentication ```http POST https://v1.api.singlebase.io/mcp/ Authorization: Bearer agk_ Content-Type: application/json Accept: application/json, text/event-stream ``` `X-API-KEY: agk_` is also accepted. Authenticate every request. Root, server and web keys, user bearer tokens, and signed requests are refused. The trailing-slash URL also works. GET returns 405; responses do not contain an `Mcp-Session-Id` or open a server message stream. The endpoint supports MCP Streamable HTTP with JSON responses and protocol revisions `2025-03-26`, `2025-06-18`, and `2025-11-25`. Clients negotiate a revision with `initialize` and can send it in `MCP-Protocol-Version` on subsequent calls. ## Connect a client ### Claude Code ```bash claude mcp add --transport http singlebase \ 'https://v1.api.singlebase.io/mcp/' \ --header 'Authorization: Bearer agk_' ``` See the [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp) for configuration scopes and credential options. ### Cursor Add a remote server to your MCP configuration: ```json { "mcpServers": { "singlebase": { "url": "https://v1.api.singlebase.io/mcp/", "headers": {"Authorization": "Bearer ${env:SINGLEBASE_AGENT_KEY}"} } } } ``` Set `SINGLEBASE_AGENT_KEY` in the environment available to Cursor. See [Cursor's MCP configuration](https://cursor.com/docs/mcp) for configuration locations. ### Claude Desktop and stdio clients For a client configuration that launches local commands, use the [`mcp-remote` bridge](https://github.com/punkpeye/mcp-remote). It forwards requests to the HTTP endpoint and sends the configured agent-key header: ```json { "mcpServers": { "singlebase": { "command": "npx", "args": [ "-y", "mcp-remote", "https://v1.api.singlebase.io/mcp/", "--header", "Authorization:${SINGLEBASE_AUTH_HEADER}" ], "env": {"SINGLEBASE_AUTH_HEADER": "Bearer agk_"} } } } ``` This requires Node.js and the bridge. The gateway itself does not use OAuth. Keep the configuration containing the key private. ### Raw HTTP Initialize the connection using your actual endpoint and key: ```bash curl 'https://v1.api.singlebase.io/mcp/' \ -H 'Authorization: Bearer agk_' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' ``` The response names the server `singlebase`, advertises tools, and provides instructions describing this key's collections, permissions and filter syntax. Normal MCP clients send `notifications/initialized` next; it receives an empty HTTP 202 response. No server session is created. List this key's tools: ```bash curl 'https://v1.api.singlebase.io/mcp/' \ -H 'X-API-KEY: agk_' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-11-25' \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' ``` Call a tool: ```bash curl 'https://v1.api.singlebase.io/mcp/' \ -H 'X-API-KEY: agk_' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-11-25' \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_documents","arguments":{"collection":"orders","limit":5}}}' ``` ## Tools | Tool | Purpose | Permission | | --- | --- | --- | | `list_collections` | Discover collection descriptions, fields, indexes and permissions | Any collection permission | | `search_documents` | Return documents using filters or full-text search | `read`; text search also needs `search` | | `insert_documents` | Add one or more documents | `write` | | `update_documents` | Update documents by ID or filter | `write` | | `delete_documents` | Archive documents by ID, IDs or filter | `delete` | | `ask_documents` | Get a written answer with sources from project documents | `ai.chat` and an available knowledge source | Only available tools are listed. Schemas describe exact collection enums for each permission, including their console descriptions. Read tools advertise `readOnlyHint`; update advertises `idempotentHint`, and delete advertises `destructiveHint`. These annotations guide the client; gateway checks enforce access. ### list_collections Call with `{}`. The result includes the collections assigned to this key, their descriptions, field types, indexes and the key's permissions. Field information combines the declared schema with a one-document sample when the key has read access. Sample values are not returned. ```json {"name":"list_collections","arguments":{}} ``` ### search_documents Returns matching documents. Use a filter alone for a query, or add `search` for full-text search with the same filter. Required: `collection`. Optional: `search`, `filter`, `fields` (an array of field names), `sort`, `limit` (1–100, default 20), `page` (starting at 1), `_user_id`. The search argument names the collections where this key can use full-text search. ```json {"name":"search_documents","arguments":{"collection":"orders","filter":{"total:$gte":100},"fields":["_id","total"],"limit":10}} ``` Filters use the normal [query syntax](/queries.md). Put ownership selectors at the argument root; `_user_id` inside a filter is refused. ### insert_documents Required: `collection` and `data` (an object or list of objects). Optional: root `_user_id`, to assign an owner. Documents are unowned when an agent key does not specify ownership. Collection create automations run normally. ```json {"name":"insert_documents","arguments":{"collection":"notes","_user_id":"user-123","data":[{"text":"Follow up"},{"text":"Send receipt"}]}} ``` ### update_documents Required: `collection` and `data`. Identify documents using `_id` in the data, or pass `filter` to apply the changes to matching documents. App automations follow the normal update path. ```json {"name":"update_documents","arguments":{"collection":"orders","data":{"_id":"ord_123","status":"shipped"}}} ``` ### delete_documents Required: `collection` and exactly one of `id`, `ids`, or `filter`. This uses `data.delete`, with the normal archive retention. It does not permanently purge documents. ```json {"name":"delete_documents","arguments":{"collection":"notes","ids":["note_123","note_456"]}} ``` ### ask_documents Answers a question in plain language from project documents, citing its sources. Use this for a written answer; use `search_documents` when you need the matching records themselves. Required: `question` and at least one of `collections` or `docsets`. `collections` accepts 1–10 readable collection names; `docsets` accepts 1–5 enabled agent-accessible docset IDs shown in the tool schema. Calls use `llm.ask` in `kb` mode. Readable collections with `search` use text retrieval; without it, the answer uses up to 20 documents from the collection. Docsets use their configured retrieval and ACL rules. ```json {"name":"ask_documents","arguments":{"question":"What is our refund policy?","docsets":["docset-123"]}} ``` ## Permissions Agent keys decide which tools and collections appear. A read-only key lists discovery and search. Write enables insert and update; delete enables deletion; `ai.chat` enables answering when a readable collection or allowed docset exists. Changing the key takes effect on the next request. A name invented by a model does not grant access: out-of-scope collections return `AGENT_SCOPE_DENIED`. Docsets with user/admin ACLs and disabled docsets are unavailable to agents. MCP cannot use a full server key or sign in as a user. See [Agents](/agents.md) for key management, expiry and ownership rules. ## Results and errors A successful call returns a tool result inside the JSON-RPC `result`: ```json { "jsonrpc": "2.0", "id": 3, "result": { "structuredContent": {"data": [{"_id": "ord_123", "total": 150}], "pagination": {"total_items": 1}}, "content": [{"type":"text","text":"{\"data\":[{\"_id\":\"ord_123\",\"total\":150}],\"pagination\":{\"total_items\":1}}"}], "isError": false } } ``` `structuredContent.data` holds the full gateway result. Pagination is included when available; ask results retain their answer and sources. The text fallback is compact JSON capped around 20 KB, followed by a note if truncated. The full structured result remains available. Gateway and argument failures return `isError: true` with the error code and message in text and an error object in structured content. Unknown tools, bad JSON-RPC, and malformed JSON produce protocol errors instead. | HTTP status | Meaning | | --- | --- | | `401` | Invalid/disabled agent key, another credential type, or `AGENT_KEY_EXPIRED` | | `403` | `MCP_DISABLED_FOR_PROJECT`, or an unauthorized supplied Origin | | `405` | Method other than POST while the service is enabled | | `503` | `MCP_DISABLED`, maintenance, offline service, or database unavailable | ## Limits Each tool call counts as its mapped gateway operation, using the same rate limits and usage recording as an API call with that agent key. AI work uses the normal model metering. Call metrics include `surface: "mcp"`. MCP has no separate tool quota. JSON requests are limited to 10 MB; the 20 KB text limit affects only the fallback, not the structured result. JSON-RPC batches are not supported. --- Canonical page: https://docs.singlebase.io/auth # Authentication Register users, sign them in, and manage their sessions with `auth.*`. Read and update the signed-in user's profile with `user.*`. ## Overview **Identity** gives your users a way in. Every project includes a complete user system: sign-up, sign-in, sessions, and access control, with no backend code. Your agents work with your data; your users get their own accounts and see their own records. **Key features:** - Email and password signup and signin - Passwordless signin with one-time email codes - OAuth with Google, GitHub, Facebook, and LinkedIn - Short-lived ID tokens with rotating refresh tokens - Password reset, email change, and username change with codes - Self-service profile updates **How it works:** 1. The user signs in with `auth.signin` and receives an `id_token` and a `refresh_token`. 2. Your app sends `Authorization: Bearer ` on requests that act as the user. 3. Before the ID token expires, call `auth.refresh` to get a new pair. To create or manage users from your server or an agent, use [Users](/users.md). To add sign-in to a website without writing UI, use the [Auth UI](https://singlebase.io/components/auth-ui/) web component. --- ## Operations | Operation | Description | Bearer token | |---|---|---| | `auth.settings` | Read public authentication settings | No | | `auth.signup` | Create an email/password account | No | | `auth.signin` | Sign in with a password or an email code | No | | `auth.refresh` | Rotate session tokens | No (tokens go in the payload) | | `auth.signout` | Revoke all of the user's sessions | Required | | `auth.request_code` | Email a one-time code for a purpose | No | | `auth.confirm_code` | Reset a password or change email/username with a code | No | | `auth.change_password` | Set a new password for the current user | Required | | `auth.nonce` | Get a nonce for OAuth | No | | `auth.oauth_connect` | Start OAuth signin, signup, or account linking | No | | `auth.oauth_signin` | Exchange an OAuth access code for a session | No | | `user.get` | Get the current user's profile | Required | | `user.update` | Update the current user's profile | Required | **Audience:** Authentication flows that use account identity accept `aud`, which defaults to `"web"`. `auth.settings` and `auth.nonce` need no payload fields. Use the same audience for the whole flow. Self-service signup always uses the default audience and roles. --- ## Sign Up ### auth.signup Create an email/password account. ```json { "operation": "auth.signup", "payload": { "email": "jane@example.com", "password": "ExamplePass123!", "first_name": "Jane", "last_name": "Doe", "metadata": { "plan": "free" } } } ``` **Parameters:** | Field | Required | Description | |---|---|---| | `email` | Yes | Email address. Stored in lowercase | | `password` | Yes | Must meet the project's password policy | | `first_name` | Yes | First name. Alias `name` | | `last_name` | No | Last name. Alias `surname` | | `phone` | No | Phone number. Alias `phone_number` | | `profile_photo` | No | Photo URL. Alias `photo_url` | | `metadata` | No | Custom profile data | **Response:** ```json { "data": { "id": "8f14e45fceea167a5a36dedd4bea2543", "next_action": "SIGNIN", "next_operation": "auth.signin" } } ``` **Behavior:** - Signup does not sign the user in. Call `auth.signin` next. - `next_action` is `SIGNIN_WITH_CODE` when the project requires email verification or an email second factor. - The response is the same whether or not the email already exists, so it never reveals registered accounts. - Email subaddresses such as `jane+app@example.com` are rejected. - Sending `roles` or a custom `aud` returns `CUSTOM_SIGNUP_CLAIMS_NOT_ALLOWED`. --- ## Sign In ### auth.signin **Example - Password:** ```json { "operation": "auth.signin", "payload": { "email": "jane@example.com", "password": "ExamplePass123!" } } ``` **Example - Email code** (after [`auth.request_code`](#auth-request-code) with `purpose: "signin"`): ```json { "operation": "auth.signin", "payload": { "email": "jane@example.com", "grant_type": "code", "code": "123456" } } ``` **Parameters:** | Field | Description | |---|---| | `email` | Email address (required) | | `grant_type` | `"password"` (default) or `"code"` | | `password` | Password, for password signin | | `code` | One-time code, for code signin. Alias `otp` | | `purpose` | `"invite"` when accepting an invitation | When the project requires email verification or an email second factor, send both `password` and `code`. **Response:** ```json { "data": { "id_token": "", "refresh_token": "", "token_type": "bearer", "user_profile": { "id": "user_123", "email": "jane@example.com", "first_name": "Jane", "last_name": "Doe", "aud": "web", "roles": ["user"] }, "next_action": null, "next_operation": null, "token_info": { "ttl": 900, "exp": 1791044100, "iat": 1791043200, "aud": "web", "id": "user_123" } } } ``` The profile is abbreviated. See [`user.get`](#user-get) for every field. **Tokens:** - **id_token** - Send as `Authorization: Bearer `. Lasts 15 minutes - **refresh_token** - Store securely. Exchange with `auth.refresh`. Sessions last 30 days **Example - Accept an invitation:** Request a code with `purpose: "invite"`, then set the password while signing in: ```json { "operation": "auth.signin", "payload": { "email": "jane@example.com", "grant_type": "code", "purpose": "invite", "code": "123456", "password": "ExamplePass123!" } } ``` --- ## Sessions ### auth.refresh Get a new token pair. The ID token may already be expired, but its session must still be valid. ```json { "operation": "auth.refresh", "payload": { "id_token": "", "refresh_token": "" } } ``` Returns a new session, in the same shape as `auth.signin`. Replace both stored tokens: the old refresh token is consumed, and reusing it fails. ### auth.signout Revoke every session for the current user. Send the ID token in the `Authorization` header. ```json { "operation": "auth.signout", "payload": {} } ``` Returns `data: {"signout": true}`. Clear the tokens stored in your app. **Example - Keep a session alive:** ```javascript async function refreshSession(session) { const result = await singlebase('auth.refresh', { id_token: session.id_token, refresh_token: session.refresh_token }); return result.data; // store the new id_token and refresh_token } ``` --- ## One-Time Codes ### auth.request_code Email a one-time code for a specific purpose. ```json { "operation": "auth.request_code", "payload": { "email": "jane@example.com", "purpose": "password_reset" } } ``` **Response:** ```json { "data": { "accepted": true, "purpose": "password_reset", "next_action": "RESET_PASSWORD_WITH_CODE", "next_operation": "auth.confirm_code" } } ``` | Purpose | `next_action` | Next operation | Field to send with the code | |---|---|---|---| | `signin` | `SIGNIN_WITH_CODE` | `auth.signin` | None | | `invite` | `ACCEPT_INVITE_WITH_CODE` | `auth.signin` | `password` | | `password_reset` | `RESET_PASSWORD_WITH_CODE` | `auth.confirm_code` | `new_password` | | `email_change` | `CHANGE_EMAIL_WITH_CODE` | `auth.confirm_code` | `new_email` | | `username_change` | `CHANGE_USERNAME_WITH_CODE` | `auth.confirm_code` | `new_username` | **Behavior:** - Codes expire after 10 minutes and work once. - Codes are bound to the account, audience, and purpose. - `accepted: true` does not reveal whether the account exists or a code was sent. - Password recovery and account changes require the matching email-code setting in the project. ### auth.confirm_code Use a code to reset a password or change an email or username. ```json { "operation": "auth.confirm_code", "payload": { "email": "jane@example.com", "purpose": "password_reset", "code": "123456", "new_password": "NewExamplePass123!" } } ``` **Parameters:** | Field | Description | |---|---| | `email` | Current account email (required) | | `purpose` | `password_reset`, `email_change`, or `username_change` (required) | | `code` | One-time code (required). Alias `otp` | | `new_password`, `new_email`, `new_username` | The value for the purpose (required) | For an email change, the code goes to the current email. The new email starts unverified. Confirmation revokes existing sessions and returns a new session. Store the new tokens. --- ## Passwords ### auth.change_password Set a new password for the signed-in user. Send the ID token in the `Authorization` header. ```json { "operation": "auth.change_password", "payload": { "password": "NewExamplePass123!" } } ``` Revokes existing sessions and returns a new session. Send plain passwords only; `password_hash` and `password_algo` are rejected. **Forgot password flow:** 1. `auth.request_code` with `purpose: "password_reset"` 2. The user enters the emailed code 3. `auth.confirm_code` with `code` and `new_password` 4. Store the session it returns --- ## OAuth Sign users in with Google, GitHub, Facebook, or LinkedIn. Providers must be enabled in the project. **Flow:** 1. Call `auth.nonce` and keep the nonce in the browser. 2. Call `auth.oauth_connect` with the provider, nonce, and intent. 3. Redirect the browser to `oauth_redirect_url`. 4. The provider returns to Singlebase, which redirects to your project's OAuth return URL with an `access_code`. 5. Call `auth.oauth_signin` with the `access_code` and the same nonce. ### auth.nonce ```json { "operation": "auth.nonce", "payload": {} } ``` Returns `data: {"nonce": ""}`. The nonce expires after 10 minutes. ### auth.oauth_connect ```json { "operation": "auth.oauth_connect", "payload": { "provider": "google", "nonce": "", "intent": "signin" } } ``` **Parameters:** | Field | Description | |---|---| | `provider` | `google`, `github`, `facebook`, or `linkedin` (required) | | `nonce` | Nonce from `auth.nonce` (required) | | `intent` | `signin` (default), `signup`, or `link` | | `id_token`, `refresh_token` | Current session. Required for `link` | OAuth signup requires a verified email. Names are optional; if the provider omits a name, the full email address is used as `first_name`. **Response:** ```json { "data": { "oauth_redirect_url": "https://accounts.google.com/o/oauth2/v2/auth?...", "oauth_provider": "google" } } ``` **Return URL parameters:** | Parameter | Meaning | |---|---| | `access_code` | Success. Exchange it with `auth.oauth_signin` | | `error=oauth_denied` | The user cancelled at the provider | | `oauth_error=` | The flow failed. See the codes below | | `oauth_error` | Meaning | |---|---| | `OAUTH_VERIFICATION_FAILED` | The provider response could not be verified | | `VERIFIED_PROVIDER_EMAIL_REQUIRED` | The provider did not return a verified email | | `SIGN_IN_TO_LINK_PROVIDER` | The email belongs to an account; sign in, then link | | `PROVIDER_ALREADY_LINKED` | The provider identity belongs to another account | | `OAUTH_SIGNUP_DISABLED`, `OAUTH_SIGNIN_DISABLED` | The project disabled OAuth signup or signin | | `MISSING_OAUTH_CODE` | The provider did not return a code | | `INVALID_CREDENTIALS`, `INVALID_TOKEN` | The account or linking session is invalid | | `REQUIRE_PASSWORD_CHANGE` | The account must change its password first | | `OAUTH_FAILED` | Unexpected failure | ### auth.oauth_signin ```json { "operation": "auth.oauth_signin", "payload": { "access_code": "", "nonce": "" } } ``` The access code expires after 10 minutes and works once. Returns a session. For `intent: "link"`, the exchange also completes the link. **Example - Browser flow:** ```javascript // 1. Start const { data: { nonce } } = await singlebase('auth.nonce'); sessionStorage.setItem('oauth_nonce', nonce); const { data } = await singlebase('auth.oauth_connect', { provider: 'github', nonce, intent: 'signin' }); window.location.href = data.oauth_redirect_url; // 2. On your return URL const params = new URLSearchParams(window.location.search); const accessCode = params.get('access_code'); if (accessCode) { const session = await singlebase('auth.oauth_signin', { access_code: accessCode, nonce: sessionStorage.getItem('oauth_nonce') }); } ``` --- ## Settings ### auth.settings Read the project's public authentication settings to build your signin screens. ```json { "operation": "auth.settings", "payload": {} } ``` **Response:** ```json { "data": { "enabled": true, "auth_settings": { "enabled": true, "allow_signin": true, "allow_signup": true, "signin_method": "password", "second_factor": null, "signup_verify_email": false, "password_policy": {} }, "oauth_settings": { "enabled": true, "allow_signin": true, "allow_signup": true, "redirect_url": "https://app.example.com/auth/callback" }, "oauth_providers": { "google": { "enabled": true, "name": "Google" } } } } ``` Values are illustrative. Provider credentials are never returned. --- ## Current User Use [the Current User API](/user.md) to read and update the account in your bearer token. It cannot select another user. ### user.get See [user.get](/user.md#user-get) for the request and profile response. ### user.update See [user.update](/user.md#user-update) for editable profile fields. --- ## Common Errors | Message | Meaning | |---|---| | `EMAIL_SIGNUP_DISABLED`, `EMAIL_SIGNIN_DISABLED` | The project disabled this method | | `INVALID_CREDENTIALS` | Wrong email, password, or code, or the account is inactive | | `CODE_REQUIRED` | The project requires a code with the password | | `REQUIRE_PASSWORD_CHANGE` | The account must reset its password before signing in | | `INVALID_BEARER_TOKEN` | The ID token or its session is invalid | | `AUTHENTICATION_REQUIRED` | The operation needs a bearer token | | `AGENT_KEY_EXPIRED` | The agent key reached its expiry; returns 401 before scope checks or usage tracking. Extend it or remove its expiry through `console.update_agent_key` | | `CUSTOM_SIGNUP_CLAIMS_NOT_ALLOWED` | Signup sent roles or a custom audience | | `VERIFICATION_DISABLED` | Email codes are disabled for this change | | `INVALID_NONCE` | The OAuth nonce is invalid, expired, or does not match | | `MISSING_PROFILE_DATA` | `user.update` had no supported fields | See [Responses](/api.md#responses) for the error envelope. --- ## Next Steps - [Data](/data.md) - Store data owned by the signed-in user - [Files](/files.md) - Let users upload files - [Users](/users.md) - Manage users from your server --- Canonical page: https://docs.singlebase.io/user # Current User `user.*` operations act on the account in the bearer token. A payload cannot select another user. ## user.get ```json { "operation": "user.get", "payload": {} } ``` **Response:** ```json { "data": { "id": "user_123", "email": "jane@example.com", "username": null, "phone": null, "first_name": "Jane", "last_name": "Doe", "profile_photo": null, "status": "active", "requires_password_change": false, "email_verified_at": "2026-10-03T12:00:00+00:00", "phone_verified_at": null, "created_at": "2026-10-01T09:30:00+00:00", "modified_at": "2026-10-03T12:00:00+00:00", "timezone": "America/New_York", "locale": "en-US", "metadata": { "plan": "free" }, "aud": "web", "roles": ["user"] } } ``` ## user.update ```json { "operation": "user.update", "payload": { "first_name": "Jane", "timezone": "America/New_York", "locale": "en-US", "metadata": { "theme": "dark" } } } ``` **Updatable fields:** `first_name` (alias `name`), `last_name` (alias `surname`), `phone` (alias `phone_number`), `profile_photo` (alias `photo_url`), `timezone`, `locale`, and `metadata`. Send at least one field. Null values are ignored. Returns the updated profile. To change email, username, or password, use [codes](/auth.md#one-time-codes) or [`auth.change_password`](/auth.md#auth-change-password). To set a profile photo from an upload, see [Files](/files.md#profile-photos). ## Next Steps - [Authentication](/auth.md): signup, signin, credentials, and session tokens. - [Users administration](/users.md): manage any project user from server code. --- Canonical page: https://docs.singlebase.io/users # Users Manage your project's users from a trusted server or AI agent with `users.*` operations. ## Overview **Users** is the admin side of Identity: the API for your project's user records, the same accounts that sign in through [Authentication](/auth.md). Call it from your backend, or let a support or ops agent manage users within the permissions you grant. **Key features:** - Create users, with or without a password - Look up users by ID, email, username, or linked provider - Search and paginate users - Update profiles and application data - Suspend users, with scheduled status transitions - Soft-delete or permanently purge users - Link and unlink OAuth provider identities **Use cases:** Admin dashboards, back-office tools, imports, support agents, moderation **Access:** Admin only. Call `users.*` with a server key (`sk_`). An [agent key](/agents.md) can call permitted user operations, including `users.get_details` with `users.list`; agent keys can never call `users.get`. Don't send a bearer token: with one, the request acts as that user and is denied. Never call these operations from a browser. ::: tip Self-service vs admin - A signed-in user reads and edits **their own** profile with [`user.get` and `user.update`](/user.md). - Your server manages **any** user with `users.*`. - Passwords, codes, and sessions belong to [`auth.*`](/auth.md). ::: --- ## Operations | Operation | Description | Selector | |---|---|---| | `users.create` | Create a user | None | | `users.get` | Get one user | One of `user_id`, `id`, `email`, `username`; or `provider` + `provider_user_id` | | `users.get_details` | Get a user with providers, login methods, and recent events | One of `user_id`, `id`, `email`, `username` | | `users.query` | Search and list users | None | | `users.update` | Update profile and application data | `user_id` or `id` | | `users.update_status` | Change status, optionally on a schedule | `user_id` or `id` | | `users.update_password` | Set a new password | `user_id` or `id` | | `users.delete` | Soft-delete or purge a user | `user_id` or `id` | | `users.link_provider` | Link a provider identity | `user_id` or `id` | | `users.unlink_provider` | Unlink a provider identity | Provider identity | `id` is an alias for `user_id` in selectors. Send one or the other, not both. --- ## User Fields | Field | Description | |---|---| | `id` | User ID | | `email`, `username`, `phone` | Identity fields | | `first_name`, `last_name`, `profile_photo` | Profile fields | | `status` | `active` by default. Other values are up to your app, such as `suspended` or `banned` | | `requires_password_change` | When `true`, the user must reset their password before signing in | | `email_verified_at`, `phone_verified_at` | Verification times | | `data` | Application data: `timezone`, `locale`, `metadata`, and `claims` | **Roles** live in `data.claims`, keyed by audience. For example, `{"web": ["user"]}` gives the role `user` in the `web` audience. Only `active` users that are not deleted can sign in. --- ## users.create ```json { "operation": "users.create", "payload": { "email": "ada@example.com", "password": "ExamplePass123!", "first_name": "Ada", "last_name": "Lovelace", "data": { "timezone": "Europe/London", "locale": "en-GB", "metadata": { "plan": "pro" }, "claims": { "web": ["user", "editor"] } } } } ``` **Parameters (all optional):** | Field | Description | |---|---| | `user_id` | Your own ID. A UUID is generated when omitted | | `email`, `username`, `phone` | Identity fields | | `first_name`, `last_name`, `profile_photo` | Profile fields | | `password` | Plain password. It is checked against the password policy and stored hashed | | `status`, `status_reason` | Initial status. Default `active` | | `requires_password_change` | Force a password reset on first signin. Default `false` | | `provider`, `provider_user_id` | A provider identity your server has already verified | | `data` | Application data. `claims` defaults to `{"web": ["user"]}` | **Behavior:** - No welcome email is sent and no session is created. Use [`auth.signup`](/auth.md#auth-signup) for the normal signup flow. - `password_hash` and `password_algo` are rejected. Send `password`. - Put roles in `data.claims`, not `data.auth.claims`. --- ## users.get ```json { "operation": "users.get", "payload": { "email": "ada@example.com" } } ``` **Example - By provider identity:** ```json { "operation": "users.get", "payload": { "provider": "github", "provider_user_id": "827364" } } ``` **Response:** ```json { "data": { "item": { "id": "user_123", "email": "ada@example.com", "first_name": "Ada", "last_name": "Lovelace", "status": "active", "data": { "claims": { "web": ["user"] } } } } } ``` The record is returned under `data.item`. Admin responses are not filtered like [`user.get`](/user.md#user-get); don't forward them to public clients. --- ## users.get_details Get a user with linked providers, login methods, and recent identity events. ```json { "operation": "users.get_details", "payload": { "user_id": "user_123" } } ``` Accepts one of `user_id`, `id`, `email`, or `username`. To look up by provider, call `users.get` first. --- ## users.query ```json { "operation": "users.query", "payload": { "status": "active", "search": "ada", "filter": { "data.metadata.plan:$in": ["pro", "enterprise"] }, "page": 1, "per_page": 25 } } ``` **Parameters (all optional):** | Field | Description | |---|---| | `search` | Matches ID, email, username, or phone. Alias `q` | | `status`, `email`, `username` | Exact matches | | `filter` | [Filter](/queries.md) on application data. Paths must start with `data.` | | `page`, `per_page` | Page-based pagination | | `limit`, `offset` | Offset-based pagination | Returns users in `data` and pagination in `meta.pagination`. Use `status`, `email`, and `username` instead of filtering those fields. --- ## users.update ```json { "operation": "users.update", "payload": { "user_id": "user_123", "first_name": "Ada", "data": { "timezone": "Europe/London" } } } ``` **Updatable fields:** `email`, `username`, `phone`, `first_name`, `last_name`, `profile_photo`, `requires_password_change`, `email_verified_at`, `phone_verified_at`, `data` **Behavior:** - `data` is merged deeply; nested fields you omit are kept. - To replace `data` entirely, send `"data": {"$replace": {...}}`. This can remove `claims`, so use it with care. - Status and passwords have their own operations. --- ## users.update_status Suspend, ban, or reactivate a user. Optionally schedule the next status. ```json { "operation": "users.update_status", "payload": { "user_id": "user_123", "status": "suspended", "status_reason": "Payment overdue", "status_expires_in": 172800, "status_next": "active", "status_next_reason": "Suspension ended", "changed_by": "admin:42" } } ``` **Parameters:** | Field | Description | |---|---| | `status` | New status (required) | | `status_reason` | Why it changed | | `status_expires_in` | Seconds until `status_next` applies | | `status_expires_at` | Time when `status_next` applies. Use one expiration field only | | `status_next` | Status to apply when the current one expires. Required with an expiration | | `status_next_reason` | Reason for the scheduled change | | `changed_by` | Who made the change, for the audit trail | A non-`active` status blocks new signins. Session verification also checks that the user is active, so suspended or deleted users cannot continue authenticated requests. Status updates do not themselves consume every stored session token. --- ## users.update_password ```json { "operation": "users.update_password", "payload": { "user_id": "user_123", "password": "NewExamplePass123!" } } ``` The password is checked against the policy and stored hashed. Existing sessions are revoked. Returns `data: {"id": "user_123", "updated": true}`. --- ## users.delete ```json { "operation": "users.delete", "payload": { "user_id": "user_123", "status_reason": "User requested deletion" } } ``` **Soft delete (default):** Sets `status` to `deleted`, revokes sessions, and keeps the email and provider identities reserved. **Purge:** Add `"purge": true` to permanently remove the user, providers, tokens, and identity events. ::: danger Purging cannot be undone. It does not delete the user's documents or files. Remove those separately with [`data.delete`](/data.md#data-delete) and [`files.delete`](/files.md#files-delete). ::: --- ## Provider Identities ### users.link_provider ```json { "operation": "users.link_provider", "payload": { "user_id": "user_123", "provider": "github", "provider_user_id": "827364", "email": "ada@example.com" } } ``` Requires a user selector, `provider`, and `provider_user_id`. Optional: `email`, `data`. Only link identities your server has verified. ### users.unlink_provider ```json { "operation": "users.unlink_provider", "payload": { "provider": "github", "provider_user_id": "827364" } } ``` Requires `provider` and `provider_user_id`. `user_id` or `id` is optional. --- ## Common Errors | Message | Meaning | |---|---| | `AUTHENTICATION_REQUIRED`, `ACCESS_DENIED` | The caller is not a server or agent key, or the request included a user's bearer token | | `AGENT_SCOPE_DENIED` | The agent key lacks the needed `users.*` permission | | `INVALID_PAYLOAD` | Missing or conflicting selectors, or an invalid status schedule | | `MISSING_USER_SELECTOR` | No user selector was sent | See [Responses](/api.md#responses) for the error envelope. --- ## Next Steps - [Authentication](/auth.md) - Signup, signin, and sessions for end users - [Agents](/agents.md) - Let an AI agent manage users with scoped permissions - [Data](/data.md) - Query documents owned by a user --- Canonical page: https://docs.singlebase.io/files # Files Upload, organize, and serve files with `files.*` operations. ## Overview **Storage** is a home for the files your users upload and the reports, documents, and images your agents produce. Singlebase keeps a record for each object. Uploads go straight from the client to storage, so large files never pass through your API requests. **Key features:** - Direct-to-storage uploads with signed upload tokens - Batch uploads (up to 10 files by default) - Logical buckets with allowed file types - Public or private access, with time-limited signed URLs - Optional knowledge indexing, so uploaded documents become context for agents and chat - Profile photo uploads **Use cases:** Avatars, attachments, agent-generated reports, knowledge documents for [Chat with Documents](/chat.md#attachments) **On your website:** The [File Uploader](https://singlebase.io/components/file-uploader/) web component runs this upload flow for you. --- **Access:** File storage operations require a signed-in user (bearer token), or a server, root, or permitted agent key. Operations on an existing file check that the user owns it. Admin callers can act on any file. ## Operations | Operation | Description | |---|---| | `files.initiate_upload` | Get signed upload credentials | | `files.complete_upload` | Verify uploaded objects and create file records | | `files.fail_upload` | Report a failed upload | | `files.query` | Query file records | | `files.get_signed_url` | Get a temporary download URL | | `files.update` | Update metadata or public access | | `files.reprocess` | Retry ingestion or resume failed indexing | | `files.delete` | Delete one or more files and their records | --- ## Upload Workflow Uploading takes three steps: 1. **Initiate** - Call `files.initiate_upload`. Keep each `id` and `upload_token`. 2. **Upload** - `POST` the file to the returned storage `url` with the returned `fields`. 3. **Complete** - Call `files.complete_upload` with the same `id` and `upload_token`. If the upload failed, call `files.fail_upload` instead. **Requirements:** - File storage is enabled for the project. - The bucket exists, is enabled, and allows the file's type. - Files are between 100 bytes and 10 MB (10,485,760 bytes). - Upload credentials and tokens expire after 30 minutes (1800 seconds). **File types:** | Type | Extensions | |---|---| | `IMAGE` | `png`, `gif`, `jpeg`, `jpg`, `webp` | | `DOCUMENT` | `txt`, `md`, `rtf`, `tex`, `pdf`, `pptx`, `docx`, `xlsx`, `odp`, `odt`, `ods`, `epub` | | `DATA` | `csv`, `json`, `xml`, `html`, `htm` | Each bucket lists the types it accepts. ### files.initiate_upload ```json { "operation": "files.initiate_upload", "payload": { "files": [ { "filename": "report.pdf", "content_type": "application/pdf", "bucket": "default", "public_read": false, "metadata": { "category": "reports" } } ] } } ``` **Parameters (each item in `files`):** | Field | Required | Description | |---|---|---| | `filename` | Yes | File name with an allowed extension | | `content_type` | No | MIME type | | `bucket` | No | Logical bucket name. Default `"default"` | | `new_name` | No | Rename the stored file | | `public_read` | No | Make the file publicly readable. Default `false` | | `metadata` | No | Your own data. Alias `info` | | `options` | No | Upload options, such as `{"profile_photo": true}` | `files` is always an array, even for one file. The batch limit defaults to 10. **Response:** ```json { "data": [ { "id": "7b21f51e730d40d0b0e373ef720e43d5", "upload": { "url": "https://storage.example.com/", "fields": { "key": "project/7b21f51e730d40d0b0e373ef720e43d5.pdf", "Content-Type": "application/pdf", "policy": "", "x-amz-signature": "" } }, "upload_token": "" } ] } ``` Results keep the input order. Send every `fields` entry unchanged. Do not decode or modify `upload_token`. Initiation does not create a file record. ### Upload to storage This browser example uses the [`singlebase` helper](/api.md#_4-a-reusable-request-helper). `file` is a browser `File`. ```javascript // 1. Initiate const init = await singlebase('files.initiate_upload', { files: [{ filename: file.name, content_type: file.type }] }, idToken); const item = init.data[0]; // 2. Upload directly to storage const form = new FormData(); for (const [name, value] of Object.entries(item.upload.fields)) { form.append(name, value); } form.append('file', file); // the file goes last const uploaded = await fetch(item.upload.url, { method: 'POST', body: form }); // 3. Complete, or report the failure if (!uploaded.ok) { await singlebase('files.fail_upload', { files: [{ id: item.id, upload_token: item.upload_token, error: `HTTP ${uploaded.status}` }] }, idToken); throw new Error('Upload failed'); } const done = await singlebase('files.complete_upload', { files: [{ id: item.id, upload_token: item.upload_token }] }, idToken); console.log(done.data[0].url); ``` Let the browser set the multipart `Content-Type`. Do not send Singlebase headers to the storage URL. ### files.complete_upload ```json { "operation": "files.complete_upload", "payload": { "files": [ { "id": "7b21f51e730d40d0b0e373ef720e43d5", "upload_token": "" } ] } } ``` **Response:** ```json { "data": [ { "id": "7b21f51e730d40d0b0e373ef720e43d5", "owner_id": "user_123", "filename": "report.pdf", "filesize": 248311, "content_type": "application/pdf", "fileclass": "DOCUMENT", "file_extension": "pdf", "bucket": "default", "status": "completed", "acl": "private", "metadata": { "category": "reports" }, "url": "https://storage.example.com/project/7b21f51e730d40d0b0e373ef720e43d5.pdf", "object_uri": "s3://app-files/project/7b21f51e730d40d0b0e373ef720e43d5.pdf", "object_key": "project/7b21f51e730d40d0b0e373ef720e43d5.pdf" } ] } ``` The response is abbreviated. Completion checks the token, the object's existence, size, and content type, then creates the record. Calling it again with the same token returns the same record. A private file's `url` is not directly readable. Use [`files.get_signed_url`](#files-get-signed-url). ### files.fail_upload ```json { "operation": "files.fail_upload", "payload": { "files": [ { "id": "7b21f51e730d40d0b0e373ef720e43d5", "upload_token": "", "error": { "code": "UPLOAD_FAILED", "message": "Connection lost" } } ] } } ``` Each item requires `id`, `upload_token`, and `error`. Returns `[{"id": "...", "change": "error"}]`. No file record is created. **Batch behavior:** Upload batches run concurrently and are not transactional. Some files can complete while others fail. ### Profile photos Set `options.profile_photo: true` on an image upload. Completing it also sets the owner's `profile_photo`. ```json { "operation": "files.initiate_upload", "payload": { "files": [ { "filename": "avatar.jpg", "content_type": "image/jpeg", "bucket": "avatars", "public_read": true, "options": { "profile_photo": true } } ] } } ``` --- ## files.query Query file records. ```json { "operation": "files.query", "payload": { "owner_id": "user_123", "content_type": "application/pdf", "status": "completed", "page": 1, "per_page": 20 } } ``` **Parameters (all optional):** | Field | Description | |---|---| | `bucket` | Logical bucket | | `status` | Record status, such as `completed` | | `owner_id`, `owner_type` | Owner | | `content_type` | MIME type | | `storage_backend` | Storage backend | | `search` | Text search. Alias `q` | | `filter` | Additional [filter](/queries.md) | | `page`, `per_page` | Defaults `1` and `20` | | `limit`, `offset` | Offset pagination | Returns file records in `data` and pagination in `meta.pagination`. To get one record, use `filter: {"id": ""}` and `limit: 1`. ::: warning `files.query` automatically scopes signed-in users to their own files. Another payload-level `owner_id` or a non-user `owner_type` returns `OWNER_ID_MISMATCH`. Server and agent keys can query across owners or choose a payload-level `owner_id`. Never put `owner_id` or `owner_type` inside `filter`: that returns `INVALID_OWNER_ID_FILTER`. ::: Query results are raw file records (for example `size_bytes` instead of `filesize`). They do not have exactly the same shape as upload results. --- ## files.get_signed_url Get a temporary URL for a private file. ```json { "operation": "files.get_signed_url", "payload": { "id": "7b21f51e730d40d0b0e373ef720e43d5", "signed_ttl": 3600 } } ``` **Response:** ```json { "data": { "url": "https://storage.example.com/...&X-Amz-Signature=..." } } ``` Send `id`, or an `s3://` object URI in `url`. `signed_ttl` defaults to 1800 seconds and is limited to 1 to 604800 seconds (7 days). Ownership is checked. | `variant` | Object signed | |---|---| | `original` (default) | Original uploaded file | | `markdown` | Stored `metadata.md_file` from DocLLM conversion | | `docv` | Stored `metadata.docv_file`, the full `.docv.json` result | For example, use `{"id": "file_123", "variant": "markdown", "signed_ttl": 3600}` to open the converted Markdown. All variants require the owner or an admin and use the same response and TTL rules. Agent keys need `files.read`. Conversion URLs are signed from the file's stored metadata; callers cannot supply their path. Missing Markdown returns `404 FILE_MARKDOWN_NOT_FOUND`; missing JSON returns `404 FILE_DOCV_NOT_FOUND`. A ready conversion saves `src_file`, `src_bytes`, `md_file`, `md_bytes`, `docv_file` and `docv_bytes` as flat `metadata` keys returned by `files.query`, and under `__file` in private documents and Smart Bucket copies. `src_file` is the original record's permanent S3 path. Source size comes from DocLLM, or the record's `size_bytes` when missing. Output paths must be S3 URIs and sizes non-negative integers; missing or invalid output values are null. The Markdown and JSON fields clear when conversion restarts or fails, and are null for script-supplied content. Indexing-only retries preserve them. These fields are gateway-owned and cannot be set through user metadata or content. Conversion statistics are also stored as flat `metadata` keys and in `__file`: `src_file_total_pages`, `md_file_total_pages`, `total_words` and `chunk_count`. They come from DocLLM's `statistics` object and must be non-negative integers. Missing page/word values are null; an omitted `chunk_count` uses the number of saved chunks. Invalid values are null. Statistics clear with conversion outputs on restart, ingestion failure, or script-supplied content, and are gateway-owned. --- ## files.update Update a file's metadata or access. ```json { "operation": "files.update", "payload": { "id": "7b21f51e730d40d0b0e373ef720e43d5", "public_read": true, "metadata": { "category": "approved" } } } ``` **Parameters:** | Field | Description | |---|---| | `id` | File ID (required) | | `metadata` | Merged into existing metadata (shallow) | | `public_read` | Change public access on the stored object | | `filename` (alias `name`) | Rename the existing file record | | `content_type`, `status`, `expires_at` | Record fields | | `_xsync` | `true` refreshes size and status from storage | | `_xlock` | `true` locks the file against deletion | Returns the updated file information. There is no public unlock. --- ## files.reprocess Retry document processing for an uploaded file you own. Admin and root callers can retry any uploaded file. Agent keys need the `files.upload` permission and always follow owner retry rules, even with an admin role. Web keys and anonymous callers are refused. ```json { "operation": "files.reprocess", "payload": {"id": "file_123"} } ``` `id` (alias `_id`) is required. The file's upload `status` must be `completed`. Work runs in the background; the immediate response is: ```json { "data": { "id": "file_123", "doc_processing_status": "pending", "doc_processing_step": null, "doc_processing_attempts": 2 } } ``` If processing failed at indexing and ready, nonblank chunks remain, the response has `doc_processing_status: "indexing"` and `doc_processing_step: "indexing"`; only vector indexing runs. Other eligible retries submit a new DocLLM job and ignore the previous job's callback. A retry increments attempts once. Owners and agents may retry failed or unprocessed files, with four total starts per file (the first run plus three retries). They cannot restart completed processing. Admins and root may restart completed processing and have no attempt limit. Everyone must wait while active processing was updated less than 30 minutes ago; stuck processing at least 30 minutes old may be restarted. Query the file with `files.query` to read the seven gateway-managed flags at the top level of its `metadata`: `doc_processing_status`, `doc_processing_step`, `doc_processing_error`, `doc_processing_updated_at`, `doc_processing_attempts`, `file_ingested`, and `file_indexed`. Status moves through `pending`, `ingestion`, `indexing`, and `completed`, or `failed` with the last step and a short error. Unqueued files start with null status, zero attempts, and false flags. These flags also appear in the private document and Smart Bucket copies under `__file`. User metadata and script content cannot set them. **Errors:** | Condition | Status | Error | |---|---|---| | Unknown file or no write access | 404 | `FILE_NOT_FOUND` | | Upload incomplete | 409 | `FILE_NOT_COMPLETED` | | Active processing updated less than 30 minutes ago | 409 | `FILE_PROCESSING_IN_PROGRESS` | | Completed processing requested by an owner or agent | 403 | `FILE_ALREADY_PROCESSED` | | Owner or agent already started processing four times | 429 | `FILE_REPROCESS_LIMIT` | | Agent lacks `files.upload` | 403 | `AGENT_SCOPE_DENIED` | | Web key or unauthenticated caller | 401/403 | Authentication required | | Caller tries to write processing flags through `files.update` | 400 | `INVALID_FILE_METADATA_FIELD` | --- ## files.delete Delete one file by `id`, or a batch by `ids`. ```json { "operation": "files.delete", "payload": { "id": "file_123" } } ``` **Response:** ```json { "data": { "ids": ["file_123"], "change": "deleted" } } ``` For batch deletion: ```json { "operation": "files.delete", "payload": { "ids": ["file_123", "file_locked", "file_456"], "purge": false } } ``` **Batch response:** ```json { "data": { "ids": ["file_123", "file_456"], "failed": [{"id": "file_locked", "error": "FILE_LOCKED"}], "change": "deleted" } } ``` **Parameters:** | Field | Description | |---|---| | `id` (alias `_id`) | One file ID; required unless `ids` is provided | | `ids` | Between 1 and 100 nonempty file IDs; selects batch behavior | | `purge` | Permanently remove metadata records; default `false` | **Behavior:** - Provide `id`, `ids`, or both. Both are merged with `id` first; duplicates are removed in order. The merged selection cannot exceed 100 files. - The stored object is always deleted. `purge` (default `false`) only controls whether the record is also removed permanently. - A single `id` raises on failure. When `ids` is supplied, only successful deletions appear in the response's `ids`; each failure appears in `failed`, which is empty when all files succeed. Individual failures do not stop the batch. - Unknown files and files the caller cannot write both report `FILE_NOT_FOUND`, so callers cannot probe other users' IDs. Admins can delete other users' files. - Batches run up to 10 files concurrently. Unexpected failures are logged and reported as `FILE_NOT_DELETED`. - Deletion also removes the private `__files` document and queues vector cleanup. - Stored Markdown and `.docv.json` output objects are deleted too. Cleanup errors are logged without failing the file deletion. - Deleting a profile photo clears the owner's `profile_photo`. - Authentication and agent-key permission for `files.delete` remain required. **Errors:** | Condition | Status | Error | |---|---|---| | Neither `id` nor `ids` | 400 | `INVALID_PAYLOAD` with `MISSING_FILE_ID` in validation details | | Empty IDs, empty batch, or more than 100 IDs | 400 | `INVALID_PAYLOAD` | | Unknown file or no write access | 404 | `FILE_NOT_FOUND` | | Locked file | 403 | `FILE_LOCKED` | | Linked documents | 409 | `CANT_DELETE_FILE_HAS_LINKED_DOCUMENTS` | | Record deletion fails | 500 | `FILE_NOT_DELETED` | For batches, file errors appear as messages in `failed` rather than rejecting the request. Authentication and payload validation errors still reject the whole request. ::: danger File bytes cannot be recovered after `files.delete`, even when `purge` is `false`. ::: --- ## Common Errors | Message | Meaning | |---|---| | `FILE_FORBIDDEN` | The user does not own the file | | `FILE_BUCKET_NOT_FOUND`, `FILE_BUCKET_DISABLED` | The bucket is missing or disabled | | `FILE_TYPE_NOT_ALLOWED` | The bucket does not accept this file type | | `FILE_UPLOAD_LIMIT_EXCEEDED` | Too many files in one upload batch | | `UPLOADED_OBJECT_NOT_FOUND` | Nothing was uploaded to storage | | `CONTENT_TYPE_MISMATCH`, `INVALID_UPLOADED_OBJECT` | The stored object does not match the upload | | `FILE_LOCKED`, `CANT_DELETE_FILE_HAS_LINKED_DOCUMENTS` | The file cannot be deleted | | `FILE_NOT_UPLOADED`, `FILE_NOT_CONVERTABLE` | The source is incomplete or cannot be converted | See [Responses](/api.md#responses) for the error envelope. --- ## Next Steps - [LLM](/llm.md) - Chat with uploaded files as attachments - [Authentication](/auth.md) - Get the ID token for uploads - [Agents](/agents.md) - Grant file permissions to AI agents --- Canonical page: https://docs.singlebase.io/api-reference # API Reference Find the operation for your task, then open its service reference for payloads, responses, and access rules. All operations use the same JSON endpoint and `operation`/`payload` envelope. See [API overview](/api.md) for headers, keys, batches, and errors. Agents can also call selected operations through the project's [MCP server](/mcp-guide), using an agent key and the same gateway scope, ownership, automation and usage rules. Examples and SDK calls use the canonical namespaces below. Chat operations are grouped under `chat`, separate from generation and embeddings under `llm`. Internal maintenance operations and unpublished endpoints are outside this public reference. ## Data [Full data reference](/data.md). | Operation | Purpose | |---|---| | `data.query` | Retrieve documents | | `data.count` | Count matching documents | | `data.aggregate` | Compute aggregate values | | `data.insert` | Insert one or more documents | | `data.update` | Update documents by `_id` or filter | | `data.upsert` | Update matches, or insert when nothing matches | | `data.archive` | Archive documents with optional retention | | `data.delete` | Archive documents with seven-day retention | ## Files [Full files reference](/files.md). | Operation | Purpose | |---|---| | `files.initiate_upload` | Get signed upload credentials | | `files.complete_upload` | Verify uploaded objects and create file records | | `files.fail_upload` | Report a failed upload | | `files.query` | Query file records | | `files.get_signed_url` | Get a temporary download URL | | `files.update` | Update metadata or public access | | `files.reprocess` | Retry ingestion or resume failed indexing | | `files.delete` | Delete one or more files and their records | ## Authentication [Full authentication reference](/auth.md). | Operation | Purpose | |---|---| | `auth.settings` | Read public authentication settings | | `auth.signup` | Create an email/password account | | `auth.signin` | Sign in with a password or an email code | | `auth.refresh` | Rotate session tokens | | `auth.signout` | Revoke all of the user's sessions | | `auth.request_code` | Email a one-time code for a purpose | | `auth.confirm_code` | Reset a password or change email/username with a code | | `auth.change_password` | Set a new password for the current user | | `auth.nonce` | Get a nonce for OAuth | | `auth.oauth_connect` | Start OAuth signin, signup, or account linking | | `auth.oauth_signin` | Exchange an OAuth access code for a session | ## Current user [Full current user reference](/user.md). | Operation | Purpose | |---|---| | `user.get` | Read the signed-in profile | | `user.update` | Update the signed-in profile | ## Users administration [Full users administration reference](/users.md). | Operation | Purpose | |---|---| | `users.create` | Create a user | | `users.get` | Get one user | | `users.get_details` | Get a user with providers, login methods, and recent events | | `users.query` | Search and list users | | `users.update` | Update profile and application data | | `users.update_status` | Change status, optionally on a schedule | | `users.update_password` | Set a new password | | `users.delete` | Soft-delete or purge a user | | `users.link_provider` | Link a provider identity | | `users.unlink_provider` | Unlink a provider identity | | `users.create_token` | Create a stored user token record | | `users.get_token` | Get a stored token record | | `users.consume_token` | Consume a stored token | | `users.revoke_token` | Revoke a token or token kind | ## LLM generation and embeddings [Full llm generation and embeddings reference](/llm.md). | Operation | Purpose | |---|---| | `llm.generate` | Generate content with a named built-in template | | `llm.write` | Write content | | `llm.translate` | Translate content | | `llm.summarize` | Summarize content | | `llm.categorize` | Classify content | | `llm.extract` | Extract entities or data | | `llm.analyze` | Analyze sentiment | | `llm.embed` | Create embeddings | ## Chat and retrieval [Full chat and retrieval reference](/chat.md). | Operation | Purpose | |---|---| | `chat.ask` | Ask without saving a conversation | | `chat.prepare` | Prepare context and starter questions | | `chat.send` | Start a conversation or continue one | | `chat.list` | List conversations | | `chat.get` | Get a conversation and its messages | | `chat.update` | Rename or bookmark a conversation | | `chat.bookmark` | Bookmark or unbookmark a conversation | | `chat.delete` | Delete a conversation | | `chat.bookmark_message` | Bookmark or unbookmark one message | | `chat.delete_message` | Delete one message | | `chat.remove_attachment` | Remove a saved attachment from a conversation | User-token operations require admin/server access and are denied to agent keys. They manage stored token records; browser apps should use the authentication session APIs. Their payload selectors are: | Operation | Payload | |---|---| | `users.create_token` | `user_id` or `id`, `kind`, `token_hash`; optional `expires_at` or `expires_in`, `allow_multi`, `data` | | `users.get_token`, `users.consume_token` | `kind`, `token_hash` | | `users.revoke_token` | `token_id`, or `user_id` and `kind` | ## SDKs - [JavaScript SDK](/sdk-javascript.md): service namespaces such as `sbc.data`, `sbc.llm`, and `sbc.chat`. - [Python](/sdk-python.md), [Go](/sdk-go.md), [PHP](/sdk-php.md), and [Ruby](/sdk-ruby.md): copyable server clients with one call method and a full Result envelope. --- Canonical page: https://docs.singlebase.io/sdk-javascript # JavaScript SDK The existing `@singlebase/singlebase-sdk` package connects your application to Singlebase services through one client. Use it from a browser with a web key and user session, or from your backend with a server or agent key. ## Install ```sh npm install @singlebase/singlebase-sdk ``` ## Connect Set `baseUrl` to the complete project endpoint copied from the console. Leave `urlAccessKey` unset when the endpoint already includes its key. ```javascript import { SinglebaseClient } from "@singlebase/singlebase-sdk"; const sbc = SinglebaseClient({ baseUrl: "https://v1.api.singlebase.io/api/", apiKey: "wk_", }); // Compatibility for releases that expose chat only through service(). sbc.chat ??= sbc.service("chat"); ``` Current SDK builds expose `sbc.chat` directly. Older releases can create the same namespace through `sbc.service("chat")`; the compatibility line above supports both. `sbc.llm` handles generation and embeddings; `sbc.chat` handles answers and conversations. | Option | Behavior | |---|---| | `baseUrl` | API URL; defaults to `https://v1.api.singlebase.io`. Set the full console endpoint to avoid ambiguity. HTTPS is required outside localhost | | `urlAccessKey` | Optional key appended as one encoded path segment; omit it when using a full endpoint | | `apiKey` | Sent as `X-API-Key` | | `audience` | Token audience; default `web` | | `fetch` | Optional Fetch-compatible transport | | `auth` | Session storage, auto-refresh, cross-tab, and event configuration | Use only a web key in browser code. Keep server, root, and agent keys in backend environment variables. A signed-in user automatically owns their inserted documents and sees only their scoped data and files; trusted calls without a bearer follow their key permissions. See [API keys](/api.md#api-keys) and [Ownership](/data.md#ownership). ## Calls and results Namespace methods map to `.` and accept a payload. The SDK returns the response's `data`, not the whole envelope. ```javascript const notes = await sbc.data.query({ collection: "notes", limit: 10 }); const profile = await sbc.user.get(); const count = await sbc.data.count({ collection: "notes" }); ``` The second argument controls request options, an explicit bearer, or cancellation: ```javascript const controller = new AbortController(); const notes = await sbc.data.query({ collection: "notes", limit: 10 }, { options: {}, signal: controller.signal, }); // Server-side only: no signed-in user identity. const data = await sbc.dispatch({ operation: "data.query", payload: { collection: "notes" }, options: {}, }, { bearer: null }); ``` `dispatch()` also returns `data`. For `meta` and gateway `exec_time`, use the HTTP envelope or one of the small server clients below. They have a different return contract. The SDK injects the current session's bearer token by default and can refresh a stale token once before retrying. Set `bearer: null` to suppress the user token, or supply an explicit token. An explicit bearer does not use automatic refresh. ## Errors ```javascript import { SinglebaseError } from "@singlebase/singlebase-sdk"; try { await sbc.data.query({ collection: "notes" }); } catch (error) { if (error instanceof SinglebaseError) { console.error(error.code, error.status, error.type, error.details); } else { throw error; } } ``` API failures throw `SinglebaseError`, including stable `code`, HTTP `status`, `type`, `details`, and `traceId`. Do not log keys or bearer tokens. ## Authentication and current user ```javascript await sbc.auth.signIn({ email: "jane@example.com", password: "" }); const settings = await sbc.auth.getSettings(); const profile = await sbc.user.get(); await sbc.user.update({ first_name: "Jane" }); console.log(sbc.isAuthenticated()); await sbc.auth.logout(); ``` | Auth method | API operation | |---|---| | `getSettings()` | `auth.settings` | | `signUp(payload)` | `auth.signup` | | `signIn(payload)` | `auth.signin` | | `refreshSession()` | `auth.refresh` | | `logout()` | `auth.signout` | | `requestCode(payload)` | `auth.request_code` | | `resetPassword(payload)`, `changeEmail(payload)` | `auth.confirm_code` | | `changePassword(payload)` | `auth.change_password` | | `startOAuth(payload)` | OAuth nonce and `auth.oauth_connect` flow | | `completeOAuth(payload)` | `auth.oauth_signin` | Read [Authentication](/auth.md) for payloads and project settings. Auth methods include session behavior; generic service namespaces such as `sbc.user`, `sbc.users`, and `sbc.data` map directly to operation names. `sbc.users` is for trusted server or permitted agent calls, without a user bearer. ## Documents ```javascript const inserted = await sbc.data.insert({ collection: "notes", data: { title: "First note", status: "active" }, }); const notes = await sbc.data.query({ collection: "notes", filter: { status: "active" }, per_page: 20, }); await sbc.data.update({ collection: "notes", data: { _id: "", title: "Updated note" }, }); ``` Available operations: `query`, `count`, `aggregate`, `insert`, `update`, `upsert`, `archive`, and `delete`. See [Data](/data.md) for selectors, ownership, templates, and search. ## Files ```javascript const files = await sbc.files.query({ per_page: 20 }); const download = await sbc.files.get_signed_url({ id: "" }); ``` For browser uploads, the SDK orchestrates direct-to-storage transfer and completion: ```javascript // input is an HTML file input element with selected files. const { completed, failed } = await sbc.files.upload(input.files, { bucket: "reports", onProgress: ({ input, percent }) => console.log(percent), }); ``` Use a bucket configured for your project. `upload()` reports each file separately. The low-level methods `initiateUpload()`, `uploadToRemote()`, `completeUpload()`, and `failUpload()` support custom upload flows. See [Files](/files.md). ## LLM generation and embeddings ```javascript const summary = await sbc.llm.summarize({ content: "", input: "Summarize in three bullets.", }); const embeddings = await sbc.llm.embed({ documents: [{ content: "A lightweight laptop backpack" }], }); ``` Generation methods are `generate`, `write`, `translate`, `summarize`, `categorize`, `extract`, and `analyze`. Embeddings use `embed`. Use `content` or `input` for generation, and `documents` for embeddings. Read [LLM](/llm.md) for actual payloads and model access. ## Chat answers and conversations ```javascript const answer = await sbc.chat.ask({ message: "What changed in Q3?" }); let turn = await sbc.chat.send({ message: "Plan a launch", format: "markdown" }); turn = await sbc.chat.send({ chat_id: turn._id, message: "Make it shorter" }); const prepared = await sbc.chat.prepare({ key: "order-4411", retrieval: [{ source: "json", data: { order_id: "order-4411", status: "shipped" } }], starters: true, }); const chat = await sbc.chat.get({ key: "order-4411" }); ``` Use `ask` for a one-off answer and `send` for saved conversations. Other operations are `prepare`, `list`, `get`, `update`, `bookmark`, `delete`, `bookmark_message`, `delete_message`, and `remove_attachment`. Key-based chats require a signed-in identity. See [Chat](/chat.md) for docsets, modes, retrieval, and access. Legacy chat aliases under `llm` may still be accepted by the backend, but new integrations should use the separate `chat` namespace. ## Sources and other languages This guide adapts the [JavaScript SDK specification](https://github.com/singlebase/singlebase-js/blob/main/docs/sdk.md), checking payloads against the backend and namespace behavior against SDK source. - [Python client](/sdk-python.md) - [Go client](/sdk-go.md) - [PHP client](/sdk-php.md) - [Ruby client](/sdk-ruby.md) - [Grouped API reference](/api-reference.md) --- Canonical page: https://docs.singlebase.io/sdk-python # Python SDK A small client you can copy into your backend. This is a documented implementation, not a separately published package. It sends the same API envelope for every service through one `call` method. Python 3.10+; standard library only. Async calls run blocking HTTP I/O in a worker thread. ## Response contract | Field | Meaning | |---|---| | `data` | Operation result; absent on API errors | | `error` | API error object, or null/nil on success; `message` is the stable code | | `meta` | Response metadata, including pagination when returned | | `exec_time` | Gateway execution time in seconds, when returned | API errors return in `Result.error`. Network, invalid JSON, and transport failures raise an exception or return a Go error. These small clients do not manage sessions, auto-refresh tokens, or retry requests. Pass a current user bearer token to the constructor/client only when acting as that user; omit it for trusted server/agent calls. Keep keys on the server. ## Client implementation Save as `singlebase.py`. [Download the source](/examples/singlebase.py). ```python import asyncio import json from dataclasses import dataclass, field from typing import Any from urllib.error import HTTPError from urllib.request import Request, urlopen @dataclass class Result: data: Any = None error: dict | None = None meta: dict = field(default_factory=dict) exec_time: float | None = None class singlebaseClient: def __init__(self, api_key: str, api_url: str, bearer: str | None = None): self.api_key, self.api_url, self.bearer = api_key, api_url, bearer async def call(self, operation: str, payload: dict, options: dict | None = None) -> Result: return await asyncio.to_thread(self._call, operation, payload, options) def _call(self, operation, payload, options): headers = {"Content-Type": "application/json", "X-API-KEY": self.api_key} if self.bearer: headers["Authorization"] = "Bearer " + self.bearer body = {"operation": operation, "payload": payload} if options is not None: body["options"] = options request = Request(self.api_url, data=json.dumps(body).encode(), headers=headers, method="POST") try: response = urlopen(request, timeout=30) except HTTPError as exc: response = exc with response: result = json.load(response) if response.status >= 400 and not result.get("error"): raise RuntimeError(f"HTTP {response.status} without an API error envelope") return Result(result.get("data"), result.get("error"), result.get("meta") or {}, result.get("exec_time")) ``` ## Example Set `SINGLEBASE_API_URL` to the complete console endpoint and `SINGLEBASE_API_KEY` to your server or appropriately scoped agent key. The `notes` collection must exist. ```python import asyncio import os from singlebase import singlebaseClient, Result async def main(): sbc = singlebaseClient(api_key=os.environ["SINGLEBASE_API_KEY"], api_url=os.environ["SINGLEBASE_API_URL"]) resp: Result = await sbc.call(operation="data.query", payload={"collection": "notes", "limit": 5}, options={}) if resp.error: raise RuntimeError(resp.error["message"]) print(resp.data, resp.meta, resp.exec_time) asyncio.run(main()) ``` Use the same method with `llm.summarize` for generation or `chat.ask` for an answer, with the operation's verified payload. The `options` argument goes in the request envelope, separate from `payload`. An empty options object is valid; omit it when unused. See [API overview](/api.md) for request access and errors, and [API reference](/api-reference.md) for the operation groups. --- Canonical page: https://docs.singlebase.io/sdk-go # Go SDK A small client you can copy into your backend. This is a documented implementation, not a separately published package. It sends the same API envelope for every service through one `call` method. Go 1.18+; standard library only. Put the client in a `singlebase` subdirectory of your Go module. Replace `example.com/app` in the example with your module path. ## Response contract | Field | Meaning | |---|---| | `data` | Operation result; absent on API errors | | `error` | API error object, or null/nil on success; `message` is the stable code | | `meta` | Response metadata, including pagination when returned | | `exec_time` | Gateway execution time in seconds, when returned | API errors return in `Result.error`. Network, invalid JSON, and transport failures raise an exception or return a Go error. These small clients do not manage sessions, auto-refresh tokens, or retry requests. Pass a current user bearer token to the constructor/client only when acting as that user; omit it for trusted server/agent calls. Keep keys on the server. ## Client implementation Save as `singlebase.go`. [Download the source](/examples/singlebase.go). ```go package singlebase import ( "bytes" "context" "encoding/json" "fmt" "net/http" "time" ) type Result struct { Data json.RawMessage `json:"data"` Error map[string]any `json:"error"` Meta map[string]any `json:"meta"` ExecTime *float64 `json:"exec_time"` } type Client struct { APIURL string APIKey string Bearer string } func (s Client) Call(ctx context.Context, operation string, payload map[string]any, options map[string]any) (Result, error) { body := map[string]any{"operation": operation, "payload": payload} if options != nil { body["options"] = options } raw, err := json.Marshal(body) if err != nil { return Result{}, err } req, err := http.NewRequestWithContext(ctx, "POST", s.APIURL, bytes.NewReader(raw)) if err != nil { return Result{}, err } req.Header.Set("Content-Type", "application/json") req.Header.Set("X-API-KEY", s.APIKey) if s.Bearer != "" { req.Header.Set("Authorization", "Bearer "+s.Bearer) } httpClient := &http.Client{Timeout: 30 * time.Second} res, err := httpClient.Do(req) if err != nil { return Result{}, err } defer res.Body.Close() var result Result if err := json.NewDecoder(res.Body).Decode(&result); err != nil { return Result{}, err } if res.StatusCode >= 400 && result.Error == nil { return result, fmt.Errorf("HTTP %d without an API error envelope", res.StatusCode) } return result, nil } ``` ## Example Set `SINGLEBASE_API_URL` to the complete console endpoint and `SINGLEBASE_API_KEY` to your server or appropriately scoped agent key. The `notes` collection must exist. ```go package main import ( "context" "fmt" "os" "example.com/app/singlebase" ) func main() { sbc := singlebase.Client{APIURL: os.Getenv("SINGLEBASE_API_URL"), APIKey: os.Getenv("SINGLEBASE_API_KEY")} resp, err := sbc.Call(context.Background(), "data.query", map[string]any{"collection": "notes", "limit": 5}, map[string]any{}) if err != nil { panic(err) } if resp.Error != nil { panic(resp.Error["message"]) } fmt.Println(string(resp.Data), resp.Meta, resp.ExecTime) } ``` Use the same method with `llm.summarize` for generation or `chat.ask` for an answer, with the operation's verified payload. The `options` argument goes in the request envelope, separate from `payload`. An empty options object is valid; omit it when unused. See [API overview](/api.md) for request access and errors, and [API reference](/api-reference.md) for the operation groups. --- Canonical page: https://docs.singlebase.io/sdk-php # PHP SDK A small client you can copy into your backend. This is a documented implementation, not a separately published package. It sends the same API envelope for every service through one `call` method. PHP 8.0+ with HTTPS stream wrappers enabled (`allow_url_fopen`). No third-party package is required. ## Response contract | Field | Meaning | |---|---| | `data` | Operation result; absent on API errors | | `error` | API error object, or null/nil on success; `message` is the stable code | | `meta` | Response metadata, including pagination when returned | | `exec_time` | Gateway execution time in seconds, when returned | API errors return in `Result.error`. Network, invalid JSON, and transport failures raise an exception or return a Go error. These small clients do not manage sessions, auto-refresh tokens, or retry requests. Pass a current user bearer token to the constructor/client only when acting as that user; omit it for trusted server/agent calls. Keep keys on the server. ## Client implementation Save as `singlebase.php`. [Download the source](/examples/singlebase.php). ```php data = $body['data'] ?? null; $this->error = $body['error'] ?? null; $this->meta = $body['meta'] ?? []; $this->exec_time = isset($body['exec_time']) ? (float)$body['exec_time'] : null; } } class SinglebaseClient { public function __construct(private string $api_key, private string $api_url, private ?string $bearer = null) {} public function call(string $operation, array $payload, ?array $options = null): Result { $headers = ['Content-Type: application/json', 'X-API-KEY: ' . $this->api_key]; if ($this->bearer !== null) $headers[] = 'Authorization: Bearer ' . $this->bearer; $body = ['operation' => $operation, 'payload' => (object)$payload]; if ($options !== null) $body['options'] = (object)$options; $context = stream_context_create(['http' => [ 'method' => 'POST', 'header' => implode("\r\n", $headers), 'content' => json_encode($body, JSON_THROW_ON_ERROR), 'timeout' => 30, 'ignore_errors' => true, 'follow_location' => 0 ]]); $raw = file_get_contents($this->api_url, false, $context); if ($raw === false) throw new RuntimeException('HTTP transport failed'); $decoded = json_decode($raw, true, 512, JSON_THROW_ON_ERROR); if (!is_array($decoded)) throw new RuntimeException('Expected a JSON API envelope'); $status = 0; foreach ($http_response_header ?? [] as $line) { if (preg_match('/^HTTP\/\S+\s+(\d{3})/', $line, $m)) $status = (int)$m[1]; } if ($status >= 400 && !isset($decoded['error'])) throw new RuntimeException('HTTP ' . $status . ' without an API error envelope'); return new Result($decoded); } } ``` ## Example Set `SINGLEBASE_API_URL` to the complete console endpoint and `SINGLEBASE_API_KEY` to your server or appropriately scoped agent key. The `notes` collection must exist. ```php call('data.query', ['collection' => 'notes', 'limit' => 5], []); if ($resp->error !== null) throw new RuntimeException($resp->error['message']); var_dump($resp->data, $resp->meta, $resp->exec_time); ``` Use the same method with `llm.summarize` for generation or `chat.ask` for an answer, with the operation's verified payload. The `options` argument goes in the request envelope, separate from `payload`. An empty options object is valid; omit it when unused. See [API overview](/api.md) for request access and errors, and [API reference](/api-reference.md) for the operation groups. --- Canonical page: https://docs.singlebase.io/sdk-ruby # Ruby SDK A small client you can copy into your backend. This is a documented implementation, not a separately published package. It sends the same API envelope for every service through one `call` method. Ruby 2.5+; standard library only. ## Response contract | Field | Meaning | |---|---| | `data` | Operation result; absent on API errors | | `error` | API error object, or null/nil on success; `message` is the stable code | | `meta` | Response metadata, including pagination when returned | | `exec_time` | Gateway execution time in seconds, when returned | API errors return in `Result.error`. Network, invalid JSON, and transport failures raise an exception or return a Go error. These small clients do not manage sessions, auto-refresh tokens, or retry requests. Pass a current user bearer token to the constructor/client only when acting as that user; omit it for trusted server/agent calls. Keep keys on the server. ## Client implementation Save as `singlebase.rb`. [Download the source](/examples/singlebase.rb). ```ruby require 'json' require 'net/http' require 'uri' Result = Struct.new(:data, :error, :meta, :exec_time, keyword_init: true) class SinglebaseClient def initialize(api_key:, api_url:, bearer: nil) @api_key, @api_url, @bearer = api_key, api_url, bearer end def call(operation:, payload:, options: nil) uri = URI(@api_url) request = Net::HTTP::Post.new(uri) request['Content-Type'] = 'application/json' request['X-API-KEY'] = @api_key request['Authorization'] = "Bearer #{@bearer}" if @bearer body = {operation: operation, payload: payload} body[:options] = options unless options.nil? request.body = JSON.generate(body) http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = uri.scheme == 'https' http.open_timeout = 30 http.read_timeout = 30 response = http.request(request) decoded = JSON.parse(response.body) unless decoded.is_a?(Hash) raise 'Expected a JSON API envelope' end if response.code.to_i >= 400 && !decoded['error'] raise "HTTP #{response.code} without an API error envelope" end Result.new(data: decoded['data'], error: decoded['error'], meta: decoded['meta'] || {}, exec_time: decoded['exec_time']) end end ``` ## Example Set `SINGLEBASE_API_URL` to the complete console endpoint and `SINGLEBASE_API_KEY` to your server or appropriately scoped agent key. The `notes` collection must exist. ```ruby require_relative 'singlebase' sbc = SinglebaseClient.new(api_key: ENV.fetch('SINGLEBASE_API_KEY'), api_url: ENV.fetch('SINGLEBASE_API_URL')) resp = sbc.call(operation: 'data.query', payload: {collection: 'notes', limit: 5}, options: {}) raise resp.error['message'] if resp.error puts resp.data.inspect puts resp.meta.inspect puts resp.exec_time ``` Use the same method with `llm.summarize` for generation or `chat.ask` for an answer, with the operation's verified payload. The `options` argument goes in the request envelope, separate from `payload`. An empty options object is valid; omit it when unused. See [API overview](/api.md) for request access and errors, and [API reference](/api-reference.md) for the operation groups.