MongoDB API¶

Everything you can do with a MongoDB datastore over the API: create one with a new or an existing connection, test the connection, read and list datastores, update or delete one, and create several at once from the databases of a single deployment.

Complete API Reference

For the full interactive API documentation with all request and response schemas, visit the API docs.

Endpoint: POST /api/datastores

Permission: Manager, plus the Editor team permission on at least one of the assigned teams (the Public team when teams is left out). Admins are exempt.

Source datastores only

MongoDB is read-only and cannot be used as an enrichment datastore. To link a separate enrichment datastore as the MongoDB source's destination, see Datastore API › Link Enrichment Destination.

UI ↔ API field mapping¶

The API names several fields differently from the connection form. The user and password travel outside parameters, which is what keeps the password encrypted.

UI form field	API field	Notes
Connection > Host	`connection.parameters.host`	A hostname, or a comma-separated `host:port` list for a replica set
Connection > Port	`connection.parameters.port`	A number. Used only for a single host written without a port, and never with SRV
Connection > DNS Seed List (SRV)	`connection.parameters.srv`	`"true"` for SRV (`mongodb+srv`), `"false"` otherwise
Connection > SSL Connection	`connection.parameters.ssl`	`true` to connect over TLS. Always on with SRV
Connection > User	`connection.username`	The MongoDB database user
Connection > Password	`connection.password`	Stored encrypted
Connection > Auth Source	`connection.parameters.auth_source`	The database the user is defined in; `admin` when omitted
Location > Database	`schema`	The MongoDB database to monitor

No connection string or options

connection.parameters.connection_string and connection.parameters.options are refused with a message that they are no longer supported. Send the host, port, srv, and auth_source fields instead. A host that contains @, /, ?, or a space is refused too, and so is any parameter value starting with mongodb:// or mongodb+srv:// that carries credentials or a password option.

Create a MongoDB Datastore¶

Both flows use the same endpoint and differ only in whether the connection travels inline or by reference.

New ConnectionExisting Connection

Pass the host settings and the credentials inline. Qualytics saves the connection and creates the datastore in a single call, so the connection is then available to reuse.

Connection fields

Property	Type	Required	Default	Description
`type`	string	Yes		`mongodb_native`.
`name`	string	Yes		A label for the saved connection.
`parameters.host`	string	Yes		A hostname, a comma-separated `host:port` list for a replica set, or, with SRV, the cluster's single address.
`parameters.port`	number	No		The port of a single host given without one. MongoDB's default, 27017, applies when it is omitted.
`parameters.srv`	string	No	`"false"`	`"true"` to look up the cluster's members through DNS (`mongodb+srv`), as Atlas expects. The host must then be a single hostname without a port.
`parameters.ssl`	boolean	No		`true` to connect over TLS. Ignored with SRV, which always uses TLS.
`username`	string	No		The MongoDB database user. Required when `password` is sent.
`password`	string	No		That user's password. Required when `username` is sent.
`parameters.auth_source`	string	No	`admin`	The database the user is defined in.

Datastore fields

Property	Type	Required	Default	Description
`name`	string	Yes		The datastore name in Qualytics.
`schema`	string	Yes		The MongoDB database to monitor (shown as Database in the form).
`teams`	array	No	`Public`	The teams that can work with this datastore. Left out, the datastore is assigned to the Public team.
`trigger_sync`	boolean	No	`false`	Ask Qualytics to run the first Sync once the datastore is created, equivalent to ticking Initiate Sync in the form.

No Catalog to send

Connectors such as Athena take a Catalog, the level above the database. MongoDB has no such level, so there is no field to fill in. Qualytics derives one from the connection settings. A request without parameters.host is refused with a message that host is required.

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/datastores" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mongo Orders",
    "connection": {
      "name": "acme_mongodb",
      "type": "mongodb_native",
      "username": "qualytics",
      "password": "<password>",
      "parameters": {
        "host": "cluster0.abcde.mongodb.net",
        "srv": "true",
        "auth_source": "admin"
      }
    },
    "schema": "orders",
    "teams": ["Data Platform"],
    "trigger_sync": true
  }'

Response (200 OK):

{
  "id": 52,
  "name": "Mongo Orders",
  "type": "mongodb_native",
  "store_type": "native",
  "schema": "orders",
  "connected": true
}

A self-hosted replica set

For a replica set, send its members in host and set ssl as your servers need it: "parameters": {"host": "mongo-1.internal:27017,mongo-2.internal:27017", "srv": "false", "ssl": true, "auth_source": "admin"}.

Reuse a MongoDB connection you already created, through this API or the connection form, by passing its connection_id. The host settings and the credentials come from the saved connection, so you supply only the datastore fields.

Reuse it whenever you are adding another database from the same deployment. The password stays in one place, and changing it later is a single edit rather than one per datastore.

Datastore fields

Property	Type	Required	Default	Description
`name`	string	Yes		The datastore name in Qualytics.
`connection_id`	integer	Yes		The ID of the saved MongoDB connection.
`schema`	string	Yes		The MongoDB database to monitor (shown as Database in the form).
`teams`	array	No	`Public`	The teams that can work with this datastore. Left out, the datastore is assigned to the Public team.
`trigger_sync`	boolean	No	`false`	Ask Qualytics to run the first Sync once the datastore is created.

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/datastores" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mongo Support",
    "connection_id": 9,
    "schema": "support",
    "teams": ["Support Ops"],
    "trigger_sync": true
  }'

Response (200 OK):

{
  "id": 53,
  "name": "Mongo Support",
  "type": "mongodb_native",
  "store_type": "native",
  "schema": "support",
  "connected": true
}

Run the first Sync

A datastore is only useful once Sync has discovered its collections and worked out their fields. Send trigger_sync as true to start it with the datastore, or run a Sync yourself once the request returns.

Test a Connection¶

Both tests run as the Member role. The second one also needs the Editor team permission on the datastore.

Before savingAn existing datastore

Validates a create payload without persisting anything. Send the same body you would send to create the datastore.

Endpoint: POST /api/datastores/connection

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/datastores/connection" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mongo Orders",
    "connection": {
      "name": "acme_mongodb",
      "type": "mongodb_native",
      "username": "qualytics",
      "password": "<password>",
      "parameters": {
        "host": "cluster0.abcde.mongodb.net",
        "srv": "true"
      }
    },
    "schema": "orders",
    "teams": ["Data Platform"]
  }'

Response (200 OK):

{
  "connected": true,
  "message": null
}

When the connection cannot be verified, the response is a 400 Bad Request whose message names the failure. A message on a 200 is a warning, not an error.

Re-checks a saved datastore. Because MongoDB is read-only, the check confirms that Qualytics can sign in and read from the deployment.

Endpoint: POST /api/datastores/{id}/connection

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/datastores/52/connection" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200 OK):

{
  "connected": true,
  "message": null
}

A datastore that cannot be reached answers "connected": false with the reason in message.

Get a Datastore¶

Endpoint: GET /api/datastores/{id}

Permission: Member

Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/datastores/52" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200 OK):

{
  "id": 52,
  "name": "Mongo Orders",
  "type": "mongodb_native",
  "store_type": "native",
  "connection_id": 9,
  "schema": "orders",
  "username": "qualytics",
  "parameters": {
    "host": "cluster0.abcde.mongodb.net",
    "srv": "true",
    "auth_source": "admin"
  },
  "has_password": true,
  "connected": true,
  "enrichment_only": false,
  "enrichment_prefix": "_mongo_orders",
  "teams": [{ "name": "Data Platform" }]
}

The password never comes back

has_password reports only whether a password is stored on the connection. The password itself is never returned.

List Datastores¶

Endpoint: GET /api/datastores

Permission: Member

Example request and response

Request:

curl -X GET "https://your-instance.qualytics.io/api/datastores?datastore_type=mongodb_native&sort_name=asc" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200 OK):

{
  "items": [
    { "id": 52, "name": "Mongo Orders", "type": "mongodb_native", "store_type": "native", "connected": true },
    { "id": 53, "name": "Mongo Support", "type": "mongodb_native", "store_type": "native", "connected": true }
  ],
  "total": 2,
  "page": 1,
  "size": 50,
  "pages": 1
}

Query Parameters¶

Parameter	Type	Description
`id`	`list[int]`	Filter by datastore ID.
`name`	string	Filter by exact name.
`search`	string	Partial name match, case-insensitive, or an exact ID.
`datastore_type`	`list[string]`	Filter by connector type. `mongodb_native` returns only MongoDB datastores.
`tag`	`list[string]`	Filter by tag name.
`group`	`list[int]`	Filter by datastore group ID.
`enrichment_only`	boolean	`false` for source datastores (the default). MongoDB datastores are always source datastores.
`sort_name`, `sort_created`, `sort_favorite`, `sort_containers`, `sort_active_anomalies`	string	`asc` or `desc`.

Update a Datastore¶

Changes the datastore's own settings. Every request must include name, connection_id, enrichment_only, and enrichment_prefix, even when they are not changing, so send their current values from Get a Datastore. Most other parameters you leave out stay as they are, with two exceptions:

tags and teams replace the whole list when sent.
enrichment_source_record_limit, enrichment_remediation_strategy, and high_count_rollup_threshold go back to their defaults (10, none, and 10) whenever they are left out. Send their current values on every update to keep them; the example below sends the values a datastore without a linked enrichment destination has.

Endpoint: PUT /api/datastores/{id}

Permission: Member role, with the Editor team permission on the datastore. Changing teams also takes the Manager or Admin role.

What lives on the connection

The host settings, the user, the password, and the Auth Source belong to the connection, not to the datastore. Change them through the connection, and the change reaches every datastore that shares it.

Favorites

Marking a datastore as a favorite has its own endpoint: send {"favorite": true} (or false) to PATCH /api/datastores/{id}/favorite, with the Member role. This update ignores a favorite property.

Property	Type	Required	Description
`name`	string	Yes	The datastore name.
`connection_id`	integer	Yes	The MongoDB connection the datastore reads through.
`enrichment_only`	boolean	Yes	Always `false`. MongoDB datastores are source datastores.
`enrichment_prefix`	string	Yes	The prefix for the tables Qualytics writes to the linked enrichment destination. Send the current value to keep it.
`description`	string	No	Free text shown on the datastore.
`schema`	string	No	The MongoDB database to monitor.
`tags`	`list[string]`	No	Replaces the datastore's tags.
`teams`	`list[string]`	No	Replaces the datastore's teams. Needs the Manager or Admin role.
`enrichment_source_record_limit`, `enrichment_remediation_strategy`, `enrichment_auto_profile`, `high_count_rollup_threshold`	mixed	No	Settings for the enrichment destination linked to this source. `enrichment_auto_profile` was previously named `enrichment_auto_sync`; the old name is deprecated, still accepted, and will be removed in a future release.

Example request and response

Request:

curl -X PUT "https://your-instance.qualytics.io/api/datastores/52" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mongo Orders (EMEA)",
    "connection_id": 9,
    "enrichment_only": false,
    "enrichment_prefix": "_mongo_orders",
    "enrichment_source_record_limit": 10,
    "enrichment_remediation_strategy": "none",
    "high_count_rollup_threshold": 10,
    "schema": "orders_emea",
    "tags": ["mongodb", "orders"],
    "teams": ["Data Platform", "Sales Ops"]
  }'

Response (200 OK):

{
  "id": 52,
  "name": "Mongo Orders (EMEA)",
  "type": "mongodb_native",
  "store_type": "native",
  "connection_id": 9,
  "schema": "orders_emea",
  "global_tags": [{ "name": "mongodb" }, { "name": "orders" }],
  "teams": [{ "name": "Data Platform" }, { "name": "Sales Ops" }]
}

Delete a Datastore¶

Endpoint: DELETE /api/datastores/{id}

Permission: Admin

Example request

curl -X DELETE "https://your-instance.qualytics.io/api/datastores/52" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: 204 No Content

Warning

Deletion permanently removes the datastore's containers, checks, anomalies, and operation history from Qualytics. Nothing is removed from MongoDB. Data already written to an enrichment destination stays there and must be removed separately. The connection stays, and so does every other datastore that uses it.

Create Several Datastores at Once¶

A MongoDB deployment usually holds more than one database. The bulk endpoints take a list of databases and create one datastore per entry, sharing the same connection and settings.

Permission: Manager, plus the Editor team permission on at least one of the assigned teams (the Public team when teams is left out). Admins are exempt.

New ConnectionExisting Connection

Endpoint: POST /api/connections/datastores/bulk

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/connections/datastores/bulk" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connection": {
      "name": "acme_mongodb",
      "type": "mongodb_native",
      "username": "qualytics",
      "password": "<password>",
      "parameters": {
        "host": "cluster0.abcde.mongodb.net",
        "srv": "true",
        "auth_source": "admin"
      }
    },
    "schemas": ["sales", "support", "billing"],
    "name_template": "mongo_{{schema}}",
    "teams": ["Data Platform"],
    "trigger_sync": true
  }'

Response (200 OK):

{
  "created": [121, 122, 123],
  "errors": [],
  "connection_id": 14
}

Endpoint: POST /api/connections/{connection_id}/datastores/bulk

Example request and response

Request:

curl -X POST "https://your-instance.qualytics.io/api/connections/9/datastores/bulk" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schemas": ["marketing", "logistics"],
    "name_template": "mongo_{{schema}}",
    "teams": ["Data Platform"],
    "trigger_sync": true
  }'

Response (200 OK):

{
  "created": [130, 131],
  "errors": [],
  "connection_id": 9
}

Property	Type	Required	Description
`connection`	object	New connection only	The same connection object as in Create a MongoDB Datastore.
`schemas`	`list[string]`	Yes	The MongoDB databases to create datastores for, one datastore each.
`name_template`	string	No	Naming pattern with `{{schema}}` standing for the database name. Defaults to the connection name followed by the database.
`teams`	`list[string]`	No	Teams assigned to every created datastore.
`tags`	`list[string]`	No	Tags applied to every created datastore.
`group_id`	integer	No	An existing datastore group to place them in.
`description`	string	No	Description applied to every created datastore.
`trigger_sync`	boolean	No	Run the first Sync on each datastore as it is created.

Note

There is no database field to send: MongoDB has no level above the database, so schemas is the whole address. Creation is not atomic. Databases that succeed are created even if others fail, and the response lists both the created IDs and, per failed database, the reason. It also returns connection_id, the connection the datastores were created on. To retry the failed databases, send them to that connection through the Existing Connection endpoint. When no datastore was created, a New Connection request still returns connection_id if the connection was saved anyway, so retry on it the same way. When connection_id is null after a New Connection request, the connection was not saved, so resend the whole request. After an Existing Connection request, connection_id is null when no datastore was created; retry on the same connection ID.