Connections

Connections store encrypted credentials to your source databases.

Create Connection

POST /v1/providers/{provider}/connections

Path Parameters:

Parameter	Description
provider	Database provider: snowflake or postgresql

Request Body:

Field	Type	Required	Description
name	string	Yes	Connection name (1-100 chars)
mode	string	Yes	managed or platform
credentials	object	Yes	Provider-specific credentials

Snowflake Credentials

Field	Type	Required	Description
auth_method	string	Yes	password or key_pair
account	string	Yes	Snowflake account identifier
user	string	Yes	Username
password	string	Conditional	Required for password auth
private_key	string	Conditional	PEM-encoded key for key_pair auth
warehouse	string	No	Warehouse name
database	string	No	Database name
schema	string	No	Schema name (default: PUBLIC)
role	string	No	Role name

PostgreSQL Credentials

Field	Type	Required	Description
host	string	Yes	Database hostname
port	integer	No	Port (default: 5432)
database	string	Yes	Database name
user	string	Yes	Username
password	string	Yes	Password
ssl_mode	string	No	SSL mode (require, verify-ca, etc.)

Example:

curl -X POST https://api.embedd.to/v1/providers/snowflake/connections \
  -H "Authorization: Bearer sk_your_key" \
  -H "X-Environment-Id: env_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "analytics-warehouse",
    "mode": "managed",
    "credentials": {
      "auth_method": "password",
      "account": "myorg-account",
      "user": "EMBEDD_USER",
      "password": "secure_password",
      "warehouse": "COMPUTE_WH"
    }
  }'

Response (201):

{
  "id": "conn_abc123",
  "org_id": "org_xyz",
  "environment_id": "env_abc123",
  "name": "analytics-warehouse",
  "provider": "snowflake",
  "mode": "managed",
  "status": "pending",
  "last_tested_at": null,
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z"
}

List Connections

GET /v1/connections

Supports cursor-based pagination with limit and cursor query parameters.

Get Connection

GET /v1/connections/{connection_id}

Update Connection

PUT /v1/connections/{connection_id}

Request Body:

Field	Type	Required	Description
name	string	No	Updated name
credentials	object	No	Updated credentials

Delete Connection

DELETE /v1/connections/{connection_id}

Fails with 409 Conflict if vector tables are using the connection.

Response: 204 No Content

Test Connection

POST /v1/connections/{connection_id}/test

Tests connectivity to the database using stored credentials.

Response (200):

{
  "status": "connected",
  "details": {"latency_ms": 245}
}

On failure:

{
  "status": "failed",
  "details": {"error": "Connection refused"}
}