API Documentation

Complete guide to integrating with the Vaachas API

Works with Postgres (incl. Supabase), MongoDB (incl. Atlas), Elasticsearch (incl. Bonsai), and Cassandra (incl. DataStax Astra DB).

v1.0.0
Quick Navigation
What is a Database GatewayPilot BriefOverviewQuickstartVendor setup linksAuthenticationRequests & ResponsesStatusQuery SyntaxRate LimitsTroubleshootingIdempotency & Partial Failures
Overview

Vaachas is the operational layer between your app and every datastore you rely on. Ship multi-database workflows without custom routing code, queue plumbing, or ad-hoc credential management. This guide shows how to wire the gateway into your stack in minutes—provision connections, register them once, and call a single HTTP API for writes and reads.

Follow the quickstart to set up databases, register credentials, and issue your first request. Later sections cover payload formats, long-running write tracking, authentication, and operational guardrails so you can plug Vaachas into production services with confidence.

Base URL

https://api.vaachas.com

Drop the custom glue

Central API instead of bespoke queue and worker code.

One request, many databases

Sync the primary and secondaries with ordered writes.

Operate with guardrails

API keys, retries, and status polling built in.

Authentication

Include your API key using the X-API-KEY header for all requests.

Example Request

curl -X POST "https://api.vaachas.com/api/data/v1/direct"   -H "Content-Type: application/json"   -H "X-API-KEY: YOUR_API_KEY"   -d '{
  "dbId": "YOUR_DB_ID",
  "query": "SELECT * FROM products"
}'
Quickstart
  1. Provision or pick databases you want to use.
  2. Create schema in your provisioned databases.
  3. Find your provider connection credentials (host/port/user/db or connection string).
  4. Register those databases in Vaachas.
  5. Generate an API key.
  6. Test requests in the browser using Developer Tools.

Step 1 — Provision databases (or use existing)

Bring an existing cluster or pick any managed option. Vaachas supports most PostgreSQL, MongoDB, Cassandra, and Elasticsearch providers out of the box.

PostgreSQLSQL

Managed Postgres with full compatibility for host/port or connection string modes.

SupabaseNeonAWS RDS
MongoDBDocument

Deploy a managed MongoDB cluster or connect your self-hosted deployment.

MongoDB AtlasDigitalOceanAzure Cosmos DB
CassandraWide Column

Fully managed Cassandra with Secure Connect bundle support for Vaachas integrations.

DataStax Astra DBAWS KeyspacesInstaclustr
ElasticsearchSearch

Provision managed Elasticsearch and capture the endpoint URL for your index.

BonsaiElastic CloudSelf-managed

Already have these databases provisioned? Continue to Step 2.

Step 2 — Create schema in your provisioned DBs

Run these DDL commands in your provider consoles or your own DB clients. Do not run them via Vaachas.

RelationalSQL
Wide ColumnCQL
DocumentJSON
SearchMapping

Step 3 — Find your connection credentials

Locate host/port/database/username/password or the connection string in your provider console. Some providers like Mongo atlas require whitelisting IPs for access. So, if required whitelist this IP on provider for flawless functioning - 51.222.62.168/29

PostgreSQLSupabase
MongoDBAtlas
ElasticsearchBonsai
CassandraAstra DB

Step 4 — Register your databases in Vaachas

  1. Open Dashboard → Databases (/dashboard/credentials).
  2. Click Add Database.
  3. Provide Name and select Type (POSTGRES, SUPABASE, MONGO, ELASTIC, CASSANDRA).
  4. Add at least one Connection.
    • HOST_PORT: host, port, username, password, and database/index (Elasticsearch uses Index).
    • CONNECTION_STRING: connection string (Mongo requires database name too).
    • API_KEY: for Astra DB, token + Secure Connect bundle (base64); otherwise API key.
  5. Save. The database appears in your list with an ID (dbId).
Vaachas dashboard Databases listVaachas Add New Database form

Databases list and Add New Database form.

Step 5 — Generate an API key

  1. Open Dashboard → API Keys (/dashboard/api-keys).
  2. Click Generate API Key, give it a name, set expiration, and create.
  3. Copy the key and store it securely.
Vaachas API Keys page with Generate modal

API Keys: Generate API Key modal.

Step 6 — Test requests in Developer Tools

  1. Open Dashboard → Developer Tools (/dashboard/developer-tools) → API Testing.
  2. Select Request Type: Query (read) or Manipulation (write).
  3. Choose or paste your API Key (X-API-KEY). You can copy/paste queries text in the following diagrams from Requests & Responses.
  4. For Manipulation: Add one or more write commands with target dbs and sequence. Click Execute. If a tracking id is returned, use Check Status.
  5. For Query: Select a Database by dbId and paste a read query. Click Execute. View Response.
Developer Tools API Testing Console Writes

Developer Tools: API Testing Console overview writes.

Developer Tools API Testing Console Reads

Developer Tools: API Testing Console overview reads.

Copy‑paste queries for Developer Tools
PostgresSQL
MongoDBJSON
ElasticsearchDSL
CassandraCQL
Vendor setup links

Use any provider. Common starting points:

Requests & Responses
POST/api/data/v1/direct

Two request shapes are supported:

DirectDbDataManipulationRequest (DML fan‑out)
{
  "queryToDbsMap": {
    "INSERT INTO products (id,name,price) VALUES ('111...','Acme Anvil',49.99)": [
      { "dbId": "supabase", "sequence": 0 },
      { "dbId": "elastic", "sequence": 1 }
    ]
  }
}

sequence 0 runs synchronously; higher sequences continue in the same workflow. Default sequence is 1. Same sequence values run in parallel.

DirectDbDataQueryRequest (DQL read)
{
  "dbId": "supabase",
  "query": "SELECT * FROM products ORDER BY created_at DESC"
}
Responses

DataManipulationResponse (sync)

{
  "queries": [
    {
      "query": "INSERT INTO products (...) VALUES (...)",
      "dbs": [ { "dbId": "supabase", "succeeded": true } ]
    }
  ]
}

DataManipulationResponse (async)

{ "requestTrackingId": "req-123" }

DataManipulationResponse (mixed)

{
  "queries": [ { "query": "...", "dbs": [ { "dbId": "supabase", "succeeded": true } ] } ],
  "requestTrackingId": "req-123"
}

DataQueryResponse

{ "results": [{"id":"..."}], "succeeded": true }
{ "results": null, "succeeded": false, "error": "details" }

Per‑DB status object: { "dbId": string, "succeeded": boolean, "error": string | null }.

cURL examples
DML fan‑out (mixed)
curl -X POST "https://api.vaachas.com/api/data/v1/direct"   -H "Content-Type: application/json"   -H "X-API-KEY: YOUR_API_KEY"   -d '{
    "queryToDbsMap": {
      "INSERT INTO products (id,name,price) VALUES (''11111111-1111-1111-1111-111111111111'',''Acme Anvil'',49.99)": [
        { "dbId": "supabase", "sequence": 0 },
        { "dbId": "elastic", "sequence": 1 }
      ]
    }
  }'
DQL read
curl -X POST "https://api.vaachas.com/api/data/v1/direct"   -H "Content-Type: application/json"   -H "X-API-KEY: YOUR_API_KEY"   -d '{
    "dbId": "supabase",
    "query": "SELECT * FROM products ORDER BY created_at DESC"
  }'
Status
GET/api/data/v1/direct/status/{requestTrackingId}

Poll the execution status of asynchronous or mixed workflows.

{
  "requestStatus": "RUNNING | COMPLETED | FAILED | TERMINATED | CANCELED | UNKNOWN",
  "queries": [ { "query": "...", "dbs": [ { "dbId": "supabase", "succeeded": true, "error": null } ] } ]
}
Query Syntax

The Direct API executes your queries against the target engines in their native dialects:

  • Postgres (incl. Supabase): SQL
  • MongoDB (incl. Atlas): db.runCommand JSON
  • Elasticsearch (incl. Bonsai): REST/DSL JSON
  • Cassandra (incl. DataStax Astra DB): CQL
We do not validate or rewrite your queries. Ensure they are safe and correct for the target engine.
Roadmap: MariaDB support.
Rate Limits

API calls are rate‑limited per plan.

GET/api/v1/ratelimit/me

View your current plan and effective rate limit policy.

curl -X GET "https://api.vaachas.com/api/v1/ratelimit/me"   -H "X-API-KEY: YOUR_API_KEY"
Troubleshooting
400 Bad Request — invalid payload
  • Cause: JSON shape does not match DirectDbDataManipulationRequest or DirectDbDataQueryRequest.
  • Fix: Validate JSON; required fields present; query syntax valid for the target DB.
  • Tip: For Mongo/Elasticsearch, send valid command/DSL JSON; for Cassandra/Postgres, send valid CQL/SQL.
403 Forbidden — authentication required
  • Cause: Missing or invalid API key.
  • Fix: Include X-API-KEY header; ensure key is active in /dashboard/api-keys.
404 Not Found — status id
  • Cause: requestTrackingId is wrong or expired.
  • Fix: Verify the id returned by the initial request; re-run if necessary.
Per‑DB connection/auth errors
  • Symptom: Response shows per‑DB error with succeeded: false.
  • Fix: Check connection details in /dashboard/credentials; verify host/port or connection string, user/password/API key, database/index name, and network access.
Idempotency & Partial Failures
Execution model
  • sequence = 0 runs synchronously; its results appear in the immediate response.
  • Same sequence values run in parallel.
  • Higher sequence values continue in the same workflow and may complete asynchronously; a requestTrackingId is returned. Use the Status API to poll.
Handling partial successes
  • Check per‑DB statuses: { dbId, succeeded, error }.
  • When a response includes both per‑DB results and a requestTrackingId, poll until the workflow reaches a terminal state.
  • Design reads to tolerate missing/lagging targets (e.g., read from a primary source when a replica/index update is pending).
Idempotent writes
  • Use stable, deterministic identifiers in your payloads (e.g., product IDs) and prefer upsert semantics where supported.
  • Avoid non‑deterministic functions in write statements unless necessary.
  • If you implement client‑side retries, ensure your writes are idempotent to prevent duplicates.