Vastu API Integration Guide

Recipe 1 — Floor plan audit (curl)

When: User finished tagging rooms; you want score + defect list.

curl -X POST https://api.vedika.io/v2/astrology/vastu/audit/floor-plan \
  -H "Authorization: Bearer $VEDIKA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rooms": [
      { "roomType": "kitchen",        "zone": "SE" },
      { "roomType": "master_bedroom", "zone": "SW" },
      { "roomType": "pooja",          "zone": "NE" },
      { "roomType": "toilet",         "zone": "NE" }
    ]
  }'

# Read response.data.score, grade, totalRooms, defects and sources.
# Computed scores and traditional conventions are not verified verse claims.

Recipe 2 — Mandala projection (JavaScript)

When: AR app finished a scan and has a plot polygon.

const plotPolygon = [[0,0], [12,0], [12,12], [0,12]];
const r = await fetch(
  'https://api.vedika.io/v2/astrology/vastu/mandala/project/9-zone',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.VEDIKA_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      plotPolygon,
      bearingDeg: 0  // geometry is already +X east, +Y north
    })
  }
);
const { data } = await r.json();
data.cells.forEach(cell => {
  // Rectangular grid cells use the input 2D frame and units.
  // Clip cells to your plot, then map to your AR world frame.
  arScene.addPolygon(clipAndMapToArWorld(cell.polygon, plotPolygon), {
    color: '#6b7280', // A grid cell alone is not an audit result.
    label: cell.zone
  });
});

Recipe 3 — AI Query in Hindi (curl)

When: User typed a Vastu question in their language.

curl -X POST https://api.vedika.io/api/v1/query \
  -H "Authorization: Bearer $VEDIKA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "question": "मेरे मुख्य द्वार दक्षिण-पश्चिम मुखी है, क्या उपाय करूं?" }'

# Read the returned answer and its sources.
# Preserve the distinction between citations and traditional conventions.

Recipe 4 — Detailed audit (Python)

When: Premium audit — one call returns score + heatmap + remediation order.

import os, requests
r = requests.post(
    'https://api.vedika.io/v2/astrology/vastu/audit/floor-plan-detailed',
    headers={'Authorization': f'Bearer {os.environ["VEDIKA_KEY"]}'},
    json={
        'rooms': [
            {'roomType': 'kitchen', 'zone': 'SE'},
            {'roomType': 'toilet',  'zone': 'NE'},
        ],
        'plotPolygon': [[0,0],[12,0],[12,12],[0,12]],
        'bearingDeg': 0
    }
).json()

print(r['data']['score'], r['data']['grade'])
for step in r['data']['remediationOrder']:
    print(step['step'], step['room'], '-', step['action'])
# Render the returned action and its source/provenance; do not invent a citation.

Recipe 5 — Magnetic declination (true-north correction)

When: AR scan starts. Call once per scan to convert phone-compass to true-north.

curl "https://api.vedika.io/v2/astrology/vastu/direction/declination?lat=18.5204&lon=73.8567" \
  -H "Authorization: Bearer $VEDIKA_KEY"

# Read data.declinationDeg and data.verified from the response.
# The correction can be null outside the grid coverage.

function trueBearingFromCorrection(magneticBearing, data) {
  if (!Number.isFinite(magneticBearing) || data?.verified !== true ||
      !Number.isFinite(data.declinationDeg)) return null;
  return ((magneticBearing + data.declinationDeg) % 360 + 360) % 360;
}

Recipe 6 — 32-pada door classifier

When: User taps the door position in your AR scene.

curl -X POST https://api.vedika.io/v2/astrology/vastu/entrance/pada \
  -H "Authorization: Bearer $VEDIKA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plotPolygon": [[0,0],[12,0],[12,12],[0,12]],
    "doorXY": [12, 6],
    "bearingDeg": 0
  }'

# Read response.data.pada and its source/provenance fields.
# This example places the door on the east plot boundary.
# Use your measured boundary door point for a real assessment.

Recipe 7 — AR scan quality (gate before audit)

When: Scan done; verify quality before paying for audit.

curl -X POST https://api.vedika.io/v2/astrology/vastu/ar/scan-quality \
  -H "Authorization: Bearer $VEDIKA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pointCloudDensity": 1800,
    "polygonClosure": true,
    "compassConfidence": 0.9,
    "gpsConfidence": 0.95,
    "roomsTagged": 4,
    "roomCount": 4,
    "expectedRoomCount": 4,
    "scanDurationSec": 45,
    "scannedAreaM2": 30
  }'

# Read data.acceptForAudit and data.reScanSuggestions.
# Missing readings have null scores. Room counts must state the captured and expected scope.
# Acceptance checks caller-reported consistency; it does not attest a device scan.

Recipe 8 — Plot ratio audit (pre-construction)

When: Real-estate listing or builder's pre-construction audit.

curl -X POST https://api.vedika.io/v2/astrology/vastu/plot/ratio \
  -H "Authorization: Bearer $VEDIKA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "plotPolygon": [[0,0],[18,0],[18,9],[0,9]] }'

# Read data.length, data.width, data.ratio and data.units.
# Dimensions stay in caller-supplied units; they are not converted to metres.
# Deprecated lengthM/widthM are null because this request has no metre scale.

1. Auto-detection (default — 17 trigger patterns)

curl -X POST https://api.vedika.io/api/v1/query \
  -H "Authorization: Bearer vk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "question": "Where should I put my pooja room?" }'

# Auto-fires on: vastu, vaastu, ishanya, agneya, nairutya, vayavya, brahmasthana,
#                main door, pooja room, kitchen direction, sleeping direction,
#                home faces, bedroom NE/NW/SE/SW, etc.

2. Bracket override — {vastu} / {vaastu}

# Bracket-prefixed (recommended for explicit control)
curl -X POST https://api.vedika.io/api/v1/query \
  -H "Authorization: Bearer vk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "question": "{vastu} What about my master bedroom?" }'

# Equivalent — bracket anywhere in the question
curl -X POST https://api.vedika.io/api/v1/query \
  -H "Authorization: Bearer vk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "question": "Help with placement {vastu} please" }'

# Both forms ({vastu} and {vaastu}) trigger the same Vastu directive injection.

3. Enterprise custom Vastu preferences

curl -X POST https://api.vedika.io/api/v1/query \
  -H "Authorization: Bearer vk_ent_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "{vastu} Master bedroom in NE — what should I do?",
    "customDirective": {
      "region": "south-india",
      "preferredRemedies": ["yantra", "color-therapy"],
      "tone": "formal-tamil",
      "disclaimer": "This guidance is subject to our terms.",
      "attribution": "Prepared for Acme Homes.",
      "suppressClaims": false,
      "additionalRules": [
        "Prefer non-structural options when supported",
        "Explain limits in short sentences"
      ]
    }
  }'

# Requires an authenticated Enterprise key or Enterprise plan.
# Preferences guide the answer; computed facts and source citations stay unchanged.

1App boot — fetch reference data once

// Server-side, behind your app's own authenticated proxy.
const apiBase = 'https://api.vedika.io';
const headers = {
  'Authorization': `Bearer ${process.env.VEDIKA_KEY}`,
  'Content-Type': 'application/json'
};
const zones = await fetch(`${apiBase}/v2/astrology/vastu/reference/mandala/9-zone`, { headers }).then(r => r.json());
const devatas = await fetch(`${apiBase}/v2/astrology/vastu/reference/mandala/45-devatas`, { headers }).then(r => r.json());
cacheLocally(zones.data, devatas.data);  // listed total $0.02 for these two reference calls

2Scan starts — get true-north correction

const decl = await fetch(
  `${apiBase}/v2/astrology/vastu/direction/declination?lat=${lat}&lon=${lon}`,
  { headers }
).then(r => r.json());
const trueBearing = trueBearingFromCorrection(compassBearing, decl.data);
if (trueBearing === null) { showMagneticHeadingOnly(); return; }
// Already-true native headings need no declination correction.

3Scan finishes — extract polygon and rooms

4Check reported scan quality before paying for audit

const quality = await fetch(`${apiBase}/v2/astrology/vastu/ar/scan-quality`, {
  method: 'POST', headers,
  body: JSON.stringify({ pointCloudDensity, polygonClosure, compassConfidence,
                         gpsConfidence, roomsTagged, roomCount, expectedRoomCount,
                         scanDurationSec, scannedAreaM2 })
}).then(r => r.json());
// This gate checks caller-reported telemetry; it does not attest sensors or physical coverage.
if (!quality.data.acceptForAudit) { showReScanPrompt(quality.data); return; }

5One-shot detailed audit

const audit = await fetch(`${apiBase}/v2/astrology/vastu/audit/floor-plan-detailed`, {
  method: 'POST', headers,
  body: JSON.stringify({ rooms, plotPolygon, bearingDeg: 0 })
}).then(r => r.json());
// audit.data.score, .grade, .defects[], .devataHeatmap[], .mandalaProjection.cells[],
// .remediationOrder[]

6Render in AR scene

audit.data.mandalaProjection.cells.forEach(cell => {
  // Neutral means no flagged rule; it does not certify a surveyed or healthy zone.
  const color = audit.data.defects.some(d => d.zone === cell.zone) ? '#b42318' : '#6b7280';
  arScene.addPolygon(clipAndMapToArWorld(cell.polygon, plotPolygon), { color, label: cell.zone });
});

7User taps a defect → fetch narrative explanation

onUserTapDefect(defect => {
  fetch(`${apiBase}/api/v1/query`, {
    method: 'POST', headers,
    body: JSON.stringify({
      question: `Why is my ${defect.room} in the ${defect.zone} a problem?`
    })
  }).then(r => r.json()).then(r => showBottomSheet(r.response));
});

What the reference handler does

// Web-standard fetch handler for your server or edge runtime. No dependencies.
// Mount it at /vedika-proxy on your own site and set the embed's apiBase to '/vedika-proxy'.
const VEDIKA_API = 'https://api.vedika.io';
const PREFIX = '/vedika-proxy';
const MAX_BODY_BYTES = 64 * 1024;
const ALLOWED_ORIGINS = ['https://www.example.com']; // your site's own origins

// Exact method + path pairs. Anything else returns 404 and never reaches Vedika.
const ROUTES = {
  // The AR embed's only request. Keyless; the embed shows it and does not apply it.
  'GET /sandbox/astrology/vastu/direction/declination': { keyed: false, query: ['lat', 'lon'] },
  // Calls your own browser code makes. Each one is billed to your account.
  'POST /v2/astrology/vastu/ar/scan-quality': { keyed: true, query: [] },
  'POST /v2/astrology/vastu/audit/floor-plan-detailed': { keyed: true, query: [] }
};

function reject(status, error) {
  return new Response(JSON.stringify({ error }), {
    status, headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' }
  });
}

async function readCapped(request, limit) {
  if (!request.body) return new Uint8Array(0);
  const reader = request.body.getReader();
  const chunks = [];
  let size = 0;
  for (;;) {
    const { done, value } = await reader.read();
    if (done) break;
    size += value.byteLength;
    if (size > limit) { await reader.cancel(); return null; }
    chunks.push(value);
  }
  const bytes = new Uint8Array(size);
  let offset = 0;
  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
  return bytes;
}

async function handleVedikaProxy(request, env) {
  const origin = request.headers.get('Origin');
  if (origin !== null && !ALLOWED_ORIGINS.includes(origin)) return reject(403, 'origin not allowed');
  const url = new URL(request.url);
  const path = url.pathname.startsWith(PREFIX + '/') ? url.pathname.slice(PREFIX.length) : '';
  const route = ROUTES[`${request.method} ${path}`];
  if (!route) return reject(404, 'not found');

  const upstream = new URL(path, VEDIKA_API);
  for (const key of route.query) {
    const value = url.searchParams.get(key);
    if (value !== null) upstream.searchParams.set(key, value);
  }
  // Built fresh: browser cookies, Authorization and X-API-Key headers are never forwarded.
  const headers = { 'Accept': 'application/json' };
  const requestId = request.headers.get('X-Request-Id');
  if (requestId !== null && /^[A-Za-z0-9._:-]{1,128}$/.test(requestId)) headers['X-Request-Id'] = requestId;
  let body;
  if (request.method === 'POST') {
    if (Number(request.headers.get('Content-Length')) > MAX_BODY_BYTES) return reject(413, 'body too large');
    body = await readCapped(request, MAX_BODY_BYTES);
    if (body === null) return reject(413, 'body too large');
    headers['Content-Type'] = 'application/json';
  }
  if (route.keyed) {
    if (!env.VEDIKA_KEY) return reject(500, 'proxy key not configured');
    headers['Authorization'] = `Bearer ${env.VEDIKA_KEY}`;
  }

  const reply = await fetch(upstream, { method: request.method, headers, body });
  const out = { 'Content-Type': reply.headers.get('Content-Type') || 'application/json', 'Cache-Control': 'no-store' };
  for (const name of ['Retry-After', 'X-Request-Id']) {
    const value = reply.headers.get(name);
    if (value !== null) out[name] = value;
  }
  return new Response(reply.body, { status: reply.status, headers: out });
}

// On your page: the key never reaches the browser.
import { mountVastuAR } from 'https://vedika.io/js/vastu/vastu-ar-embed.js';
mountVastuAR(document.getElementById('vastu-ar'), { apiBase: '/vedika-proxy' });

Caching strategy

async function vastuCacheKey(accountScope, contractRevision, path, body, language = 'en') {
  if (![accountScope, contractRevision, path, language].every(v => typeof v === 'string' && v.trim())) {
    throw new TypeError('Complete account, rule, path and language context is required');
  }
  const active = new Set();
  function canonical(value) {
    if (value === null || typeof value === 'string' || typeof value === 'boolean') {
      return JSON.stringify(value);
    }
    if (typeof value === 'number' && Number.isFinite(value)) return JSON.stringify(value);
    if (typeof value !== 'object' || active.has(value)) {
      throw new TypeError('Only finite, acyclic JSON values are supported');
    }
    active.add(value);
    let result;
    if (Array.isArray(value)) {
      result = '[' + Array.from(value, canonical).join(',') + ']';
    } else if (Object.prototype.toString.call(value) === '[object Object]') {
      result = '{' + Object.keys(value).sort().map(key =>
        JSON.stringify(key) + ':' + canonical(value[key])).join(',') + '}';
    } else {
      throw new TypeError('Only JSON objects and arrays are supported');
    }
    active.delete(value);
    return result;
  }
  const input = canonical({ accountScope, contractRevision, path, language, body });
  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(input));
  return 'vastu-cache-v1:' + Array.from(new Uint8Array(digest), byte =>
    byte.toString(16).padStart(2, '0')).join('');
}

Error handling with retry + idempotency

const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
async function callVedika(path, body, requestId, maxAttempts = 3) {
  if (!requestId || !Number.isInteger(maxAttempts) || maxAttempts < 1) {
    throw new Error('A retained request ID and a positive attempt count are required');
  }
  const payload = JSON.stringify(body);
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    let r;
    try {
      r = await fetch(`https://api.vedika.io${path}`, {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${VEDIKA_KEY}`,
          'Content-Type': 'application/json',
          'X-Request-Id': requestId
        },
        body: payload
      });
    } catch (error) {
      if (attempt === maxAttempts - 1) throw error;
      await sleep(1000 * 2 ** attempt);
      continue;
    }
    let data;
    try {
      data = await r.json();
    } catch (error) {
      if (r.ok) throw error;
      data = {};
    }
    if (r.ok) return data;
    const retryable = r.status === 429 || r.status >= 500;
    if (!retryable || attempt === maxAttempts - 1) {
      throw new Error(`Vedika request failed (${r.status})`);
    }
    const seconds = Number(r.headers.get('Retry-After') ?? data.retryAfter);
    await sleep(Number.isFinite(seconds) && seconds > 0
      ? seconds * 1000 : 1000 * 2 ** attempt);
  }
}

Status code map

JavaScript / TypeScript (@vedika-io/sdk)

import { VedikaClient } from '@vedika-io/sdk';
const vedika = new VedikaClient({ apiKey: process.env.VEDIKA_KEY });

const audit = await vedika.vastuAudit('floor-plan', {
  rooms: [
    { roomType: 'kitchen', zone: 'SE' },
    { roomType: 'toilet',  zone: 'NE' }
  ]
});
console.log(audit.score, audit.grade, audit.defects);

Python (vedika-sdk)

from vedika import VedikaClient
vedika = VedikaClient(api_key="vk_live_...")

audit = vedika.vastu_audit("floor-plan", params={
    "rooms": [
        {"roomType": "kitchen", "zone": "SE"},
        {"roomType": "toilet",  "zone": "NE"},
    ]
})
print(audit["data"]["score"], audit["data"]["grade"], audit["data"]["defects"])

Why customers switch