--- title: Documents description: API reference for managing documents in Mavibase readTime: 12 relatedTo: - collections - querying - versions --- # 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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/v1/db/databases/:databaseId/collections/:collectionId/documents/:documentId ``` ### Example Request ```bash curl -X DELETE "/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/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/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/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/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/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/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/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](/docs/api/versions) 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" } } ```