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

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.

import { SinglebaseClient } from "@singlebase/singlebase-sdk";

const sbc = SinglebaseClient({
  baseUrl: "https://v1.api.singlebase.io/api/<ENDPOINT_KEY>",
  apiKey: "wk_<WEB_KEY>",
});
// 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 and Ownership.

Calls and results

Namespace methods map to <namespace>.<method> and accept a payload. The SDK returns the response's data, not the whole envelope.

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:

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

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

await sbc.auth.signIn({ email: "jane@example.com", password: "<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 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

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: "<DOCUMENT_ID>", title: "Updated note" },
});

Available operations: query, count, aggregate, insert, update, upsert, archive, and delete. See Data for selectors, ownership, templates, and search.

Files

const files = await sbc.files.query({ per_page: 20 });
const download = await sbc.files.get_signed_url({ id: "<FILE_ID>" });

For browser uploads, the SDK orchestrates direct-to-storage transfer and completion:

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

LLM generation and embeddings

const summary = await sbc.llm.summarize({
  content: "<DOCUMENT_TEXT>", 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 for actual payloads and model access.

Chat answers and conversations

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 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, checking payloads against the backend and namespace behavior against SDK source.

• Python client
• Go client
• PHP client
• Ruby client
• Grouped API reference