> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apinizer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Connection

> Creates a new connection in a project. Connections are reusable configurations for external systems such as databases, message queues, email servers, and logging systems.

## Endpoint

```
POST /apiops/projects/{projectName}/connections/{connectionName}/
```

## Authentication

Requires a Personal API Access Token.

### Header

```
Authorization: Bearer YOUR_TOKEN
```

## Request

### Headers

| Header        | Value            | Required |
| ------------- | ---------------- | -------- |
| Authorization | Bearer {token}   | Yes      |
| Content-Type  | application/json | Yes      |

### Path Parameters

| Parameter      | Type   | Required | Description                               |
| -------------- | ------ | -------- | ----------------------------------------- |
| projectName    | string | Yes      | Project name                              |
| connectionName | string | Yes      | Connection name (must match name in body) |

### Request Body

**Note:** The API uses DTOs (Data Transfer Objects) for requests and responses. The `type` field is used as the discriminator field to identify the connection type, replacing the previous `_class` field used in internal entity models.

#### Full JSON Body Example (Email Connection)

```json theme={null}
{
  "type": "email",
  "name": "my-email-connection",
  "description": "Email connection for sending notifications",
  "deployToWorker": true,
  "enabled": true,
  "host": "smtp.gmail.com",
  "port": 587,
  "enableStartTls": true,
  "auth": true,
  "username": "user@example.com",
  "password": "app-password",
  "defaultEncoding": "UTF-8",
  "addressToTest": "test@example.com",
  "from": "noreply@example.com",
  "additionalProperties": []
}
```

#### Request Body Fields

##### Common Fields (All Connection Types)

| Field          | Type    | Required | Default | Description                                                                                                                                                                                                                                                                |
| -------------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type           | string  | Yes      | -       | Connection type discriminator field. Used to identify the connection type in API requests/responses. Valid values: `email`, `kafka`, `elasticsearch`, `database`, `ldap`, `ftp`, `rabbitMq`, `activeMq`, `snmp`, `linux-script`, `graylog`, `syslog`, `webhook`, `logback` |
| name           | string  | Yes      | -       | Connection name (must match path parameter)                                                                                                                                                                                                                                |
| description    | string  | No       | -       | Connection description                                                                                                                                                                                                                                                     |
| deployToWorker | boolean | No       | true    | Whether to deploy to worker                                                                                                                                                                                                                                                |
| enabled        | boolean | No       | true    | Whether connection is enabled                                                                                                                                                                                                                                              |

### Connection Types

* `email` - Email (SMTP) connection
* `kafka` - Kafka connection
* `elasticsearch` - Elasticsearch connection
* `database` - Database connection
* `ldap` - LDAP connection
* `ftp` - FTP connection
* `rabbitMq` - RabbitMQ connection
* `activeMq` - Apache ActiveMQ connection
* `snmp` - SNMP connection
* `linux-script` - Linux Script connection
* `ops-genie` - OpsGenie connection (if available)
* `graylog` - Graylog connection
* `syslog` - Syslog connection
* `webhook` - Webhook connection
* `logback` - Logback connection

**Note:** Connection-specific fields vary by connection type. See individual connection type documentation for complete field descriptions:

* [Email Connection](/api-reference/connections/connections/connection-email)
* [Kafka Connection](/api-reference/connections/connections/connection-kafka)
* [Database Connection](/api-reference/connections/connections/connection-database)
* … (see [Connections Index](/api-reference/connections/connections/connection-activemq.mdx) for complete list)

## Response

### Success Response (200 OK)

```json theme={null}
{
  "success": true,
  "deploymentResult": {
    "success": true
  }
}
```

#### Response Fields

| Field                    | Type    | Description                                |
| ------------------------ | ------- | ------------------------------------------ |
| success                  | boolean | Indicates if the request was successful    |
| deploymentResult         | object  | Deployment result (if deployToWorker=true) |
| deploymentResult.success | boolean | Deployment success                         |

### Error Response (400 Bad Request)

```json theme={null}
{
  "error": "bad_request",
  "error_description": "Connection (name: my-email-connection) already exists!"
}
```

#### Common Causes

* Connection name already exists
* Connection name in path does not match name in body
* Invalid connection type
* Missing required fields for connection type
* Invalid field values

### Error Response (401 Unauthorized)

```json theme={null}
{
  "error": "unauthorized_client",
  "error_description": "Invalid token"
}
```

### Error Response (404 Not Found)

```json theme={null}
{
  "error": "not_found",
  "error_description": "Project 'MyProject' not found"
}
```

## cURL Example

### Example 1: Create Email Connection

```bash theme={null}
curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/connections/my-email-connection/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "email",
    "name": "my-email-connection",
    "description": "Email connection for sending notifications",
    "deployToWorker": true,
    "enabled": true,
    "host": "smtp.gmail.com",
    "port": 587,
    "enableStartTls": true,
    "auth": true,
    "username": "user@example.com",
    "password": "app-password",
    "defaultEncoding": "UTF-8",
    "from": "noreply@example.com"
  }'
```

### Example 2: Create Database Connection

```bash theme={null}
curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/connections/my-db-connection/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "database",
    "name": "my-db-connection",
    "description": "PostgreSQL database connection",
    "deployToWorker": true,
    "enabled": true,
    "host": "localhost",
    "port": 5432,
    "databaseName": "mydb",
    "username": "dbuser",
    "password": "dbpassword",
    "driverClassName": "org.postgresql.Driver",
    "jdbcUrl": "jdbc:postgresql://localhost:5432/mydb"
  }'
```

### Example 3: Create Kafka Connection

```bash theme={null}
curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/connections/my-kafka-connection/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "kafka",
    "name": "my-kafka-connection",
    "description": "Kafka connection for event streaming",
    "deployToWorker": true,
    "enabled": true,
    "topicName": "events",
    "bootstrapServers": "localhost:9092",
    "keyStoreName": "my-keystore",
    "trustStoreName": "my-truststore"
  }'
```

## Permissions

* User must have **`CONNECTIONS` + `MANAGE`** permission in the project

## Notes and Warnings

* **Name Matching**: Connection name in path parameter must match the `name` field in the request body (case-insensitive)
* **Unique Names**: Connection names must be unique within a project
* **Secret Fields**: Never commit connection configurations with secrets to version control
* **Connection Types**: Each connection type has different required fields. See individual connection type documentation for details
* **Deployment**: If `deployToWorker: true`, connection is automatically deployed to workers
* **References**: Some connection types support references to certificates or keystores by name (e.g., `keyStoreName`, `trustStoreName`)

## Related Documentation

* [List Connections](/api-reference/connections/crud/list-connections) - List all connections
* [Get Connection](/api-reference/connections/crud/get-connection) - Get connection details
* [Update Connection](/api-reference/connections/crud/update-connection) - Update a connection
* [Delete Connection](/api-reference/connections/crud/delete-connection) - Delete a connection
* [Email Connection](/api-reference/connections/connections/connection-email) - Email connection details
* [Database Connection](/api-reference/connections/connections/connection-database) - Database connection details
* [Kafka Connection](/api-reference/connections/connections/connection-kafka) - Kafka connection details