Connection API
This document outlines the API endpoints and structures for creating new connections, which can be either project-scoped or global-scoped.
Create Connection
You can create a new connection using a POST
request.
Endpoints
Project-scoped:
POST: https://{telmai_endpoint}/api/backend/{tenant}/configuration/projects/{projectId}/connections
Global-scoped:
POST: https://{telmai_endpoint}/api/backend/{tenant}/configuration/connections
Request Body
The request body defines the properties of the new connection.
{
"name": "MyRedshift",
"type": "REDSHIFT",
"credential": {
"type": "SIMPLE",
"payload": {
"username": "test",
"password": "test"
}
},
"payload": {
"endpoint_prefix": "tlm-redshift02"
}
}
Fields:
name
(string): A user-defined name for the connection.type
(string): The type of the connection (e.g.,REDSHIFT
,GCS
,AZURE
,BIGQUERY
,DELTALAKE
,GENERIC_JDBC
,HIVE_ICEBERG
,SNOWFLAKE
). This determines the structure of thepayload
field.credential
(object): Contains the authentication details for the connection.type
(string): The type of credential (e.g.,SIMPLE
,GCP
,AWS
,TOKEN
,AZURE_SAS
,GENERIC_MAP
).payload
(object): The specific credential details, which vary based on thecredential.type
. Refer to the Credentials documentation for detailedpayload
formats.
payload
(object): The connection-specific configuration. The format of this object depends on thetype
of the connection. Refer to the "API Payload Formats by Type" table for examples.
Response
The response confirms the creation of the connection and provides its details, including a unique id
.
{
"id": 3111,
"project_id": 0,
"name": "MyRedshift",
"scope": "PROJECT", // Can be "GLOBAL" for global-scoped connections
"created_by": "[email protected]",
"created_at": "2025-05-23T11:03:01.000Z", // ISO format in UTC
"type": "REDSHIFT",
"payload": {
"endpoint_prefix": "tlm-redshift02"
},
"db_type": "HANA101"
}
Fields:
id
(integer): The unique identifier of the newly created connection.project_id
(integer): The ID of the project if it's a project-scoped connection; otherwise, it might be0
or null for global-scoped.name
(string): The name of the connection.scope
(string): Indicates whether the connection isPROJECT
-scoped orGLOBAL
-scoped.created_by
(string): The email of the user who created the connection.created_at
(string): The timestamp when the connection was created in ISO format (UTC).type
(string): The type of the connection.payload
(object): The connection-specific configuration as provided in the request.db_type
(string): The database type, derived from the connection.
Correspondence between Connection and Credential Types
The credential.type
you provide in the request body should correspond to the type
of the connection you are creating:
GCS
->GCP
S3
->AWS
BIGQUERY
->GCP
AZURE
->AZURE_SAS
SNOWFLAKE
->SIMPLE
DELTALAKE
->TOKEN
REDSHIFT
->SIMPLE
GENERIC_JDBC
->GENERIC_MAP
HIVE_ICEBERG
-> depends onlocation_type
within itspayload
(e.g.,GCP
,AWS
,AZURE_SAS
).
Payload
Payload object describes the connection detail and is dependent on connection type
REDSHIFT
SIMPLE
{"endpoint_prefix": "tlm-redshift02"}
GCS
GCP
{"bucket": "<bucket_name>"}
S3
AWS
{"bucket": "<bucket_name>"}
AZURE
AZURE_SAS
{"storage_account": "test_acc", "bucket": "<bucket_name>"}
BIGQUERY
GCP
{"project": "test_project"}
DELTALAKE
TOKEN
{"host": "test.db23.databricks.com", "port": "443", "httppath": "some/path"}
GENERIC_JDBC
GENERIC_MAP
{"db_type": "HANA10", "db_or_schema": "test_db", "connection_properties": {"prop1": "value1", "prop2": "value2"}}
connection_properties
can contain additional custom parameters.
HIVE_ICEBERG
<location_dependent>
{"thrift_uri": "thrift://<url>:<port|9083>", "location_type": "GCS", "region": "us-east-1", "bucket": "<bucket_name>"}
SNOWFLAKE
SIMPLE
{"account": "test_acc", "warehouse": "<warehouse_name>", "role": "WH_ADMIN"}
Credentials
SIMPLE
{"username": "your_username", "password": "your_password"}
Basic username and password authentication.
AWS
{"access_key": "your_access_key_id", "secret_key": "your_secret_access_key"}
AWS credentials.
TOKEN
{"token": "your_api_token"}
API token for authentication.
AZURE_SAS
{"sas_key": "your_azure_sas_key"}
Azure Shared Access Signature key.
GENERIC_MAP
{"custom_param1": "value1", "custom_param2": "value2"}
A generic map for custom key-value pair credentials.
GCP
{"projectId": "telmai-dev", "privateKeyId": "your-private-key-id", "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n", "clientEmail": "[email protected]", "clientId": "your-client-id"}
GCP service account key details.
Update Connection
You can update an existing connection using a PUT
request.
Endpoints
Project-scoped:
PUT: https://{telmai_endpoint}/api/backend/{tenant}/configuration/projects/{projectId}/connections/{connectionId}
Connection by Id:
PUT: https://{telmai_endpoint}/api/backend/{tenant}/configuration/connections/{connectionId}
Request Body
The request body defines the properties to update for the connection. All fields are optional, and only those provided will be updated. This request body uses the same parameters defined in create request
List Connections
You can retrieve the list of connections using a GET
request.
Endpoints
Project-scoped:
GET: https://{telmai_endpoint}/api/backend/{tenant}/configuration/projects/{projectId}/connections
All Connections:
GET: https://{telmai_endpoint}/api/backend/{tenant}/configuration/connections
Response
The response is an array of connection objects, each containing detailed information about a connection.
[
{
"id": 3111,
"project_id": 0,
"name": "MyRedshiftConnection",
"scope": "GLOBAL",
"created_by": "[email protected]",
"created_at": "2025-05-23T11:03:01.000Z",
"type": "REDSHIFT",
"payload": {
"endpoint_prefix": "tlm-redshift02",
"database": "production_db",
"port": 5439
},
"db_type": "HANA101"
},
{
"id": 3112,
"project_id": 123,
"name": "MyProjectGCSConnection",
"scope": "PROJECT",
"created_by": "[email protected]",
"created_at": "2025-05-24T10:00:00.000Z",
"type": "GCS",
"payload": {
"bucket": "telmai_project_storage"
},
"db_type": null
}
]
Fields for Each Connection Object:
id
(integer): The unique identifier of the connection.project_id
(integer): The ID of the project the connection belongs to. For global connections, this will typically be0
.name
(string): The user-defined name of the connection.scope
(string): Indicates whether the connection isPROJECT
-scoped orGLOBAL
-scoped.created_by
(string): The email of the user who created the connection.created_at
(string): The timestamp when the connection was created, in ISO 8601 format (UTC).type
(string): The type of the connection (e.g.,REDSHIFT
,GCS
,AZURE
,BIGQUERY
,DELTALAKE
,GENERIC_JDBC
,HIVE_ICEBERG
,SNOWFLAKE
).payload
(object): The connection-specific configuration. The structure of this object varies based on thetype
of the connection. Refer to the "Connection Payload Formats by Type" section in the main Connection API documentation for detailed examples.db_type
(string, optional): The specific database type associated with the connection, if applicable (e.g., "HANA101" for aGENERIC_JDBC
connection or derived from other types). Can benull
if not relevant.
Get Connection Details
You can retrieve the details of an existing connection using a GET
request.
Endpoints
Project-scoped:
GET: https://{telmai_endpoint}/api/backend/{tenant}/configuration/projects/{projectId}/connections/{connectionId}
General reference:
GET: https://{telmai_endpoint}/api/backend/{tenant}/configuration/connections/{connectionId}
Request
This API endpoint uses a GET
method and does not require a request body.
Response
The response provides the full details of the requested connection.
{
"id": 3111,
"project_id": 0,
"name": "MyRedshift",
"scope": "PROJECT", // Can be "GLOBAL" in case of tenant-level endpoint
"created_by": "[email protected]",
"created_at": "2025-05-23T11:03:01.000Z", // ISO format in UTC
"type": "REDSHIFT",
"payload": {
"endpoint_prefix": "tlm-redshift02"
},
"db_type": "HANA101"
}
Fields:
id
(integer): The unique identifier of the connection.project_id
(integer): The ID of the project if it's a project-scoped connection; otherwise, it might be0
or null for global-scoped.name
(string): The name of the connection.scope
(string): Indicates whether the connection isPROJECT
-scoped orGLOBAL
-scoped.created_by
(string): The email of the user who created the connection.created_at
(string): The timestamp when the connection was created in ISO format (UTC).type
(string): The type of the connection.payload
(object): The connection-specific configuration. The format of this object depends on thetype
of the connection. Refer to the "API Payload Formats by Type" table for examples.db_type
(string): The database type, derived from the connection.
Last updated