MongoDB Connector¶

Connect and sync data from MongoDB databases using connection strings.

Base URL¶

BASE_URL = "https://api.fermi.dev/public/v1"

All endpoints are relative to this base URL.

Authentication¶

All endpoints require authentication. Use a service actor token:

Authorization: Bearer <service-actor-token>

Required Scopes:

connectors:read - For read endpoints
connectors:write - For write endpoints
connectors:sync - For synchronization endpoints

Save MongoDB Connection¶

POST /connect/integrations/connect-session

Save a MongoDB connection with connection string and credentials.

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "providerConfigKey": "mongodb",
  "username": "dbuser",
  "password": "dbpassword",
  "metadata": {
    "connectionName": "Production MongoDB",
    "connectionType": "uri",
    "connectionString": "mongodb://host:27017/database",
    "protocol": "mongodb",
    "selectedDatabases": ["mydb"],
    "description": "Production MongoDB database",
    "status": "active",
    "syncStatus": "never"
  }
}

cURL Example:

curl --request POST \
  --url "${BASE_URL}/connect/integrations/connect-session" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "providerConfigKey": "mongodb",
    "username": "dbuser",
    "password": "dbpassword",
    "metadata": {
      "connectionName": "Production MongoDB",
      "connectionType": "uri",
      "connectionString": "mongodb://host:27017/database",
      "selectedDatabases": ["mydb"],
      "description": "Production database"
    }
  }'

Response:

{
  "success": true,
  "connection": {
    "connection_id": "5c096330-fc54-4144-bfec-6bd344da9586",
    "provider_config_key": "mongodb"
  }
}

Test Connection and Fetch Databases¶

POST /database/metadata

Test MongoDB connection and fetch available databases.

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "connectionString": "mongodb://username:password@host:27017/database",
  "databaseType": "mongodb"
}

cURL Example:

curl --request POST \
  --url "${BASE_URL}/database/metadata" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "connectionString": "mongodb://username:password@host:27017/database",
    "databaseType": "mongodb"
  }'

Response:

{
  "success": true,
  "metadata": {
    "databases": [
      {
        "name": "mydb",
        "collections": ["users", "orders", "products"]
      }
    ]
  }
}

List MongoDB Connections¶

GET /connect/integrations/connections?providerConfigKey=mongodb

List all MongoDB connections for the authenticated user.

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter	Type	Required	Description
`providerConfigKey`	string	Yes	Must be `mongodb`

cURL Example:

curl --request GET \
  --url "${BASE_URL}/connect/integrations/connections?providerConfigKey=mongodb" \
  --header "Authorization: Bearer <token>"

Response:

{
  "connections": [
    {
      "id": 517,
      "connection_id": "5c096330-fc54-4144-bfec-6bd344da9586",
      "provider_config_key": "mongodb",
      "created_at": "2025-01-15T10:30:00Z",
      "metadata": {
        "connectionName": "Production MongoDB",
        "connectionType": "uri",
        "selectedDatabases": ["mydb"],
        "status": "active",
        "syncStatus": "completed",
        "totalDocumentsSynced": 15000
      }
    }
  ],
  "total": 1
}

Get Connection Details¶

GET /connect/integrations/connections/{connectionId}

Get detailed information about a MongoDB connection.

Headers:

Authorization: Bearer <token>

cURL Example:

curl --request GET \
  --url "${BASE_URL}/connect/integrations/connections/5c096330-fc54-4144-bfec-6bd344da9586" \
  --header "Authorization: Bearer <token>"

Response:

{
  "id": 517,
  "connection_id": "5c096330-fc54-4144-bfec-6bd344da9586",
  "provider_config_key": "mongodb",
  "created_at": "2025-01-15T10:30:00Z",
  "metadata": {
    "connectionName": "Production MongoDB",
    "connectionType": "uri",
    "connectionString": "mongodb://host:27017/database",
    "selectedDatabases": ["mydb"],
    "description": "Production database connection",
    "status": "active",
    "syncStatus": "completed",
    "totalDocumentsSynced": 15000,
    "lastSyncedAt": "2025-01-15T12:00:00Z"
  }
}

Update Connection Metadata¶

POST /connect/integrations/connection-metadata

Update MongoDB connection metadata (selected databases, description, etc.).

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
  "providerConfigKey": "mongodb",
  "metadata": {
    "connectionName": "Production MongoDB",
    "connectionType": "uri",
    "connectionString": "mongodb://host:27017/database",
    "selectedDatabases": ["mydb", "analytics"],
    "description": "Production and analytics databases",
    "status": "active",
    "syncStatus": "never"
  }
}

cURL Example:

curl --request POST \
  --url "${BASE_URL}/connect/integrations/connection-metadata" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
    "providerConfigKey": "mongodb",
    "metadata": {
      "connectionName": "Production MongoDB",
      "selectedDatabases": ["mydb"],
      "description": "Production database"
    }
  }'

Response:

{
  "success": true,
  "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
  "providerConfigKey": "mongodb",
  "metadata": {
    "connectionName": "Production MongoDB",
    "selectedDatabases": ["mydb"],
    "description": "Production database"
  }
}

Start MongoDB Sync¶

POST /sync/enqueue

Start data synchronization for a MongoDB connection.

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
  "providerKey": "mongodb"
}

cURL Example:

curl --request POST \
  --url "${BASE_URL}/sync/enqueue" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "connectionId": "5c096330-fc54-4144-bfec-6bd344da9586",
    "providerKey": "mongodb"
  }'

Response:

{
  "success": true,
  "enqueuedCount": 1,
  "jobs": [
    {
      "jobId": "8f2c1a4e-9d3b-4c12-a7e6-1b0f3d9e2a11",
      "type": "mongodb"
    }
  ]
}

If no databases are selected: { "success": true, "message": "No databases selected for sync", "enqueuedCount": 0 }. If already queued or synced: { "success": true, "message": "Already queued/synced", "enqueuedCount": 0 }.

Disconnect MongoDB¶

DELETE /connect/integrations/connection/{connectionId}?providerConfigKey=mongodb

Remove a MongoDB connection. This DELETE currently returns 502 on the public path.

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter	Type	Required	Description
`providerConfigKey`	string	Yes	Must be `mongodb`

cURL Example:

curl --request DELETE \
  --url "${BASE_URL}/connect/integrations/connection/5c096330-fc54-4144-bfec-6bd344da9586?providerConfigKey=mongodb" \
  --header "Authorization: Bearer <token>"

Response:

{
  "success": true,
  "alertingLifecycle": {
    "alerting_stopped": true
  }
}

Connection Configuration¶

MongoDB connection metadata supports the following fields:

Field	Type	Description
`connectionName`	string	Display name for the connection
`connectionType`	string	Connection type: `uri` (connection string)
`connectionString`	string	MongoDB connection string (credentials removed)
`protocol`	string	Protocol: `mongodb` or `mongodb+srv`
`selectedDatabases`	string[]	List of databases to sync
`description`	string	Connection description for LLM context (optional)
`status`	string	Connection status: `active`, `inactive`
`syncStatus`	string	Sync status: `never`, `in_progress`, `completed`, `failed`
`totalDocumentsSynced`	number	Total documents synced
`lastSyncedAt`	string	ISO timestamp of last sync

Connection String Formats¶

MongoDB supports two connection string formats:

Standard Connection String¶

mongodb://username:password@host:27017/database?authSource=admin

SRV Connection String (MongoDB Atlas)¶

mongodb+srv://username:[email protected]/database?retryWrites=true&w=majority

Endpoints Summary¶

Method	Endpoint	Description
POST	`/connect/integrations/connect-session`	Save MongoDB connection
POST	`/database/metadata`	Test connection and fetch databases
GET	`/connect/integrations/connections`	List connections
GET	`/connect/integrations/connections/{connectionId}`	Get connection details
POST	`/connect/integrations/connection-metadata`	Update connection metadata
POST	`/sync/enqueue`	Start MongoDB sync
DELETE	`/connect/integrations/connection/{connectionId}`	Disconnect MongoDB

Features¶

Connection String Support - Use standard or SRV connection strings
Database Selection - Choose specific databases to sync
Connection Testing - Test connections and fetch available databases
Document Synchronization - Sync MongoDB documents to knowledge graph
LLM Context - Add descriptions to help AI understand your data
Connection Management - Create, update, and delete connections
SSL/TLS Support - Secure connections with SSL/TLS

Next Steps¶

Data Connectors Overview - Return to data connectors overview
API Reference Overview - Return to API reference index
Scopes and Permissions - Learn about connector scopes
Code Examples - Examples (coming soon)