API reference

The NLP engine exposes one endpoint. The desktop client uses it; you can hit it from any HTTP client you like.

Base URL

Hosted: https://api.insightomate.ai
Self-hosted: whatever URL you mapped your container to.

Authentication

A Bearer token in the Authorization header. Create one from the dashboard; it looks like iom_....

Authorization: Bearer iom_8f4c9e1b...

`POST /analyze`

Translate a prompt + schema into a MongoDB query.

Request

{
  "prompt": "string, 1..2000 chars",
  "schema": {
    "<collection>": {
      "<field>": "string | number | boolean | Date | ObjectId | array | object"
    }
  },
  "dialect": "mongodb",
  "mongo_version": "7.0"
}

Fields:

Field	Type	Required	Notes
`prompt`	string	yes	Plain-English question. Truncated past 2000 chars.
`schema`	object	yes	Map of collection → (map of field → type string).
`dialect`	string	yes	Only `"mongodb"` is supported today.
`mongo_version`	string	no	Server version — enables version-specific operators if absent.

Response — 200 OK

{
  "query": {
    "type": "aggregate",
    "collection": "users",
    "pipeline": [
      { "$match": { "createdAt": { "$gte": "2026-04-27T00:00:00Z" } } },
      { "$lookup": { "from": "orders", "localField": "_id", "foreignField": "userId", "as": "orders" } },
      { "$match": { "orders": { "$size": 0 } } }
    ]
  },
  "explanation": "New signups in the last 7 days that have no orders linked by userId.",
  "confidence": 0.92,
  "tokens_used": 418
}

The query.type is one of find, aggregate, countDocuments, distinct. Everything else is uniform.

Response — errors

{
  "error": {
    "code": "string",
    "message": "human-readable string",
    "hint": "optional string with how to fix it"
  }
}

HTTP	`code`	Meaning
400	`prompt_too_long`	Prompt > 2000 chars
400	`schema_missing`	`schema` absent or empty
400	`unsupported_dialect`	Only `mongodb` is supported
401	`invalid_key`	Bearer token rejected
402	`quota_exceeded`	Free-tier daily cap reached
422	`prompt_not_understood`	Engine couldn't confidently produce a query
429	`rate_limited`	Too many requests; see `Retry-After` header
500	`engine_error`	Our problem; retry in 30s

Rate limits

Plan	Requests / day	Burst / minute
Free	100	20
Pro	unlimited	120
Team	unlimited	120 / seat

Responses include X-RateLimit-Remaining and X-RateLimit-Reset.

Example — cURL

curl -X POST https://api.insightomate.ai/analyze \
  -H "Authorization: Bearer $IOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "top 10 customers by revenue this quarter",
    "schema": {
      "orders": {
        "userId": "ObjectId",
        "total": "number",
        "createdAt": "Date"
      }
    },
    "dialect": "mongodb"
  }'

Example — Node

const res = await fetch("https://api.insightomate.ai/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",
    schema: { orders: { userId: "ObjectId", total: "number", createdAt: "Date" } },
    dialect: "mongodb",
  }),
});

const { query } = await res.json();
// hand `query.pipeline` to your MongoDB driver