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.

type

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"

`POST /api/connections`

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

name

string

required

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

type

string

required

Connector type identifier.

config

object

required

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

credentialId

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.

config

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.

name

string

New display name.

config

object

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

credentialId

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.

type

string

required

Connector type.

config

object

required

Connection configuration to test.

credentialId

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.

schema

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.

schema

string

Schema name.

table

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.

schema

string

Schema or namespace.

table

string

Table or object name.

limit

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.

prefix

string

Path prefix inside the bucket or container.

delimiter

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.

path

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.

connectionId

string

required

Connection to introspect.

schema

string

Optional schema filter.

`GET /api/connections/columns`

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

connectionId

string

required

Connection to introspect.

schema

string

Schema name.

table

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).

connectionId

string

required

Target connection.

sql

string

required

SQL to execute (typically SELECT only).

limit

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.

connectionId

string

required

Databricks connection ID.

catalog

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

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

Overview

Data platform

Orchestration

Integration

Governance

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

​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