Connections

Connections represent credentials and configuration for databases, warehouses, APIs, and cloud storage. All endpoints below require authentication unless noted. Base URL: https://api.planasonix.com
Auth: Authorization: Bearer plus your API key or JWT access token.

List and CRUD

`GET /api/connections`

List connections in your workspace.

string

Filter by connector type (for example postgres, snowflake, s3).

string

Case-insensitive match on connection name.

Show Example request and response

curl -s https://api.planasonix.com/api/connections?type=snowflake \
  -H "Authorization: Bearer plnx_live_xxxxxxxx"

{
  "data": [
    {
      "id": "conn_01hqxyz",
      "name": "prod_analytics_wh",
      "type": "snowflake",
      "credentialId": "cred_01hqabc",
      "createdAt": "2025-03-01T10:00:00Z",
      "updatedAt": "2025-03-27T08:15:00Z"
    },
    {
      "id": "conn_02hqdef",
      "name": "marketing_s3_lake",
      "type": "s3",
      "credentialId": "cred_02hqghi",
      "createdAt": "2025-02-14T14:30:00Z",
      "updatedAt": "2025-03-20T11:00:00Z"
    }
  ],
  "meta": { "total": 2 }
}

`POST /api/connections`

Create a connection. Secret values belong in a credential; config holds non-secret settings.

string

required

Human-readable name unique within the project or workspace (per your policy).

string

required

Connector type identifier.

object

required

Connector-specific configuration (host, database, bucket, region, and so on).

string

Existing credential that stores secrets for this connection.

Show Example request and response

curl -X POST https://api.planasonix.com/api/connections \
  -H "Authorization: Bearer plnx_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "staging_postgres",
    "type": "postgres",
    "credentialId": "cred_01hqabc",
    "config": {
      "host": "db.internal.acme.com",
      "port": 5432,
      "database": "staging",
      "sslMode": "require"
    }
  }'

{
  "id": "conn_03hqjkl",
  "name": "staging_postgres",
  "type": "postgres",
  "credentialId": "cred_01hqabc",
  "config": {
    "host": "db.internal.acme.com",
    "port": 5432,
    "database": "staging",
    "sslMode": "require"
  },
  "createdAt": "2025-03-27T12:00:00Z"
}

`GET /api/connections/{id}`

Return one connection, including metadata and non-secret config.

string

required

Connection identifier.

string

Connection ID.

object

Resolved configuration; secrets are never returned in plain text.

Show Example response

{
  "id": "conn_01hqxyz",
  "name": "prod_analytics_wh",
  "type": "snowflake",
  "credentialId": "cred_01hqabc",
  "config": {
    "account": "acme.us-east-1",
    "warehouse": "ETL_WH",
    "database": "ANALYTICS",
    "schema": "PUBLIC"
  },
  "updatedAt": "2025-03-27T08:15:00Z"
}

`PUT /api/connections/{id}`

Update name, config, or linked credentialId.

string

required

Connection identifier.

string

New display name.

object

Replacement or merged config (behavior depends on connector; send full object when in doubt).

string

New credential to attach.

`DELETE /api/connections/{id}`

Remove a connection. Fails if active pipelines still reference it (unless your API version allows force delete).

string

required

Connection identifier.

Show Example response

{
  "ok": true,
  "id": "conn_03hqjkl",
  "deletedAt": "2025-03-27T12:30:00Z"
}

Test and introspection

`POST /api/connections/test`

Validate settings without persisting a connection.

string

required

Connector type.

object

required

Connection configuration to test.

string

Optional credential for secret resolution.

Show Example response

{
  "ok": true,
  "latencyMs": 142,
  "serverVersion": "PostgreSQL 15.4",
  "message": "Connection successful."
}

`GET /api/connections/{id}/tables`

List tables available through the connection.

string

required

Connection identifier.

string

Limit to a schema (when applicable).

Show Example response

{
  "connectionId": "conn_01hqxyz",
  "schema": "analytics",
  "tables": [
    { "name": "orders", "type": "TABLE" },
    { "name": "order_items", "type": "TABLE" },
    { "name": "dim_customers", "type": "VIEW" }
  ]
}

`GET /api/connections/{id}/columns`

Return columns for a specific table.

string

required

Connection identifier.

string

Schema name.

string

required

Table name.

Show Example response

{
  "connectionId": "conn_01hqxyz",
  "schema": "analytics",
  "table": "orders",
  "columns": [
    { "name": "order_id", "type": "BIGINT", "nullable": false },
    { "name": "customer_id", "type": "UUID", "nullable": true },
    { "name": "amount_cents", "type": "INTEGER", "nullable": false },
    { "name": "ordered_at", "type": "TIMESTAMPTZ", "nullable": false }
  ]
}

`GET /api/connections/{id}/schemas`

List schemas (databases that support multiple schemas).

string

required

Connection identifier.

`GET /api/connections/{id}/catalogs`

List catalogs (Iceberg, Unity Catalog, Hive-metastore style sources).

string

required

Connection identifier.

`GET /api/connections/{id}/preview`

Sample rows from a table or object.

string

required

Connection identifier.

string

Schema or namespace.

string

Table or object name.

integer

Max rows (default bounded by server policy, often 100–1000).

Show Example response

{
  "columns": ["order_id", "customer_id", "amount_cents"],
  "rows": [
    [1001, "c7f2b3a1-4d5e-6f70-8192-abcdef012345", 12999],
    [1002, null, 4590]
  ],
  "truncated": true
}

`GET /api/connections/{id}/files`

Browse objects in cloud storage connections.

string

required

Connection identifier.

string

Path prefix inside the bucket or container.

string

Directory delimiter (often /).

Show Example response

{
  "prefix": "raw/events/",
  "objects": [
    { "key": "raw/events/2025/03/27/part-000.parquet", "size": 8388608, "lastModified": "2025-03-27T06:00:00Z" },
    { "key": "raw/events/2025/03/27/_SUCCESS", "size": 0, "lastModified": "2025-03-27T06:00:01Z" }
  ],
  "commonPrefixes": ["raw/events/2025/03/28/"]
}

`GET /api/connections/{id}/cloud-schema`

Infer or load schema for files in cloud storage (for example Parquet/CSV headers).

string

required

Connection identifier.

string

required

Object key or path to inspect.

Query-parameter variants

`GET /api/connections/tables`

Same as listing tables, but connectionId is passed as a query parameter instead of a path segment.

string

required

Connection to introspect.

string

Optional schema filter.

`GET /api/connections/columns`

Column metadata with connectionId (and table identifiers) in the query string.

string

required

Connection to introspect.

string

Schema name.

string

required

Table name.

`POST /api/connections/test-query`

Run a read-only SQL statement to validate syntax and permissions (subject to row/timeout limits).

string

required

Target connection.

string

required

SQL to execute (typically SELECT only).

integer

Row cap for the result set.

Show Example response

{
  "ok": true,
  "columns": ["region", "revenue_usd"],
  "rows": [
    ["US-West", 128400.55],
    ["EU-Central", 90211.12]
  ],
  "stats": { "rowsScanned": 450000, "executionMs": 820 }
}

`POST /api/connections/databricks/discover`

Discover catalogs and schemas for Databricks-backed connections.

string

required

Databricks connection ID.

string

When set, list schemas inside this catalog only.

Show Example response

{
  "connectionId": "conn_db_01",
  "catalogs": [
    {
      "name": "main",
      "schemas": ["default", "analytics", "sandbox"]
    },
    {
      "name": "hive_metastore",
      "schemas": ["legacy"]
    }
  ]
}

Credentials

Store secrets separately from connection config.

Overview

Data platform

Orchestration

Integration

Governance

Iceberg Catalog

Platform

List and CRUD

`GET /api/connections`

`POST /api/connections`

`GET /api/connections/{id}`

`PUT /api/connections/{id}`

`DELETE /api/connections/{id}`

Test and introspection

`POST /api/connections/test`

`GET /api/connections/{id}/tables`

`GET /api/connections/{id}/columns`

`GET /api/connections/{id}/schemas`

`GET /api/connections/{id}/catalogs`

`GET /api/connections/{id}/preview`

`GET /api/connections/{id}/files`

`GET /api/connections/{id}/cloud-schema`

Query-parameter variants

`GET /api/connections/tables`

`GET /api/connections/columns`

`POST /api/connections/test-query`

`POST /api/connections/databricks/discover`

Credentials

​List and CRUD

​GET /api/connections

​POST /api/connections

​GET /api/connections/{id}

​PUT /api/connections/{id}

​DELETE /api/connections/{id}

​Test and introspection

​POST /api/connections/test

​GET /api/connections/{id}/tables

​GET /api/connections/{id}/columns

​GET /api/connections/{id}/schemas

​GET /api/connections/{id}/catalogs

​GET /api/connections/{id}/preview

​GET /api/connections/{id}/files

​GET /api/connections/{id}/cloud-schema

​Query-parameter variants

​GET /api/connections/tables

​GET /api/connections/columns

​POST /api/connections/test-query

​POST /api/connections/databricks/discover

​Related

Credentials

List and CRUD

`GET /api/connections`

`POST /api/connections`

`GET /api/connections/{id}`

`PUT /api/connections/{id}`

`DELETE /api/connections/{id}`

Test and introspection

`POST /api/connections/test`

`GET /api/connections/{id}/tables`

`GET /api/connections/{id}/columns`

`GET /api/connections/{id}/schemas`

`GET /api/connections/{id}/catalogs`

`GET /api/connections/{id}/preview`

`GET /api/connections/{id}/files`

`GET /api/connections/{id}/cloud-schema`

Query-parameter variants

`GET /api/connections/tables`

`GET /api/connections/columns`

`POST /api/connections/test-query`

`POST /api/connections/databricks/discover`

Related