Databases

API reference for managing databases in Mavibase

8 mins

Databases API

Databases are the top-level containers for your data in Mavibase. Each database can contain multiple collections.

Authentication

All database endpoints require an API key with appropriate scopes:

Scope	Required For
`databases:read`	GET requests
`databases:write`	POST, PATCH requests
`databases:delete`	DELETE requests

Include your API key in the request header:

bash

X-API-Key: your_api_key

Create Database

Creates a new database.

Endpoint

POST <API_ENDPOINT>/api/v1/db/databases

Request Body

Field	Type	Required	Description
`name`	string	Yes	Database name (alphanumeric, hyphens allowed)

Example Request

bash

curl -X POST "<API_ENDPOINT>/api/v1/db/databases" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "name": "my-application"
  }'

JavaScript Example

javascript

const response = await fetch('<API_ENDPOINT>/api/v1/db/databases', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key',
  },
  body: JSON.stringify({
    name: 'my-application',
  }),
});

const database = await response.json();

Response

json

{
  "success": true,
  "database": {
    "id": "db_abc123xyz",
    "name": "my-application",
    "projectId": "prj_abc123",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

List Databases

Returns all databases for the current project.

Endpoint

GET <API_ENDPOINT>/api/v1/db/databases

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	25	Maximum results to return
`offset`	integer	0	Number of results to skip

Example Request

bash

curl -X GET "<API_ENDPOINT>/api/v1/db/databases?limit=10" \
  -H "X-API-Key: your_api_key"

JavaScript Example

javascript

const response = await fetch('<API_ENDPOINT>/api/v1/db/databases?limit=10', {
  headers: {
    'X-API-Key': 'your_api_key',
  },
});

const { databases, total } = await response.json();

Response

json

{
  "success": true,
  "databases": [
    {
      "id": "db_abc123xyz",
      "name": "my-application",
      "projectId": "prj_abc123",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

Get Database

Retrieves a single database by ID.

Endpoint

GET <API_ENDPOINT>/api/v1/db/databases/:databaseId

Path Parameters

Parameter	Description
`databaseId`	Unique database identifier

Example Request

bash

curl -X GET "<API_ENDPOINT>/api/v1/db/databases/db_abc123xyz" \
  -H "X-API-Key: your_api_key"

JavaScript Example

javascript

const response = await fetch('<API_ENDPOINT>/api/v1/db/databases/db_abc123xyz', {
  headers: {
    'X-API-Key': 'your_api_key',
  },
});

const { database } = await response.json();

Response

json

{
  "success": true,
  "database": {
    "id": "db_abc123xyz",
    "name": "my-application",
    "projectId": "prj_abc123",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

Get Database Stats

Retrieves statistics for a database including size and document counts.

Endpoint

GET <API_ENDPOINT>/api/v1/db/databases/:databaseId/stats

Path Parameters

Parameter	Description
`databaseId`	Unique database identifier

Example Request

bash

curl -X GET "<API_ENDPOINT>/api/v1/db/databases/db_abc123xyz/stats" \
  -H "X-API-Key: your_api_key"

Response

json

{
  "success": true,
  "stats": {
    "databaseId": "db_abc123xyz",
    "totalCollections": 5,
    "totalDocuments": 1250,
    "totalSize": 2457600,
    "collectionsStats": [
      {
        "collectionId": "col_users",
        "name": "users",
        "documentCount": 500,
        "size": 1024000
      }
    ]
  }
}

Get Database Schema

Retrieves the complete schema for all collections in a database.

Endpoint

GET <API_ENDPOINT>/api/v1/db/databases/:databaseId/schema

Path Parameters

Parameter	Description
`databaseId`	Unique database identifier

Example Request

bash

curl -X GET "<API_ENDPOINT>/api/v1/db/databases/db_abc123xyz/schema" \
  -H "X-API-Key: your_api_key"

Response

json

{
  "success": true,
  "schema": {
    "databaseId": "db_abc123xyz",
    "collections": [
      {
        "id": "col_users",
        "name": "users",
        "schema": {
          "name": { "type": "string", "required": true },
          "email": { "type": "email", "required": true, "unique": true }
        }
      }
    ]
  }
}

Export Database

Exports the complete database structure and optionally data.

Endpoint

GET <API_ENDPOINT>/api/v1/db/databases/:databaseId/export

Path Parameters

Parameter	Description
`databaseId`	Unique database identifier

Example Request

bash

curl -X GET "<API_ENDPOINT>/api/v1/db/databases/db_abc123xyz/export" \
  -H "X-API-Key: your_api_key"

Response

json

{
  "success": true,
  "export": {
    "database": {
      "id": "db_abc123xyz",
      "name": "my-application"
    },
    "collections": [...],
    "exportedAt": "2024-01-15T10:30:00.000Z"
  }
}

Update Database

Updates a database's properties.

Endpoint

PATCH <API_ENDPOINT>/api/v1/db/databases/:databaseId

Path Parameters

Parameter	Description
`databaseId`	Unique database identifier

Request Body

Field	Type	Required	Description
`name`	string	No	New database name

Example Request

bash

curl -X PATCH "<API_ENDPOINT>/api/v1/db/databases/db_abc123xyz" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "name": "my-renamed-database"
  }'

JavaScript Example

javascript

const response = await fetch(
  '<API_ENDPOINT>/api/v1/db/databases/db_abc123xyz',
  {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'your_api_key',
    },
    body: JSON.stringify({
      name: 'my-renamed-database',
    }),
  }
);

const { database } = await response.json();

Response

json

{
  "success": true,
  "database": {
    "id": "db_abc123xyz",
    "name": "my-renamed-database",
    "projectId": "prj_abc123",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T12:00:00.000Z"
  }
}

Delete Database

Permanently deletes a database and all its collections and documents.

Endpoint

DELETE <API_ENDPOINT>/api/v1/db/databases/:databaseId

Path Parameters

Parameter	Description
`databaseId`	Unique database identifier

Example Request

bash

curl -X DELETE "<API_ENDPOINT>/api/v1/db/databases/db_abc123xyz" \
  -H "X-API-Key: your_api_key"

JavaScript Example

javascript

const response = await fetch(
  '<API_ENDPOINT>/api/v1/db/databases/db_abc123xyz',
  {
    method: 'DELETE',
    headers: {
      'X-API-Key': 'your_api_key',
    },
  }
);

const result = await response.json();

Response

json

{
  "success": true,
  "message": "Database deleted successfully"
}

Warning: This action is irreversible. All collections and documents in the database will be permanently deleted.

Error Responses

400 Bad Request

json

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Database name is required"
  }
}

401 Unauthorized

json

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden

json

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have required scope: databases:write"
  }
}

404 Not Found

json

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Database not found"
  }
}

409 Conflict

json

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Database with this name already exists"
  }
}

PreviousCollections Next Documents

Edit on GitHub View raw

Databases

API reference for managing databases in Mavibase

8 mins

Databases API

Databases are the top-level containers for your data in Mavibase. Each database can contain multiple collections.

Authentication

All database endpoints require an API key with appropriate scopes:

Scope	Required For
`databases:read`	GET requests
`databases:write`	POST, PATCH requests
`databases:delete`	DELETE requests

Include your API key in the request header:

bash

X-API-Key: your_api_key

Create Database

Creates a new database.

Endpoint

POST <API_ENDPOINT>/api/v1/db/databases

Request Body

Field	Type	Required	Description
`name`	string	Yes	Database name (alphanumeric, hyphens allowed)

Example Request

bash

curl -X POST "<API_ENDPOINT>/api/v1/db/databases" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "name": "my-application"
  }'

JavaScript Example

javascript

const response = await fetch('<API_ENDPOINT>/api/v1/db/databases', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key',
  },
  body: JSON.stringify({
    name: 'my-application',
  }),
});

const database = await response.json();

Response

json

{
  "success": true,
  "database": {
    "id": "db_abc123xyz",
    "name": "my-application",
    "projectId": "prj_abc123",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

List Databases

Returns all databases for the current project.

Endpoint

GET <API_ENDPOINT>/api/v1/db/databases

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	25	Maximum results to return
`offset`	integer	0	Number of results to skip

Example Request

bash

curl -X GET "<API_ENDPOINT>/api/v1/db/databases?limit=10" \
  -H "X-API-Key: your_api_key"

JavaScript Example

javascript

const response = await fetch('<API_ENDPOINT>/api/v1/db/databases?limit=10', {
  headers: {
    'X-API-Key': 'your_api_key',
  },
});

const { databases, total } = await response.json();

Response

json

{
  "success": true,
  "databases": [
    {
      "id": "db_abc123xyz",
      "name": "my-application",
      "projectId": "prj_abc123",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

Get Database

Retrieves a single database by ID.

Endpoint

GET <API_ENDPOINT>/api/v1/db/databases/:databaseId

Path Parameters

Parameter	Description
`databaseId`	Unique database identifier

Example Request

bash

curl -X GET "<API_ENDPOINT>/api/v1/db/databases/db_abc123xyz" \
  -H "X-API-Key: your_api_key"

JavaScript Example

javascript

const response = await fetch('<API_ENDPOINT>/api/v1/db/databases/db_abc123xyz', {
  headers: {
    'X-API-Key': 'your_api_key',
  },
});

const { database } = await response.json();

Response

json

{
  "success": true,
  "database": {
    "id": "db_abc123xyz",
    "name": "my-application",
    "projectId": "prj_abc123",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

Get Database Stats

Retrieves statistics for a database including size and document counts.

Endpoint

GET <API_ENDPOINT>/api/v1/db/databases/:databaseId/stats

Path Parameters

Parameter	Description
`databaseId`	Unique database identifier

Example Request

bash

curl -X GET "<API_ENDPOINT>/api/v1/db/databases/db_abc123xyz/stats" \
  -H "X-API-Key: your_api_key"

Response

json

{
  "success": true,
  "stats": {
    "databaseId": "db_abc123xyz",
    "totalCollections": 5,
    "totalDocuments": 1250,
    "totalSize": 2457600,
    "collectionsStats": [
      {
        "collectionId": "col_users",
        "name": "users",
        "documentCount": 500,
        "size": 1024000
      }
    ]
  }
}

Get Database Schema

Retrieves the complete schema for all collections in a database.

Endpoint

GET <API_ENDPOINT>/api/v1/db/databases/:databaseId/schema

Path Parameters

Parameter	Description
`databaseId`	Unique database identifier

Example Request

bash

curl -X GET "<API_ENDPOINT>/api/v1/db/databases/db_abc123xyz/schema" \
  -H "X-API-Key: your_api_key"

Response

json

{
  "success": true,
  "schema": {
    "databaseId": "db_abc123xyz",
    "collections": [
      {
        "id": "col_users",
        "name": "users",
        "schema": {
          "name": { "type": "string", "required": true },
          "email": { "type": "email", "required": true, "unique": true }
        }
      }
    ]
  }
}

Export Database

Exports the complete database structure and optionally data.

Endpoint

GET <API_ENDPOINT>/api/v1/db/databases/:databaseId/export

Path Parameters

Parameter	Description
`databaseId`	Unique database identifier

Example Request

bash

curl -X GET "<API_ENDPOINT>/api/v1/db/databases/db_abc123xyz/export" \
  -H "X-API-Key: your_api_key"

Response

json

{
  "success": true,
  "export": {
    "database": {
      "id": "db_abc123xyz",
      "name": "my-application"
    },
    "collections": [...],
    "exportedAt": "2024-01-15T10:30:00.000Z"
  }
}

Update Database

Updates a database's properties.

Endpoint

PATCH <API_ENDPOINT>/api/v1/db/databases/:databaseId

Path Parameters

Parameter	Description
`databaseId`	Unique database identifier

Request Body

Field	Type	Required	Description
`name`	string	No	New database name

Example Request

bash

curl -X PATCH "<API_ENDPOINT>/api/v1/db/databases/db_abc123xyz" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "name": "my-renamed-database"
  }'

JavaScript Example

javascript

const response = await fetch(
  '<API_ENDPOINT>/api/v1/db/databases/db_abc123xyz',
  {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'your_api_key',
    },
    body: JSON.stringify({
      name: 'my-renamed-database',
    }),
  }
);

const { database } = await response.json();

Response

json

{
  "success": true,
  "database": {
    "id": "db_abc123xyz",
    "name": "my-renamed-database",
    "projectId": "prj_abc123",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T12:00:00.000Z"
  }
}

Delete Database

Permanently deletes a database and all its collections and documents.

Endpoint

DELETE <API_ENDPOINT>/api/v1/db/databases/:databaseId

Path Parameters

Parameter	Description
`databaseId`	Unique database identifier

Example Request

bash

curl -X DELETE "<API_ENDPOINT>/api/v1/db/databases/db_abc123xyz" \
  -H "X-API-Key: your_api_key"

JavaScript Example

javascript

const response = await fetch(
  '<API_ENDPOINT>/api/v1/db/databases/db_abc123xyz',
  {
    method: 'DELETE',
    headers: {
      'X-API-Key': 'your_api_key',
    },
  }
);

const result = await response.json();

Response

json

{
  "success": true,
  "message": "Database deleted successfully"
}

Warning: This action is irreversible. All collections and documents in the database will be permanently deleted.

Error Responses

400 Bad Request

json

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Database name is required"
  }
}

401 Unauthorized

json

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden

json

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have required scope: databases:write"
  }
}

404 Not Found

json

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Database not found"
  }
}

409 Conflict

json

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Database with this name already exists"
  }
}

PreviousCollections Next Documents

Edit on GitHub View raw