---
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_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](/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"
  }
}
```
