POST /api/analyze

Request body

{
  "prompt": "show me products under $30",
  "fields": ["name", "price", "category", "stock"],
  "collections": ["products", "orders", "customers"]
}

The engine is stateless — it never stores the prompt, never connects to your database, and only uses fields / collections to improve routing accuracy. Sending the raw schema is discouraged; sending data values is forbidden by the contract (the API will accept them but they have no effect and will appear in our access logs only as their length).

Response — 200 OK

{
  "analysis": {
    "intent": "find",
    "operation": null,
    "metric": null,
    "groupBy": [],
    "timeFrame": null,
    "collection": ["products"],
    "limit": null,
    "sort": {},
    "filters": { "price": { "$lt": 30 } },
    "visualization": "TABLE",
    "rawTokens": ["show", "product", "price", "under", "30"]
  },
  "tokens": ["show", "product", "price", "under", "30"],
  "plan": "pro",
  "planTier": "pro",
  "usage": { "used": 12, "limit": 1000 },
  "sector": {
    "id": "ecommerce",
    "label": "E-commerce / Retail",
    "confidence": "high"
  },
  "message": "Prompt analyzed successfully"
}

analysis — the Analysis object

This is the structured intent the sidecar consumes. The exact shape is defined in the internal packages/shared/src/contracts/analysis.js file and is reproduced here:

Other response fields

Response — errors

All error responses are JSON with at minimum { error, message }.

Every response — including 2xx — carries:

• X-Request-Id — opaque correlation id. Include this when reporting a bug.
• X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset — current per-key bucket state.

429 responses additionally include Retry-After in seconds.

Example — cURL

curl -X POST https://nlp-engine-prod.lunamic.co/api/analyze \
  -H "Authorization: Bearer $IOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "show me products under $30",
    "fields": ["name", "price", "category", "stock"],
    "collections": ["products", "orders", "customers"]
  }'

Example — Node

const res = await fetch("https://nlp-engine-prod.lunamic.co/api/analyze", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.IOM_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: "top 10 customers by revenue this quarter",
    fields: ["id", "name", "total", "createdAt"],
    collections: ["customers", "orders"],
  }),
});

if (res.status === 429) {
  const retry = Number(res.headers.get("Retry-After") || "1");
  await new Promise((r) => setTimeout(r, retry * 1000));
  // …retry
}

const { analysis, plan, usage } = await res.json();
// Hand `analysis` to your query generator. The sidecar's generator
// in this repo is one reference implementation.