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

# Connect an Internal System

> Turn an internal HTTP service or a read-only database into governed tools without writing code

The Connector Builder describes an internal system as data, and Danube compiles it into a private, organization-scoped service whose tools behave like any other: searchable by your agents, credential-injected at call time, covered by [policies](/organizations/policies) and the [audit log](/organizations/audit-log).

Two kinds of connector exist.

## HTTP connector

For an internal HTTP service with no published OpenAPI document. You describe the base URL, how it authenticates, and each endpoint you want exposed as a tool.

```json theme={null}
{
  "name": "Billing Service",
  "description": "Internal invoicing service",
  "base_url": "https://billing.internal.example.com",
  "auth": {"type": "api_key", "location": "header", "name": "X-API-Key"},
  "endpoints": [
    {
      "name": "Get Invoice",
      "description": "Fetch one invoice by id",
      "method": "GET",
      "path": "/v1/invoices/{id}",
      "parameters": [
        {"name": "id", "location": "path", "type": "string", "required": true}
      ]
    }
  ],
  "visibility": "private"
}
```

| Field                                | Notes                                                                                                                                                                                                            |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auth.type`                          | `none`, `api_key` (header or query, with `name`), `bearer`, or `basic`. Compiled to the same credential-injection path every other service uses; the secret itself is stored as a credential, never in the spec. |
| `endpoints[].path`                   | Appended to `base_url`; `{placeholders}` become path parameters.                                                                                                                                                 |
| `endpoints[].parameters[].location`  | `query`, `path`, `header`, or `body`.                                                                                                                                                                            |
| `endpoints[].output_schema`          | Optional; the dry run checks sample responses against it.                                                                                                                                                        |
| `environments`, `active_environment` | Optional map of environment name to base URL, for promoting a connector from staging to production without editing endpoints.                                                                                    |
| `visibility`                         | `private` by default (your organization only).                                                                                                                                                                   |

### Flow

<Steps>
  <Step title="Open the builder">
    Go to [Dashboard > Tools > Connect internal system](https://danubeai.com/dashboard/tools/connector).
  </Step>

  <Step title="Infer or write the spec">
    If the service publishes an OpenAPI document, point the builder at the base URL and it proposes a spec. Otherwise list the endpoints to probe; the builder calls each one with your sample parameters and proposes parameters and output shapes from the responses. Nothing is stored at this step; you review and edit the proposal.
  </Step>

  <Step title="Validate and test">
    Validation checks the spec shape and reports the number of tools it will create. Test makes one real call to confirm reachability and authentication.
  </Step>

  <Step title="Dry run">
    The dry run executes each endpoint with sample parameters and reports pass, fail, or skip per check, including output-schema mismatches.
  </Step>

  <Step title="Create">
    The connector becomes a private service in your organization. Its tools are immediately callable by your agents.
  </Step>
</Steps>

## Database connector

For read-only questions against Postgres or MySQL. Each query becomes a tool; parameters are typed and bound, never interpolated.

```json theme={null}
{
  "name": "Analytics DB",
  "db_type": "postgres",
  "connection_ref": "ANALYTICS_DB_DSN",
  "queries": [
    {
      "name": "Active customers",
      "description": "Customers with activity in the last N days",
      "sql": "SELECT id, name, last_seen FROM customers WHERE last_seen > now() - (:days || ' days')::interval LIMIT 100",
      "parameters": [{"name": "days", "type": "integer", "required": true}]
    }
  ]
}
```

* **Danube never holds the connection string.** `connection_ref` names an environment variable resolved where the query runs. With the [data plane](/organizations/data-plane) that is inside your network.
* **Read-only, enforced three ways.** The SQL is validated as a single `SELECT`, the connection is opened read-only, and results are capped at 1,000 rows.
* **Introspection** lists tables and columns so the builder can propose a starting set of queries.

## Endpoints

| Method | Path                                                                             | Purpose                               |
| ------ | -------------------------------------------------------------------------------- | ------------------------------------- |
| `POST` | `/v1/connectors/validate`                                                        | Check an HTTP spec                    |
| `POST` | `/v1/connectors/test`                                                            | One live call                         |
| `POST` | `/v1/connectors/infer`                                                           | Propose a spec from OpenAPI or probes |
| `POST` | `/v1/connectors/dry-run`                                                         | Execute every endpoint with samples   |
| `POST` | `/v1/connectors`                                                                 | Create the service and tools          |
| `POST` | `/v1/connectors/database/validate`, `/test`, `/introspect`, `/infer`, `/dry-run` | The same flow for a database          |
| `POST` | `/v1/connectors/database`                                                        | Create the database service           |