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.
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:
| Field | Type | Description |
|---|---|---|
number | string | Digits-only phone number (non-digits are stripped). |
botId | string | Lowercase identifier, 2–32 chars, a-z 0-9 - _. |
settings | object | Free-form JSON object. Defaults to {}. |
version | number | Incremented on every write. Used for ETag. |
schemaVersion | number | Internal schema marker (currently 1). |
createdAt | ISO date | Auto-managed timestamp. |
updatedAt | ISO date | Auto-managed timestamp. |
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
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"
}
Fetch the settings for an installation. Returns 404 if it doesn't exist.
Path Parameters
| Name | Required | Description |
|---|---|---|
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"
}
ETag header (W/"v<version>").
Send it back as If-None-Match to get a cheap 304 Not Modified.
Full replace of the settings object.
Creates the installation if missing.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
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"
}
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.
"ui.theme" are rejected with bad_key.
Send the full nested object under a single key instead.
Permanently delete an installation and all its settings.
Response
{
"success": true,
"deleted": true
}
Error Codes
| HTTP | Code | Meaning |
|---|---|---|
| 400 | missing_number | No number supplied. |
| 400 | missing_bot_id | No botId supplied. |
| 400 | invalid_bot_id | botId fails the regex rule. |
| 400 | bad_request | settings is not a plain object. |
| 400 | bad_key | A PATCH key contains a .. |
| 404 | not_found | Installation doesn't exist (GET / DELETE). |
| 404 | not_found | Unknown route. |
| 500 | db_unavailable | MongoDB connection failed. |
| 500 | internal_error | Unhandled server error. |
Validation Rules
number
- All non-digit characters are stripped before use.
"+1 (234) 567-890"becomes"1234567890".- If nothing remains after stripping, the request fails.
botId
- Trimmed and lowercased automatically.
- Must match
/^[a-z0-9][a-z0-9\-_]{1,31}$/. - Length: 2–32 characters.
- Must start with a letter or digit.
- Allowed:
a-z,0-9,-,_.
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);