Database

The database API exposes your project's tables and records. You can read the table structure, query with filtering/sorting/pagination/aggregation and nested relations up to 6 levels deep, and create or edit records. All endpoints require the api-key header and are free.

#Get Database Tables Structure

Retrieve all database table definitions including field names, types, and configuration.

Path parameters

Response fields

Example request

curl -H "api-key: tlm_sk_your_key" \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/database/tables-structure

{
  "errors": null,
  "data": {
    "tables": [
      {
        "_id": "65f1a2b3c4d5e6f7",
        "type": "customers",
        "label": "Customers",
        "description": "Customer records",
        "icon": "fa-solid fa-users",
        "properties": {
          "name": {
            "id": "prop_abc123",
            "name": "name",
            "propertyType": "string",
            "label": "Full Name"
          },
          "email": {
            "id": "prop_def456",
            "name": "email",
            "propertyType": "string",
            "label": "Email",
            "typeExtras": { "string": { "type": "link" } }
          }
        }
      }
    ]
  }
}

{
  "errors": {
    "errorCode": "PROJECT_NOT_FOUND",
    "errorMessage": "Project does not exist or you don't own it"
  },
  "data": null
}

Error codes

#Query Database

Query records from any table with advanced filtering, sorting, pagination, aggregations, and nested related data up to 6 levels deep.

Path parameters

Body parameters

Filter operators (use inside _filter)

• Exact match: { "status": "active" }
• With operator: { "fieldName": { "operator": value } }

Nested queries (related data)

Expand related tables by using the property name as a key in queryOptions.

• Shorthand: { "orders": true } — expands all related orders
• Full: { "orders": { "_filter": {...}, "_sort": {...}, "_limit": 5 } } — with options (max 300 children)
• { "orders": { "_has": true } } — only parents with at least one matching child
• { "orders": { "_has": "none" } } — only parents with zero matching children
• { "orders": { "_count": true } } — include child count per parent
• Nesting up to 6 levels deep supported

Response fields

Example request

curl -X POST \
  -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"tableName":"customers","queryOptions":{"_filter":{"status":"active","age":{"gte":18}},"_sort":{"createdAt":"desc"},"_limit":10,"orders":{"_filter":{"total":{"gt":50}},"_limit":5}}}' \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/database/query

{
  "errors": null,
  "data": {
    "results": [
      {
        "_id": "65f1a2b3c4d5e6f7a8b9c0d1",
        "name": "John Doe",
        "email": "john@example.com",
        "status": "active",
        "age": 30,
        "orders": [
          { "_id": "...", "total": 120.50, "createdAt": "2026-03-09T..." }
        ],
        "createdAt": "2026-03-10T08:00:00.000Z"
      }
    ]
  }
}

{
  "errors": {
    "errorCode": "MISSING_TABLE_NAME",
    "errorMessage": "tableName is required"
  },
  "data": null
}

More filter examples

// OR logic
"_filter": { "_or": [{ "status": "active" }, { "role": "admin" }] }
// IN operator
"_filter": { "status": { "in": ["active", "pending"] } }
// Regex case-insensitive
"_filter": { "email": { "regex": "@gmail", "options": "i" } }
// Aggregation with groupBy
"_aggregate": { "_sum": { "total": true }, "_count": true }, "_groupBy": "status"
// Nested: only parents with children matching filter
"orders": { "_has": true, "_filter": { "total": { "gt": 100 } } }

Error codes

#Create Database Record

Create a new record in any table. The _id field is auto-generated by the database — do not include it in the request body. The response returns the full created record including the generated _id and any default fields.

Path parameters

Body parameters

Response fields

Example request

curl -X POST \
  -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"tableName":"customers","data":{"name":"John Doe","email":"john@example.com","status":"active","age":30}}' \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/database/records

{
  "errors": null,
  "data": {
    "_id": "65f1a2b3c4d5e6f7a8b9c0d1",
    "name": "John Doe",
    "email": "john@example.com",
    "status": "active",
    "age": 30,
    "createdAt": "2026-03-25T10:00:00.000Z",
    "updatedAt": "2026-03-25T10:00:00.000Z"
  }
}

{
  "errors": {
    "errorCode": "MISSING_DATA",
    "errorMessage": "data is required and must be an object"
  },
  "data": null
}

Error codes

#Edit Database Record

Update specific fields of an existing record by its ID. Only the fields included in data will be modified — all other fields remain unchanged. The response returns the full updated record.

Path parameters

Body parameters

Response fields

Example request

curl -X PATCH \
  -H "api-key: tlm_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"tableName":"customers","data":{"email":"newemail@example.com","age":31}}' \
  https://api-accounts.totalum.app/api/v1/vcaas/projects/my-app/database/records/65f1a2b3c4d5e6f7a8b9c0d1

{
  "errors": null,
  "data": {
    "_id": "65f1a2b3c4d5e6f7a8b9c0d1",
    "name": "John Doe",
    "email": "newemail@example.com",
    "status": "active",
    "age": 31,
    "createdAt": "2026-03-25T10:00:00.000Z",
    "updatedAt": "2026-03-25T10:05:00.000Z"
  }
}

{
  "errors": {
    "errorCode": "PROJECT_NOT_FOUND",
    "errorMessage": "Project does not exist or you don't own it"
  },
  "data": null
}

Error codes