Data connections

Manage the data connections configured in the workspace — the databases and files agents query — and read the semantic views each one exposes. To attach a connection's data to an agent, build a semantic data model on top of it.

All paths are relative to the base URL and require an Authorization: Bearer YOUR_API_KEY header.

The data connection object

PublicDataConnection. Each connection is typed by its source. Supported engines: postgres, redshift, snowflake, mysql, mssql, oracle, timescaledb, pgvector, sqlite, duckdb, bigquery, and databricks.

Numeric configuration fields are returned as JSON numbers — e.g. port comes back as 5432.0, not 5432. Parse them as numbers, not strict integers.

Credentials are never returned

Every endpoint that returns a PublicDataConnection — list, get, create, and update — strips stored credentials from configuration at every level of nesting. These fields are removed:

access_token, api_key, app_token, client_secret, password, private_key_passphrase, private_key_path, private_key_pem, service_account_keys, ssl_cert, ssl_key, token

A Postgres connection created with a password therefore reads back without one:

{
  "id": "55408aa4-1457-487c-a2fb-f4a7ba09c1d4",
  "name": "Invoices DB",
  "description": "AP invoices",
  "engine": "postgres",
  "configuration": {
    "host": "db.internal",
    "port": 5432.0,
    "database": "invoices",
    "user": "readonly",
    "schema": "public",
    "sslmode": "require"
  },
  "tags": [],
  "external_id": null,
  "preinstalled": false,
  "created_at": "2026-02-06T18:23:04.306040Z",
  "updated_at": "2026-02-06T18:23:04.306040Z"
}

If a connection's configuration isn't in a shape the platform recognizes, it's omitted from the response entirely rather than returned unfiltered.

List data connections

GET /data-connections

Returns a PaginatedResponse of connections.

Get a data connection

GET /data-connections/{connection_id}

Returns a single PublicDataConnection.

Create a data connection

POST /data-connections

Creates a connection. The body is typed by engine, with an engine-specific configuration. The platform verifies the connection before saving — if it can't connect, you get 400 and nothing is written.

Body (PostgreSQL example)

curl -X POST 'https://{your-deployment-host}/api/v2/data-connections' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Invoices DB",
    "description": "AP invoices",
    "engine": "postgres",
    "configuration": {
      "host": "db.internal", "port": 5432, "database": "invoices",
      "user": "readonly", "password": "…", "schema": "public", "sslmode": "require"
    }
  }'

Returns the created PublicDataConnection.

Update a data connection

PUT /data-connections/{connection_id}

Updates a connection. Like create, the connection is verified before saving (400 on failure). Returns the updated PublicDataConnection.

Delete a data connection

DELETE /data-connections/{connection_id}

Returns 204 No Content.

List semantic views

GET /data-connections/{connection_id}/semantic-views

Lists the semantic views available in a connection — the tables/views a semantic data model can build on.

Response — SemanticViewsListResponse

{
  "semantic_views": [
    { "name": "string", "database": "string", "schema": "string", "created_on": "string", "description": "string" }
  ]
}