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, 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:

export SINGLEBASE_API_URL='https://v1.api.singlebase.io/api/<ENDPOINT_KEY>'
export SINGLEBASE_SERVER_KEY='sk_<SERVER_KEY>'

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.

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

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.

4. Read it back

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:

{
  "operation": "data.query",
  "payload": {
    "collection": "notes",
    "filter": { "_id": "<RETURNED_DOCUMENT_ID>" },
    "limit": 1
  }
}

JavaScript SDK example

Install the existing JavaScript SDK:

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.

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.

Python example

Copy the small client from Python SDK into singlebase.py. It uses the standard library and returns the full Result envelope.

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.

Connect a signed-in user

Browser and mobile clients use a web key (wk_) plus Authorization: Bearer <ID_TOKEN> for user-scoped operations. A signed-in insert automatically belongs to that user; reads and mutations are scoped to their documents. See Authentication for signup and signin, and API overview for headers and errors.