> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devset.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Connectors API: Configure Broker and Database Connections

> Register, list, and remove Kafka, RabbitMQ, and MongoDB connectors so Devset can route workflow executions and queries to your local infrastructure.

The Connectors API is how you tell Devset where your brokers and databases live. You register a named connector once, and then reference it by name in workflows, messages, and queries. Devset supports Kafka and RabbitMQ broker connectors, MongoDB database connectors, and a set of MongoDB query endpoints for direct data access. All endpoints are relative to `http://localhost:8082`.

***

## POST /connectors/configurations

Create a broker connector. Devset stores the connection details and makes the connector available by name across all other APIs.

<Tabs>
  <Tab title="Kafka">
    <ParamField body="type" type="string" required>
      Must be `"kafka"`.
    </ParamField>

    <ParamField body="name" type="string" required>
      A unique name for this connector, such as `local-kafka` or `staging-kafka`.
    </ParamField>

    <ParamField body="bootstrapServers" type="string" required>
      Comma-separated list of Kafka bootstrap server addresses in `host:port` format.
    </ParamField>

    <ParamField body="username" type="string">
      Optional authentication username.
    </ParamField>

    <ParamField body="password" type="string">
      Optional authentication password.
    </ParamField>

    **Request example**

    ```json theme={null}
    {
      "type": "kafka",
      "name": "local-kafka",
      "bootstrapServers": "localhost:9092"
    }
    ```
  </Tab>

  <Tab title="RabbitMQ">
    <ParamField body="type" type="string" required>
      Must be `"rabbit"`.
    </ParamField>

    <ParamField body="name" type="string" required>
      A unique name for this connector, such as `local-rabbit` or `staging-rabbit`.
    </ParamField>

    <ParamField body="host" type="string" required>
      Hostname or IP address of the RabbitMQ broker.
    </ParamField>

    <ParamField body="port" type="integer" required>
      AMQP port. Typically `5672`.
    </ParamField>

    <ParamField body="virtualHost" type="string" required>
      The RabbitMQ virtual host. Use `"/"` for the default virtual host.
    </ParamField>

    <ParamField body="username" type="string">
      Optional authentication username.
    </ParamField>

    <ParamField body="password" type="string">
      Optional authentication password.
    </ParamField>

    **Request example**

    ```json theme={null}
    {
      "type": "rabbit",
      "name": "local-rabbit",
      "host": "localhost",
      "port": 5672,
      "virtualHost": "/",
      "username": "guest",
      "password": "guest"
    }
    ```
  </Tab>
</Tabs>

**Response — 200 OK**

This endpoint returns no response body.

***

## GET /connectors/configurations

List all saved broker connectors and their connection status. Passwords are not returned in the response.

**Response — 200 OK**

```json theme={null}
[
  {
    "type": "kafka",
    "name": "local-kafka",
    "endpoint": "localhost:9092",
    "producerConnected": true,
    "consumerConnected": true,
    "authenticated": false
  },
  {
    "type": "rabbit",
    "name": "local-rabbit",
    "endpoint": "localhost:5672",
    "producerConnected": true,
    "consumerConnected": false,
    "authenticated": true
  }
]
```

<ResponseField name="type" type="string">
  The broker type: `kafka` or `rabbit`.
</ResponseField>

<ResponseField name="name" type="string">
  The connector name.
</ResponseField>

<ResponseField name="endpoint" type="string">
  The connection endpoint. For Kafka, the bootstrap server address. For RabbitMQ, `host:port`.
</ResponseField>

<ResponseField name="producerConnected" type="boolean">
  `true` if the producer side of the connection is active.
</ResponseField>

<ResponseField name="consumerConnected" type="boolean">
  `true` if the consumer side of the connection is active.
</ResponseField>

<ResponseField name="authenticated" type="boolean">
  `true` if credentials were provided for this connector.
</ResponseField>

***

## DELETE /connectors/configurations/{type}/{name}

Delete a broker connector by type and name.

**Path parameters**

<ParamField path="type" type="string" required>
  The broker type: `kafka` or `rabbit`.
</ParamField>

<ParamField path="name" type="string" required>
  The name of the connector to delete.
</ParamField>

**Request example**

```
DELETE /connectors/configurations/kafka/local-kafka
```

**Response — 200 OK**

This endpoint returns no response body.

<Warning>
  Deleting a connector that is referenced by saved workflows will cause those workflows to fail on the next execution. Update your workflows to use a different connector before deleting.
</Warning>

***

## POST /db/connectors/configurations

Create a database connector. Currently, Devset supports MongoDB.

<ParamField body="type" type="string" required>
  The database type. Currently only `"mongodb"` is supported.
</ParamField>

<ParamField body="name" type="string" required>
  A unique name for this connector, such as `local-mongo` or `staging-mongo`.
</ParamField>

<ParamField body="connectionString" type="string" required>
  A valid MongoDB connection URI, such as `mongodb://localhost:27017` or `mongodb+srv://user:pass@cluster.example.net`.
</ParamField>

<ParamField body="database" type="string" required>
  The default database to use when a query does not specify one explicitly.
</ParamField>

<ParamField body="username" type="string">
  Optional authentication username.
</ParamField>

<ParamField body="password" type="string">
  Optional authentication password.
</ParamField>

**Request example**

```json theme={null}
{
  "type": "mongodb",
  "name": "local-mongo",
  "connectionString": "mongodb://localhost:27017",
  "database": "mydb"
}
```

**Response — 200 OK**

This endpoint returns no response body.

***

## GET /db/connectors/configurations

List all saved database connectors and their connection status. Connection string credentials are not returned in the response.

**Response — 200 OK**

```json theme={null}
[
  {
    "type": "mongodb",
    "name": "local-mongo",
    "connectionString": "mongodb://localhost:27017",
    "connected": true,
    "authenticated": false
  }
]
```

<ResponseField name="type" type="string">
  The database type. Currently always `"mongodb"`.
</ResponseField>

<ResponseField name="name" type="string">
  The connector name.
</ResponseField>

<ResponseField name="connectionString" type="string">
  The connection URI used by this connector.
</ResponseField>

<ResponseField name="connected" type="boolean">
  `true` if the client is currently connected to the database.
</ResponseField>

<ResponseField name="authenticated" type="boolean">
  `true` if credentials were provided for this connector.
</ResponseField>

***

## DELETE /db/connectors/configurations/{type}/{name}

Delete a database connector by type and name.

**Path parameters**

<ParamField path="type" type="string" required>
  The database type: `mongodb`.
</ParamField>

<ParamField path="name" type="string" required>
  The name of the connector to delete.
</ParamField>

**Request example**

```
DELETE /db/connectors/configurations/mongodb/local-mongo
```

**Response — 200 OK**

This endpoint returns no response body.

***

## POST /mongodb/query

Run a MongoDB `find` query against a collection. Devset connects using the named connector and returns matching documents along with the total count.

<ParamField body="connectionName" type="string" required>
  The name of the MongoDB connector to use.
</ParamField>

<ParamField body="database" type="string" required>
  The database containing the target collection.
</ParamField>

<ParamField body="collection" type="string" required>
  The collection to query.
</ParamField>

<ParamField body="filter" type="string" required>
  A MongoDB query filter document serialized as a JSON string. Use `"{}"` to return all documents.
</ParamField>

<ParamField body="projection" type="string">
  A MongoDB projection document serialized as a JSON string, specifying which fields to include (`1`) or exclude (`0`). Omit to return all fields.
</ParamField>

<ParamField body="limit" type="integer">
  Maximum number of documents to return. Use `0` or omit for no limit.
</ParamField>

**Request example**

```json theme={null}
{
  "connectionName": "local-mongo",
  "database": "mydb",
  "collection": "orders",
  "filter": "{\"status\": \"PENDING\"}",
  "projection": "{\"id\": 1, \"amount\": 1}",
  "limit": 100
}
```

**Response — 200 OK**

```json theme={null}
{
  "documents": [
    { "id": "order-123", "amount": 42 },
    { "id": "order-124", "amount": 75 }
  ],
  "count": 2
}
```

<ResponseField name="documents" type="array">
  Array of matching documents, shaped by your projection. The `_id` field is included by default unless explicitly excluded.
</ResponseField>

<ResponseField name="count" type="integer">
  Total number of documents returned.
</ResponseField>

***

## POST /mongodb/schema

Discover the field structure of a collection by sampling one document. Devset inspects the document and returns a list of fields with their paths, inferred BSON types, and any nested children for embedded documents. Use this to understand collection shape before writing a query or workflow stage.

<ParamField body="connectionName" type="string" required>
  The name of the MongoDB connector to use.
</ParamField>

<ParamField body="database" type="string" required>
  The database containing the target collection.
</ParamField>

<ParamField body="collection" type="string" required>
  The collection to sample.
</ParamField>

**Request example**

```json theme={null}
{
  "connectionName": "local-mongo",
  "database": "mydb",
  "collection": "orders"
}
```

**Response — 200 OK**

```json theme={null}
[
  { "path": "_id", "type": "ObjectId", "children": [] },
  { "path": "id", "type": "String", "children": [] },
  { "path": "amount", "type": "Integer", "children": [] },
  { "path": "status", "type": "String", "children": [] },
  {
    "path": "address",
    "type": "Document",
    "children": [
      { "path": "address.city", "type": "String", "children": [] },
      { "path": "address.zip", "type": "String", "children": [] }
    ]
  }
]
```

The response is a JSON array of field descriptors.

<ResponseField name="path" type="string">
  Dot-notation path of the field (e.g. `address.city`).
</ResponseField>

<ResponseField name="type" type="string">
  Inferred BSON type name (e.g. `String`, `Integer`, `Document`, `Array`).
</ResponseField>

<ResponseField name="children" type="array">
  Nested field descriptors when `type` is `Document`. Empty for all other types.
</ResponseField>

<Note>
  Schema discovery samples a single document. If your collection has documents with varying shapes, the result may not reflect all possible fields. Run queries against several documents to build a complete picture.
</Note>

***

## GET /mongodb/{connectionName}/databases

List all databases accessible with the given MongoDB connector.

**Path parameters**

<ParamField path="connectionName" type="string" required>
  The name of the MongoDB connector to query.
</ParamField>

**Request example**

```
GET /mongodb/local-mongo/databases
```

**Response — 200 OK**

```json theme={null}
["mydb", "analytics", "admin", "local"]
```

The response is a JSON array of database name strings.

***

## GET /mongodb/{connectionName}/{database}/collections

List all collections in a specific database.

**Path parameters**

<ParamField path="connectionName" type="string" required>
  The name of the MongoDB connector to query.
</ParamField>

<ParamField path="database" type="string" required>
  The database whose collections you want to list.
</ParamField>

**Request example**

```
GET /mongodb/local-mongo/mydb/collections
```

**Response — 200 OK**

```json theme={null}
["orders", "payments", "users", "notifications"]
```

The response is a JSON array of collection name strings.