EliteBotVault API

A lightweight REST API for storing and retrieving per-installation bot settings, keyed by phone number and bot ID. Built with Express and MongoDB.

Overview

EliteBotVault lets bots persist configuration data against a unique (number, botId) pair. Each pair is called an installation and is created automatically the first time settings are written.

GET — read PUT — full replace PATCH — partial merge DELETE — remove

Base URL

https://your-domain.com

The Base URL is your current site origin. All paths below are relative to it.

Core Concepts

Installation

A single record identified by number + botId. It holds:

FieldTypeDescription
numberstringDigits-only phone number (non-digits are stripped).
botIdstringLowercase identifier, 2–32 chars, a-z 0-9 - _.
settingsobjectFree-form JSON object. Defaults to {}.
versionnumberIncremented on every write. Used for ETag.
schemaVersionnumberInternal schema marker (currently 1).
createdAtISO dateAuto-managed timestamp.
updatedAtISO dateAuto-managed timestamp.
Auto-creation: A missing installation is created on PUT and PATCH. On GET and DELETE, a missing installation returns 404.

Response Format

Every response is JSON with a top-level success boolean.

Success

{
  "success": true,
  "number": "1234567890",
  "botId": "mybot",
  "settings": { "theme": "dark" },
  "version": 3,
  "schemaVersion": 1,
  "updatedAt": "2025-01-01T12:00:00.000Z"
}

Error

{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Installation not found"
  }
}

Endpoints

GET /status

Health check. Reports service status, DB connection state, and uptime.

Response

{
  "ok": true,
  "service": "EliteBotVault",
  "db": true,
  "uptime": 123.45,
  "timestamp": "2025-01-01T12:00:00.000Z"
}
GET /api/botsettings/:number/:botId

Fetch the settings for an installation. Returns 404 if it doesn't exist.

Path Parameters

NameRequiredDescription
number required Phone number. Non-digit characters are stripped automatically.
botId required Bot identifier. Lowercased automatically.

Response

{
  "success": true,
  "number": "1234567890",
  "botId": "mybot",
  "settings": { "theme": "dark" },
  "version": 3,
  "schemaVersion": 1,
  "updatedAt": "2025-01-01T12:00:00.000Z"
}
Sends an ETag header (W/"v<version>"). Send it back as If-None-Match to get a cheap 304 Not Modified.
PUT /api/botsettings/:number/:botId

Full replace of the settings object. Creates the installation if missing.

Request Body

FieldTypeRequiredDescription
settings object required Plain JSON object. Arrays and primitives are rejected.
{
  "settings": {
    "theme": "dark",
    "notifications": true,
    "language": "en"
  }
}

Response

{
  "success": true,
  "number": "1234567890",
  "botId": "mybot",
  "version": 4,
  "updatedAt": "2025-01-01T12:05:00.000Z"
}
PATCH /api/botsettings/:number/:botId

Partial merge into existing settings. Top-level keys only — keys containing . are rejected. Set a key to null to remove it. Creates the installation if missing.

Request Body

{
  "settings": {
    "theme": "light",
    "oldKey": null
  }
}

The above sets settings.theme = "light" and unsets settings.oldKey, leaving all other keys untouched.

Flat keys only. Nested paths like "ui.theme" are rejected with bad_key. Send the full nested object under a single key instead.
DELETE /api/installations/:number/:botId

Permanently delete an installation and all its settings.

Response

{
  "success": true,
  "deleted": true
}

Error Codes

HTTPCodeMeaning
400missing_numberNo number supplied.
400missing_bot_idNo botId supplied.
400invalid_bot_idbotId fails the regex rule.
400bad_requestsettings is not a plain object.
400bad_keyA PATCH key contains a ..
404not_foundInstallation doesn't exist (GET / DELETE).
404not_foundUnknown route.
500db_unavailableMongoDB connection failed.
500internal_errorUnhandled server error.

Validation Rules

number

botId

ETag Caching

GET /api/botsettings/:number/:botId returns a weak ETag based on the current version:

ETag: W/"v3"

Resend it to skip the body transfer when nothing has changed:

GET https://your-domain.com/api/botsettings/1234567890/mybot
If-None-Match: W/"v3"

If the version still matches, the server replies:

HTTP/1.1 304 Not Modified

Every successful write increments version, invalidating old ETags.

Examples

Create or fully replace settings

curl -X PUT https://your-domain.com/api/botsettings/1234567890/mybot \
  -H "Content-Type: application/json" \
  -d '{"settings":{"theme":"dark","language":"en"}}'

Read settings with caching

curl https://your-domain.com/api/botsettings/1234567890/mybot \
  -H 'If-None-Match: W/"v3"'

Update one key, remove another

curl -X PATCH https://your-domain.com/api/botsettings/1234567890/mybot \
  -H "Content-Type: application/json" \
  -d '{"settings":{"theme":"light","language":null}}'

Delete an installation

curl -X DELETE https://your-domain.com/api/installations/1234567890/mybot

JavaScript (fetch)

const BASE = "https://your-domain.com";

await fetch(`${BASE}/api/botsettings/1234567890/mybot`, {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ settings: { theme: "dark" } })
});

const res  = await fetch(`${BASE}/api/botsettings/1234567890/mybot`);
const data = await res.json();
console.log(data.settings);