# 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 the `payload` 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 the `credential.type`. Refer to the [**Credentials**](#credentials) documentation for detailed `payload` formats.
* `payload` (object): The connection-specific configuration. The format of this object depends on the `type` of the connection. Refer to the "[API Payload Formats by Type](#payload)" 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": "john_doe@telm.ai",
  "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 be `0` or null for global-scoped.
* `name` (string): The name of the connection.
* `scope` (string): Indicates whether the connection is `PROJECT`-scoped or `GLOBAL`-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 on `location_type` within its `payload` (e.g., `GCP`, `AWS`, `AZURE_SAS`).

### Payload

Payload object describes the connection detail and is dependent on connection type

<table><thead><tr><th width="146.28125">Type</th><th width="148.625">Credential Type</th><th>Payload Format</th></tr></thead><tbody><tr><td><code>REDSHIFT</code></td><td><code>SIMPLE</code></td><td><code>{"endpoint_prefix": "tlm-redshift02"}</code></td></tr><tr><td><code>GCS</code></td><td><code>GCP</code></td><td><code>{"bucket": "&#x3C;bucket_name>"}</code></td></tr><tr><td><code>S3</code></td><td><code>AWS</code></td><td><code>{"bucket": "&#x3C;bucket_name>"}</code></td></tr><tr><td><code>AZURE</code></td><td><code>AZURE_SAS</code></td><td><code>{"storage_account": "test_acc", "bucket": "&#x3C;bucket_name>"}</code></td></tr><tr><td><code>BIGQUERY</code></td><td><code>GCP</code></td><td><code>{"project": "test_project"}</code></td></tr><tr><td><code>DELTALAKE</code></td><td><code>TOKEN</code></td><td><code>{"host": "test.db23.databricks.com", "port": "443", "httppath": "some/path"}</code></td></tr><tr><td><code>GENERIC_JDBC</code></td><td><code>GENERIC_MAP</code></td><td><p><code>{"db_type": "HANA10", "db_or_schema": "test_db", "connection_properties": {"prop1": "value1", "prop2": "value2"}}</code> </p><p></p><p><code>connection_properties</code> can contain additional custom parameters.</p></td></tr><tr><td><code>HIVE_ICEBERG</code></td><td>&#x3C;location_dependent></td><td><code>{"thrift_uri": "thrift://&#x3C;url>:&#x3C;port|9083>", "location_type": "GCS", "region": "us-east-1", "bucket": "&#x3C;bucket_name>"}</code></td></tr><tr><td><code>SNOWFLAKE</code></td><td><code>SIMPLE</code></td><td><code>{"account": "test_acc", "warehouse": "&#x3C;warehouse_name>", "role": "WH_ADMIN"}</code></td></tr></tbody></table>

### Credentials

<table data-header-hidden><thead><tr><th width="128.19140625">Credential Type</th><th>Payload Example</th><th>Details</th></tr></thead><tbody><tr><td><code>SIMPLE</code></td><td><code>{"username": "your_username", "password": "your_password"}</code></td><td>Basic username and password authentication.</td></tr><tr><td><code>AWS</code></td><td><code>{"access_key": "your_access_key_id", "secret_key": "your_secret_access_key"}</code></td><td>AWS credentials.</td></tr><tr><td><code>TOKEN</code></td><td><code>{"token": "your_api_token"}</code></td><td>API token for authentication.</td></tr><tr><td><code>AZURE_SAS</code></td><td><code>{"sas_key": "your_azure_sas_key"}</code></td><td>Azure Shared Access Signature key.</td></tr><tr><td><code>GENERIC_MAP</code></td><td><code>{"custom_param1": "value1", "custom_param2": "value2"}</code></td><td>A generic map for custom key-value pair credentials.</td></tr><tr><td><code>GCP</code></td><td><code>{"project_id": "telmai-dev", "private_key_id": "your-private-key-id", "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n", "client_email": "your-service-account-email@your-project.iam.gserviceaccount.com", "client_id": "your-client-id"}</code></td><td>GCP service account key details.</td></tr></tbody></table>

## 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`&#x20;

**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": "john_doe@telm.ai",
    "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": "john.doe@telm.ai",
    "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 be `0`.
* `name` (string): The user-defined name of the connection.
* `scope` (string): Indicates whether the connection is `PROJECT`-scoped or `GLOBAL`-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 the `type` 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 a `GENERIC_JDBC` connection or derived from other types). Can be `null` 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": "john_doe@telm.ai",
  "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 be `0` or null for global-scoped.
* `name` (string): The name of the connection.
* `scope` (string): Indicates whether the connection is `PROJECT`-scoped or `GLOBAL`-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 the `type` of the connection. Refer to the "API Payload Formats by Type" table for examples.
* `db_type` (string): The database type, derived from the connection.