Create Connection

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)

{
  "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
• Kafka Connection
• Database Connection
• … (see Connections Index for complete list)

Response

Success Response (200 OK)

{
  "status": "SUCCESS",
  "deploymentResult": {
    "success": true
  }
}

Response Fields

Field	Type	Description
status	string	Response status: SUCCESS or FAILURE
deploymentResult	object	Deployment result (when deployToWorker=true)
deploymentResult.success	boolean	Worker deployment success

Note

If a connection with the same name already exists, POST performs an upsert (updates the existing connection) rather than returning an error.

Error Response (400 Bad Request)

{
  "status": "FAILURE",
  "resultMessage": "Connection (name: my-email-connection) already exists!"
}

Common Causes

• 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)

{
  "status": "FAILURE",
  "resultMessage": "Token is not valid!"
}

cURL Example

Example 1: Create Email Connection

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

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

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. If a connection of the same type and name already exists, this call updates it (upsert, for promotion pipelines)
• Secret Fields: Never commit connection configurations with secrets to version control. On an upsert the same rules as Update Connection apply: an absent secret field keeps the stored value, an empty string clears it, a value replaces it — including a Kafka propertiesMap entry or Webhook headerList header whose key/name is sensitive, matched the same way (headers case-insensitive, first occurrence)
• LDAP connections: useTls (STARTTLS) and connectionTimeout (milliseconds) can be supplied; omitting useTls stores false
• 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: Kafka, Syslog, LDAP, Webhook, and Email certificate/key-store references are name-only on APIops. Use keyStoreName, trustStoreName, webhookKeyStoreName, webhookTrustStoreName, or certificateName as appropriate. Storage ID fields are internal and are rejected with 400 Bad Request even when supplied as null or an empty string; they are never returned or published in the OpenAPI schema. Names resolve within the calling project and then the shared admin project. On POST upsert, an absent or null name keeps a still-valid stored reference, "" clears an optional reference, and a non-empty name replaces it. A dangling or foreign stored reference must be repaired by a valid name or explicitly cleared before the upsert can write.

Related Documentation

• List Connections - List all connections
• Get Connection - Get connection details
• Update Connection - Update a connection
• Delete Connection - Delete a connection
• Email Connection - Email connection details
• Database Connection - Database connection details
• Kafka Connection - Kafka connection details