Table of Contents

API Documentation

A document-based API for storing and retrieving JSON documents in collections. BaseBean provides a simple, powerful way to store and query JSON data with built-in filtering, sorting, and pagination capabilities.

Authentication

All endpoints require an X-Api-Key header for authentication. You can find your API key in the panel when you create a datastore. Simply include your API key in every request header as shown in the examples below.

Pagination

The API supports three pagination modes to handle different use cases:

No Pagination

Default behavior

Returns all documents up to the limit (max 1000). Use when you need all data at once.

GET /users

Cursor-based

Efficient for large datasets

Use cursor parameter for efficient pagination of large datasets.

GET /users?cursor

Offset-based

Simple pagination

Use offset parameter for simple pagination (max 10,000 offset).

GET /users?offset=100&limit=50

Filtering

Use the filter parameter to query documents based on field values. All filters must be wrapped in and() or or() operations, with shorthand () meaning and().

Filter Operators

• = Equal to
• != Not equal to
• > Greater than
• < Less than
• >= Greater than or equal
• <= Less than or equal
• @ Array contains

Filter Examples

Simple AND filter (shorthand):

GET /users?filter=(age>25,status="active",tags@"important")

Explicit and() filter:

GET /users?filter=and(age>25,status="active")

or() filter:

GET /users?filter=or(status="active",status="pending")

Complex nested filter:

GET /users?filter=and(age>25,or(status="active",status="pending"),tags@"important")

Sorting

Use the sort parameter to order your results. Use desc() for descending order and asc() for ascending order.

Sort Examples

Single field sorting:

GET /users?sort=desc(created_at)

Multiple fields:

GET /users?sort=desc(created_at),asc(name)

Multiple fields in same direction:

GET /users?sort=desc(created_at,updated_at),asc(name)

Health Check

Simple health check endpoint that returns "Hello, World!" to verify the API is working.

GET /hello

Health check endpoint

1const response = await fetch('https://my-app-123.ds.basebean.com/hello', {
2  method: 'GET',
3  headers: {
4    'X-Api-Key': 'YOUR_API_KEY'
5  }
6});
7
8const data = await response.json();
9console.log(data);

Get Documents

Retrieve documents from a collection with optional filtering, sorting, and pagination.

GET /{collection}

Get documents from a collection

Query Parameters:

• cursor - Cursor for cursor-based pagination
• offset - Offset for offset-based pagination (max 10,000)
• limit - Maximum number of documents (default: 10, max: 1000)
• sort - Sort expression (e.g., "desc(created_at),asc(name)")
• filter - Filter expression (e.g., "(age>25,status="active",tags@"important")")

1const response = await fetch('https://my-app-123.ds.basebean.com/users?filter=(age>25,status="active",tags@"important")&sort=desc(created_at),asc(name)&limit=10', {
2  method: 'GET',
3  headers: {
4    'X-Api-Key': 'YOUR_API_KEY'
5  }
6});
7
8const data = await response.json();
9console.log(data);

Create Document

Create a new document in the specified collection. If no id field is provided, a UUID will be automatically generated.

POST /{collection}

Create a new document

Query Parameters:

• unique - Comma-separated list of fields that must be unique

1const response = await fetch('https://my-app-123.ds.basebean.com/users', {
2  method: 'POST',
3  headers: {
4    'X-Api-Key': 'YOUR_API_KEY',
5    'Content-Type': 'application/json'
6  },
7  body: JSON.stringify({
8  "id": "user123",
9  "name": "John Doe",
10  "email": "john@example.com",
11  "age": 30,
12  "tags": [
13    "user",
14    "active"
15  ],
16  "profile": {
17    "bio": "Software developer",
18    "location": "San Francisco"
19  }
20})
21});
22
23const data = await response.json();
24console.log(data);

Bulk Create Documents

Create multiple documents in a single request. Maximum 1000 documents allowed per batch. All documents must have an id field.

POST /{collection}/_bulk

Create multiple documents

1const response = await fetch('https://my-app-123.ds.basebean.com/users/_bulk', {
2  method: 'POST',
3  headers: {
4    'X-Api-Key': 'YOUR_API_KEY',
5    'Content-Type': 'application/json'
6  },
7  body: JSON.stringify([
8  {
9    "id": "doc1",
10    "name": "Document 1",
11    "value": 100,
12    "created": "2025-08-31T18:38:55.626Z"
13  },
14  {
15    "id": "doc2",
16    "name": "Document 2",
17    "value": 200,
18    "created": "2025-08-31T18:38:55.626Z"
19  }
20])
21});
22
23const data = await response.json();
24console.log(data);

Delete All Documents

Delete all documents from the specified collection. Use with caution!

DELETE /{collection}/_all

Delete all documents in a collection

1const response = await fetch('https://my-app-123.ds.basebean.com/users/_all', {
2  method: 'DELETE',
3  headers: {
4    'X-Api-Key': 'YOUR_API_KEY'
5  }
6});
7
8const data = await response.json();
9console.log(data);

Get Document

Retrieve a specific document by its id.

GET /{collection}/{document_id}

Get a specific document

1const response = await fetch('https://my-app-123.ds.basebean.com/users/doc123', {
2  method: 'GET',
3  headers: {
4    'X-Api-Key': 'YOUR_API_KEY'
5  }
6});
7
8const data = await response.json();
9console.log(data);

Replace Document

Completely replace a document with new content. The document id in the request body must match the path parameter. All existing fields will be replaced with the new content.

PUT /{collection}/{document_id}

Replace a document completely

1const response = await fetch('https://my-app-123.ds.basebean.com/users/doc123', {
2  method: 'PUT',
3  headers: {
4    'X-Api-Key': 'YOUR_API_KEY',
5    'Content-Type': 'application/json'
6  },
7  body: JSON.stringify({
8  "id": "doc123",
9  "name": "Updated Document",
10  "content": "This document has been completely replaced",
11  "updated_at": "2025-08-31T18:38:55.626Z",
12  "status": "active"
13})
14});
15
16const data = await response.json();
17console.log(data);

Update Document

Partially update a document by merging new fields with existing content. Only the fields provided will be updated; existing fields will be preserved.

PATCH /{collection}/{document_id}

Partially update a document

1const response = await fetch('https://my-app-123.ds.basebean.com/users/doc123', {
2  method: 'PATCH',
3  headers: {
4    'X-Api-Key': 'YOUR_API_KEY',
5    'Content-Type': 'application/json'
6  },
7  body: JSON.stringify({
8  "status": "completed",
9  "last_modified": "2025-08-31T18:38:55.626Z",
10  "tags": [
11    "updated",
12    "complete"
13  ]
14})
15});
16
17const data = await response.json();
18console.log(data);

Delete Document

Delete a specific document by its id.

DELETE /{collection}/{document_id}

Delete a specific document

1const response = await fetch('https://my-app-123.ds.basebean.com/users/doc123', {
2  method: 'DELETE',
3  headers: {
4    'X-Api-Key': 'YOUR_API_KEY'
5  }
6});
7
8const data = await response.json();
9console.log(data);