GET /api/v1/connectors
List all connectors for the current tenant. Supports cursor-based pagination.
Query Parameters
| Parameter | Type | Default | Description |
|---|
limit | integer | 20 | Max results per page (max 100) |
cursor | string | — | Cursor for pagination (ID of last item from previous page) |
Response
{
"data": [
{
"id": "conn_001",
"name": "Production Snowflake",
"type": "snowflake",
"description": "Main data warehouse",
"config": { "account": "xy12345.us-east-1", "warehouse": "COMPUTE_WH", "database": "ANALYTICS" },
"authMethod": "access_key",
"status": "active",
"lastTestedAt": "2026-03-15T10:30:00.000Z",
"lastError": null,
"createdAt": "2026-01-10T08:00:00.000Z",
"updatedAt": "2026-03-15T10:30:00.000Z"
}
],
"total": 12,
"hasMore": false
}
The authConfig field is never returned in list or detail responses to prevent secret leakage.
POST /api/v1/connectors
Create a new connector.
Request Body
| Field | Type | Required | Description |
|---|
name | string | Yes | Unique connector name |
type | string | Yes | Connector type (see supported types below) |
description | string | No | Human-readable description |
config | object | No | Type-specific configuration (host, port, bucket, etc.) |
authMethod | string | No | Authentication method. Default: "access_key" |
authConfig | object | No | Credentials (encrypted at rest, never returned in responses) |
Supported Connector Types
| Type | Required Config Fields |
|---|
postgresql, mysql, redshift | host, port, database |
snowflake | account, warehouse, database |
databricks | host, httpPath |
bigquery | project, dataset |
mongodb | host or connectionString |
kafka, confluent_kafka | bootstrapServers |
aws_s3 | bucket, region |
gcs | bucket, project |
azure_blob | container, storageAccount |
sftp | host, port |
rest_api, webhook | url |
amazon_kinesis | streamName, region |
salesforce, hubspot | instanceUrl or apiKey |
Example
curl -X POST https://playground.kaireonai.com/api/v1/connectors \
-H "Content-Type: application/json" \
-H "X-Tenant-Id: my-tenant" \
-d '{
"name": "Customer Data Warehouse",
"type": "snowflake",
"config": {
"account": "xy12345.us-east-1",
"warehouse": "COMPUTE_WH",
"database": "ANALYTICS"
},
"authMethod": "access_key",
"authConfig": {
"username": "svc_kaireon",
"password": "secret"
}
}'
201 Created with the connector object (excluding authConfig).
PUT /api/v1/connectors
Update an existing connector. Only provided fields are updated.
Request Body
| Field | Type | Required | Description |
|---|
id | string | Yes | Connector ID |
name | string | No | Updated name |
type | string | No | Updated type |
description | string | No | Updated description |
config | object | No | Updated configuration |
authMethod | string | No | Updated auth method |
authConfig | object | No | Updated credentials (re-encrypted) |
status | string | No | Updated status |
200 OK with the updated connector (excluding authConfig).
DELETE /api/v1/connectors
Delete a connector by ID.
Query Parameters
| Parameter | Type | Required | Description |
|---|
id | string | Yes | Connector ID to delete |
204 No Content
POST /api/v1/connectors/test
Test a connector’s connection by performing a real probe (TCP, HTTP, or SDK-specific check). Rate limited to 100 requests per 60 seconds.
Request Body
| Field | Type | Required | Description |
|---|
id | string | Yes | ID of the connector to test |
Response
{
"id": "conn_001",
"name": "Production Snowflake",
"type": "snowflake",
"status": "active",
"lastTestedAt": "2026-03-16T14:30:00.000Z",
"lastError": null,
"authConfig": { "username": "sv***vc", "password": "****" }
}
- Validates required configuration fields for the connector type
- Performs a real connection probe (TCP for databases, HTTP HEAD for REST/webhook, bucket checks for cloud storage)
- Updates the connector’s
status to "active" (success) or "error" (failure)
- Uses a circuit breaker to prevent hammering failed connectors
- Includes SSRF protection (blocks private IPs, validates DNS resolution)
- Returns masked
authConfig values (first 2 + last 2 characters visible)
Error Responses
| Status | Cause |
|---|
400 | Missing id or invalid JSON |
404 | Connector not found |
429 | Rate limit exceeded |
Roles
| Endpoint | Allowed Roles |
|---|
GET /connectors | admin, editor, viewer |
POST /connectors | admin, editor |
PUT /connectors | admin, editor |
DELETE /connectors | admin, editor |
POST /connectors/test | admin, editor |
