Florentine.ai API - Talk to your MongoDB data

The Florentine.ai API lets you integrate natural language querying for your MongoDB data directly into your project.

Questions are transformed into MongoDB aggregations that can also directly be executed and answered in natural language.

Also has a couple of extra features under the hood, e.g.:

• Secure data separation for multi-tenant usage
• Semantic vector search/RAG support with automated embedding creation
• Advanced lookup support
• Exclusion of keys

[!NOTE] If you are looking for our MCP Server you can find it here.

Contents

• Prerequisites
• Installation
• Authentication
• Connect your LLM account
  • Option 1: Save your LLM key in your account (recommended)
  • Option 2: Provide your LLM key in API requests
• First Request
• Return Types
  • Example returning all three steps
• Secure Data Separation for multi-tenant usage
  • Providing Required Inputs
  • Required Inputs Configuration
  • Supported Value Types
  • Usage Examples
• Sessions
• Errors
  • Handle errors in client
  • Common Errors

Prerequisites

• Node.js >= v18.0.0
• A Florentine.ai account (create a free account here)
• A connected database and at least one analyzed and activated collection in your Florentine.ai account
• A Florentine.ai API Key (you can find yours on your account dashboard)

Installation

A detailed documentation of the API can be found here in our docs.

npm install @florentine-ai/api

Authentication

import { Florentine } from '@florentine-ai/api';

const FlorentineAI = new Florentine({
  florentineToken: '<FLORENTINE_API_KEY>'
});

Connect your LLM account

Florentine.ai works as a bring your own key model, so you need to provide your LLM API key (OpenAI, Google, Anthropic, Deepseek) in your API requests.

You have two options how you can add your LLM API key:

Option 1: Save your LLM key in your account (recommended)

The easiest way to connect to your LLM provider is to save your LLM API key in your Florentine.ai dashboard.

• Add your API key
• Select your LLM provider (OpenAI, Deepseek, Google or Anthropic)
• Click Save

Option 2: Provide your LLM key in API requests

If you prefer not to store the key in your Florentine.ai account or want to use multiple LLM keys, you can pass the key in your API request.

Add the values as llmService and llmKey to the class constructor object:

const FlorentineAI = new Florentine({
  florentineToken: '<FLORENTINE_API_KEY>',
  llmService: '<YOUR_LLM_SERVICE>', // one of: "openai", "google", "anthropic", "deepseek"
  llmKey: '<YOUR_LLM_API_KEY>'
});

[!NOTE] If you provide an llmKey inside the request, it will override any key stored in your account.

First Request

You should now be ready to send your first API request!

Come up with a question that can be answered via the data in your activated collection(s) and pass it to the .ask() method:

const FlorentineAI = new Florentine({
  florentineToken: '<FLORENTINE_API_KEY>'
});

const res = await FlorentineAI.ask({
  question: '<YOUR_QUESTION>',
  sessionId: 'FIRST_REQUEST'
});

By default, the API returns a natural language answer based on the aggregation results.

Imagine a tabletennis collection that records the results of the matches of two players. If I ask the question Who won the last match? the answer might look similar to this:

{
  "answer": "Frank won the last match. According to our records, he emerged as the winner, highlighting his strong performance in that game."
}

Return Types

By default, the API returns a natural language answer to the question provided. However, what's happening in the background is actually three steps:

1. Aggregation Generation: The question is converted into a MongoDB aggregation query.
2. Query Execution: The aggregation runs against the database using the connection string you provided.
3. Answer Generation: The structured result is transformed into a natural language answer.

You can choose which of these steps you want returned by specifying a returnTypes array with any combination of:

Example returning all three steps

Let's imagine the tabletennis example from the first request section once more.
With all three steps the request looks like this:

const res = await FlorentineAI.ask({
  question: 'Who won the last match?',
  returnTypes: ['aggregation', 'result', 'answer']
});

And the response looks like this:

{
  "database": "samples",
  "collection": "tabletennis",
  "aggregation": [
    { "$sort": { "year": -1, "matchInYear": -1 } },
    { "$limit": 1 },
    {
      "$project": {
        "winner": {
          "$cond": {
            "if": { "$eq": ["$matchwinner", "home"] },
            "then": "$players.home",
            "else": "$players.away"
          }
        }
      }
    }
  ],
  "result": [{ "_id": "67d352056d3ef0f2281524cf", "winner": "Frank" }],
  "answer": "Frank won the last match. According to our records, he emerged as the winner, highlighting his strong performance in that game."
}

Secure Data Separation for multi-tenant usage

You can enable secure data separation by ensuring aggregation pipelines filter data based on provided values which we call Required Inputs.

These values are added to the pipeline by the Florentine.ai transformation layer after the aggregation generation by the LLM. Thus Florentine.ai can assure each user only retrieves the data he is eligible to.

Keys are defined as Required Input in your account, please refer to the section in our official docs on how to do that.

Providing Required Inputs

Provide your Required Inputs inside a requiredInputs array with keyPath and value for each key you set as Required Input and add it to the .ask() method:

const res = await FlorentineAI.ask({
  question: 'What is the revenue of my products this year?',
  requiredInputs: [
    {
      keyPath: 'accountId',
      value: '507f1f77bcf86cd799439011'
    }
  ]
});

You may also provide a database and a collections array in case you have Required Inputs with the same keyPath in multiple collections but different value for the collections:

const res = await FlorentineAI.ask({
  question: 'Whats the current monthly rent of my tenants?',
  requiredInputs: [
    {
      keyPath: 'name',
      value: 'Sesame Street',
      database: 'rentals',
      collections: ['houses']
    },
    {
      keyPath: 'name',
      value: { $in: ['Ernie', 'Bert'] },
      database: 'rentals',
      collections: ['tenants']
    }
  ]
});

Required Inputs Configuration

Supported Value Types

Based on the type of the values for the key you have different options on what you can provide as a Required Input value:

Usage Examples

Example type: String

Usecase: A user should only be able to see statistics of the players he frequently plays with.

Solution: Restricting access by player name to a group of 4 players.

const res = await FlorentineAI.ask({
  question: 'Which player had the most wins?',
  requiredInputs: [
    {
      keyPath: 'name',
      value: { $in: ['Megan', 'Frank', 'Jen', 'Bob'] }
    }
  ]
});

Example type: ObjectId

Usecase: A user should only be able to see the revenue of his own products.

Solution: Restricting the access by the accountId to one specific account.

const res = await FlorentineAI.ask({
  question: 'Whats the revenue of my products?',
  requiredInputs: [
    {
      keyPath: 'accountId',
      value: '507f1f77bcf86cd799439011'
    }
  ]
});

Example type: Boolean

Usecase: Every analysis of customers should only be performed on paying customers.

Solution: Restricting the access by isPaidAccount to paying customers only.

const res = await FlorentineAI.ask({
  question: 'How many customers registered in the last year?',
  requiredInputs: [
    {
      keyPath: 'isPaidAccount',
      value: true
    }
  ]
});

Example type: Number

Usecase: An employee should only be allowed to see payment information for payments below a certain amount.

Solution: Restricting the access by amount to payments below 10.000.

const res = await FlorentineAI.ask({
  question: 'List all payments we received.',
  requiredInputs: [
    {
      keyPath: 'amount',
      value: { $lt: 10000 }
    }
  ]
});

Example type: Date

Usecase: The analysis of financial data should only include one specific year.

Solution: Restricting the access by transactionDate to all transactions in 2024.

const res = await FlorentineAI.ask({
  question: 'What was our revenue, profit and margin per month?',
  requiredInputs: [
    {
      keyPath: 'transactionDate',
      value: {
        $gte: '2023-01-01T00:00:00Z',
        $lt: '2024-01-01T00:00:00Z'
      }
    }
  ]
});

Sessions

Sessions allow Florentine.ai to enable a server-side chat history. Just provide a sessionId string like this:

const res = await FlorentineAI.ask({
  question: 'What is the revenue of my products this year?',
  sessionId: '<YOUR_SESSION_ID>'
});

Sessions are mandatory unless you disable the server-side chat history by setting withHistory to false inside the constructor:

const FlorentineAI = new Florentine({
  florentineToken: '<FLORENTINE_API_KEY>',
  withHistory: false
});

[!NOTE] It is strongly recommended to use a sessionId to have meaningful multi-turn conversations.

Errors

All errors from the Florentine.ai API follow this consistent JSON structure:

{
  "error": {
    "name": "FlorentineApiError",
    "statusCode": 401,
    "message": "Please provide your Florentine API key. You can find it in your account settings: https://florentine.ai/settings",
    "errorCode": "NO_TOKEN",
    "requestId": "abc123"
  }
}

Handle errors in client

API errors are automatically thrown as JavaScript error classes:

import { Florentine, FlorentineApiError } from '@florentine-ai/api';

try {
  const FlorentineAI = new Florentine({});
  const res: TFlorentineReturnOutput = await FlorentineAI.ask({
    question: 'Who is Florentine?'
  });
} catch (err) {
  if (err instanceof FlorentineApiError) {
    console.error(err.message); // "Please provide your Florentine API key."
    console.error(err.statusCode); // 401
    console.error(err.errorCode); // "NO_TOKEN"
    console.error(err.requestId); // "abc123"
  }
}

All client errors extend the FlorentineError class, so you can catch all client related errors like this:

if (err instanceof FlorentineError) {
  // Catches all florentine npm package errors
}

Common Errors