# Connections

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.

**Project-scoped:** <mark style="color:green;">`POST`</mark> `https://{telmai_endpoint}/api/backend/{tenant}/configuration/projects/{projectId}/connections`

**Global-scoped:** <mark style="color:green;">`POST`</mark> `https://{telmai_endpoint}/api/backend/{tenant}/configuration/connections`

### Request Body

The request body defines the properties of the new connection.

```json
{
  "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`.

```json
{
  "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><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.

**Project-scoped:** <mark style="color:orange;">`PUT`</mark> `https://{telmai_endpoint}/api/backend/{tenant}/configuration/projects/{projectId}/connections/{connectionId}`

**Connection by Id:** <mark style="color:orange;">`PUT`</mark> `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.

**Project-scoped:** <mark style="color:blue;">`GET`</mark> `https://{telmai_endpoint}/api/backend/{tenant}/configuration/projects/{projectId}/connections`

**All Connections:** <mark style="color:blue;">`GET`</mark> `https://{telmai_endpoint}/api/backend/{tenant}/configuration/connections`

**Response**

The response is an array of connection objects, each containing detailed information about a connection.

```json
[
  {
    "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.

**Project-scoped:** <mark style="color:blue;">`GET`</mark> `https://{telmai_endpoint}/api/backend/{tenant}/configuration/projects/{projectId}/connections/{connectionId}`

**General reference:** <mark style="color:blue;">`GET`</mark> `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.

```json
{
  "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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.telm.ai/telmai/api-reference/connections.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.