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.