Documents
API reference for managing documents in Mavibase
12 mins
Documents API
Documents are the individual records stored within collections. Mavibase provides full CRUD operations plus bulk operations for efficiency.
Authentication
All document endpoints require an API key with appropriate scopes:
| Scope | Required For |
|---|---|
databases:read | GET requests |
databases:write | POST, PUT, PATCH requests |
databases:delete | DELETE requests |
Create Document
Creates a new document in a collection.
Endpoint
POST <API_ENDPOINT>/api/v1/db/databases/:databaseId/collections/:collectionId/documents
Path Parameters
| Parameter | Description |
|---|---|
databaseId | Parent database identifier |
collectionId | Parent collection identifier |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
data | object | Yes | Document data |
permissions | object | No | Document-level permissions |
Example Request
bash
curl -X POST "<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents" \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"data": {
"name": "John Doe",
"email": "john@example.com",
"age": 28,
"role": "user"
}
}'JavaScript Example
javascript
const response = await fetch(
'<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'your_api_key',
},
body: JSON.stringify({
data: {
name: 'John Doe',
email: 'john@example.com',
age: 28,
},
}),
}
);
const { document } = await response.json();Node.js Example
javascript
const axios = require('axios');
async function createDocument(databaseId, collectionId, data) {
const response = await axios.post(
`<API_ENDPOINT>/api/v1/db/databases/${databaseId}/collections/${collectionId}/documents`,
{ data },
{
headers: {
'Content-Type': 'application/json',
'X-API-Key': process.env.MAVIBASE_API_KEY,
},
}
);
return response.data;
}
const result = await createDocument('db_abc123', 'col_users', {
name: 'John Doe',
email: 'john@example.com',
});Response
json
{
"success": true,
"document": {
"id": "doc_def456",
"data": {
"name": "John Doe",
"email": "john@example.com",
"age": 28,
"role": "user"
},
"version": 1,
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z"
}
}List Documents
Returns documents from a collection with optional filtering.
Endpoint
GET <API_ENDPOINT>/api/v1/db/databases/:databaseId/collections/:collectionId/documents
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 25 | Maximum results to return (max 100) |
offset | integer | 0 | Number of results to skip |
orderBy | string | createdAt | Field to sort by |
order | string | desc | Sort direction (asc or desc) |
Example Request
bash
curl -X GET "<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents?limit=10&orderBy=name&order=asc" \
-H "X-API-Key: your_api_key"JavaScript Example
javascript
const params = new URLSearchParams({
limit: '10',
orderBy: 'name',
order: 'asc',
});
const response = await fetch(
`<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents?${params}`,
{
headers: {
'X-API-Key': 'your_api_key',
},
}
);
const { documents, total } = await response.json();Response
json
{
"success": true,
"documents": [
{
"id": "doc_def456",
"data": {
"name": "Alice Smith",
"email": "alice@example.com",
"age": 32
},
"version": 1,
"createdAt": "2024-01-15T10:30:00.000Z"
},
{
"id": "doc_ghi789",
"data": {
"name": "Bob Johnson",
"email": "bob@example.com",
"age": 25
},
"version": 1,
"createdAt": "2024-01-15T11:00:00.000Z"
}
],
"total": 150,
"limit": 10,
"offset": 0
}Get Document
Retrieves a single document by ID.
Endpoint
GET <API_ENDPOINT>/api/v1/db/databases/:databaseId/collections/:collectionId/documents/:documentId
Path Parameters
| Parameter | Description |
|---|---|
databaseId | Database identifier |
collectionId | Collection identifier |
documentId | Document identifier |
Example Request
bash
curl -X GET "<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents/doc_def456" \
-H "X-API-Key: your_api_key"Response
json
{
"success": true,
"document": {
"id": "doc_def456",
"data": {
"name": "John Doe",
"email": "john@example.com",
"age": 28,
"role": "user"
},
"version": 1,
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z"
}
}Update Document (Full Replace)
Replaces an entire document with new data.
Endpoint
PUT <API_ENDPOINT>/api/v1/db/databases/:databaseId/collections/:collectionId/documents/:documentId
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
data | object | Yes | Complete new document data |
Example Request
bash
curl -X PUT "<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents/doc_def456" \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"data": {
"name": "John Doe",
"email": "johndoe@example.com",
"age": 29,
"role": "admin"
}
}'Response
json
{
"success": true,
"document": {
"id": "doc_def456",
"data": {
"name": "John Doe",
"email": "johndoe@example.com",
"age": 29,
"role": "admin"
},
"version": 2,
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T14:00:00.000Z"
}
}Update Document (Partial)
Updates specific fields in a document without affecting others.
Endpoint
PATCH <API_ENDPOINT>/api/v1/db/databases/:databaseId/collections/:collectionId/documents/:documentId
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
data | object | Yes | Fields to update |
Example Request
bash
curl -X PATCH "<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents/doc_def456" \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"data": {
"age": 30
}
}'JavaScript Example
javascript
const response = await fetch(
'<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents/doc_def456',
{
method: 'PATCH',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'your_api_key',
},
body: JSON.stringify({
data: { age: 30 },
}),
}
);
const { document } = await response.json();Response
json
{
"success": true,
"document": {
"id": "doc_def456",
"data": {
"name": "John Doe",
"email": "johndoe@example.com",
"age": 30,
"role": "admin"
},
"version": 3,
"updatedAt": "2024-01-15T15:00:00.000Z"
}
}Delete Document
Permanently deletes a document.
Endpoint
DELETE <API_ENDPOINT>/api/v1/db/databases/:databaseId/collections/:collectionId/documents/:documentId
Example Request
bash
curl -X DELETE "<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents/doc_def456" \
-H "X-API-Key: your_api_key"Response
json
{
"success": true,
"message": "Document deleted successfully"
}Bulk Create Documents
Creates multiple documents in a single request.
Endpoint
POST <API_ENDPOINT>/api/v1/db/databases/:databaseId/collections/:collectionId/documents/bulk
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
documents | array | Yes | Array of document objects |
Example Request
bash
curl -X POST "<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents/bulk" \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"documents": [
{ "data": { "name": "Alice", "email": "alice@example.com" } },
{ "data": { "name": "Bob", "email": "bob@example.com" } },
{ "data": { "name": "Charlie", "email": "charlie@example.com" } }
]
}'JavaScript Example
javascript
const response = await fetch(
'<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents/bulk',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'your_api_key',
},
body: JSON.stringify({
documents: [
{ data: { name: 'Alice', email: 'alice@example.com' } },
{ data: { name: 'Bob', email: 'bob@example.com' } },
{ data: { name: 'Charlie', email: 'charlie@example.com' } },
],
}),
}
);
const { documents, created } = await response.json();Response
json
{
"success": true,
"documents": [
{ "id": "doc_001", "data": { "name": "Alice", "email": "alice@example.com" } },
{ "id": "doc_002", "data": { "name": "Bob", "email": "bob@example.com" } },
{ "id": "doc_003", "data": { "name": "Charlie", "email": "charlie@example.com" } }
],
"created": 3
}Bulk Update Documents
Updates multiple documents in a single request.
Endpoint
PATCH <API_ENDPOINT>/api/v1/db/databases/:databaseId/collections/:collectionId/documents/bulk
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
documents | array | Yes | Array of { id, data } objects |
Example Request
bash
curl -X PATCH "<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents/bulk" \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"documents": [
{ "id": "doc_001", "data": { "role": "admin" } },
{ "id": "doc_002", "data": { "role": "moderator" } }
]
}'Response
json
{
"success": true,
"updated": 2
}Bulk Delete Documents
Deletes multiple documents in a single request.
Endpoint
DELETE <API_ENDPOINT>/api/v1/db/databases/:databaseId/collections/:collectionId/documents/bulk
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
ids | array | Yes | Array of document IDs to delete |
Example Request
bash
curl -X DELETE "<API_ENDPOINT>/api/v1/db/databases/db_abc123/collections/col_users/documents/bulk" \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"ids": ["doc_001", "doc_002", "doc_003"]
}'Response
json
{
"success": true,
"deleted": 3
}Document Versioning
Every document change creates a new version. See the Versions API for managing document history.
json
{
"id": "doc_def456",
"version": 3,
"data": { ... },
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T15:00:00.000Z"
}Error Responses
400 Bad Request - Validation Error
json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Document validation failed",
"details": {
"email": "Invalid email format"
}
}
}404 Not Found
json
{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "Document not found"
}
}409 Conflict - Unique Constraint
json
{
"success": false,
"error": {
"code": "UNIQUE_CONSTRAINT",
"message": "A document with this email already exists",
"field": "email"
}
}