Connectors - KaireonAI

Connector status: 81 connector types are registered in the UI. Two — amazon_kinesis and braze — ship as coming-soon: they expose create/edit forms (and a working Test Connection probe for Amazon Kinesis), but pipeline runs that source from them no-op (the executor logs a message and returns zero rows). The 26 W16 expansion entries documented on Connectors Expanded are also coming-soon. Every other registered type is production-ready.

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,
      "lastSyncRowCount": 18432,
      "lastSyncAt": "2026-03-15T10:30:05.000Z",
      "createdAt": "2026-01-10T08:00:00.000Z",
      "updatedAt": "2026-03-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 12,
    "hasMore": false,
    "limit": 50,
    "cursor": null
  }
}

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.). Also accepts `connectionConfig` as an alias.
`authMethod`	string	No	Authentication method. Default: `"access_key"`
`authConfig`	object	No	Credentials (encrypted at rest, never returned in responses)

The config field contains type-specific settings like bucket, region, prefix for S3 or account, warehouse, database for Snowflake. You can also send connectionConfig as an alias — the API accepts both names and merges them.

Supported Connector Types

Type	Status	Required Config Fields
`postgresql`, `mysql`, `redshift`	Ready	`host`, `port`, `database`
`snowflake`	Ready	`account`, `warehouse`, `database`, `sourceTable`, `rowLimit` (optional)
`bigquery`	Ready	`project`, `dataset`, `sourceTable`, `rowLimit` (optional)
`mongodb`	Ready	`host` or `connectionString`
`kafka`, `confluent_kafka`	Ready (batch polling)	`bootstrapServers`
`aws_s3`	Ready	`bucket`, `region`
`gcs`	Ready	`bucket`, `project`
`azure_blob`	Ready	`container`, `storageAccount`
`sftp`	Ready	`host`, `port`
`rest_api`, `webhook`	Ready	`url`
`salesforce`, `hubspot`	Ready	`instanceUrl` or `apiKey`
`databricks`	Ready	`host`, `httpPath`
`segment`, `shopify`, `stripe`, `mailchimp`	Ready	See `/data/overview` for fields
`amazon_kinesis`	Coming soon (connection test works)	`streamName`, `region`
`braze`	Coming soon	See `/data/overview` for fields

Kafka is batch polling, not true streaming. Each pipeline run opens a consumer, reads up to maxMessages records (default 1000) with a configurable wait timeout (default 15 seconds), commits offsets, and closes. True long-lived streaming requires a persistent worker that is not yet implemented.

Snowflake and BigQuery row limits. Both connectors accept a sourceTable (required) and rowLimit (optional). The executor issues SELECT * FROM <sourceTable> LIMIT <rowLimit>. The default rowLimit is 100,000 rows (demo-safe). Set to 0 to remove the cap — only do this once you have sized the target database and pipeline run budget to handle full-table reads.

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"
    }
  }'

Response: 201 Created with the connector object (excluding authConfig).

PUT /api/v1/connectors

Update an existing connector. Only fields explicitly included in the body are changed — omitted fields preserve their existing values.

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). Omit to keep existing credentials.
`status`	string	No	Updated status

Response: 200 OK with the updated connector (authConfig returned masked).

Credential preservation contract

authConfig is special. The endpoint follows these rules:

Omit authConfig entirely → existing credentials are preserved unchanged. This is the path used by the UI’s Edit form, which leaves credential fields blank by default with a “Leave blank to keep existing” placeholder.
Send authConfig with non-empty values → new credentials are encrypted and stored, replacing the old ones.
Send authConfig: {} → existing credentials are wiped. Avoid unless you intentionally want to clear them.

Clients implementing connector edit forms should follow the UI pattern: only serialize authConfig into the PUT body when the user actually entered new credential values.

DELETE /api/v1/connectors

Delete a connector by ID.

Query Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Connector ID to delete

Response: 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,
  "lastSyncRowCount": 18432,
  "lastSyncAt": "2026-03-16T14:30:02.000Z",
  "success": true,
  "message": "Connection test succeeded",
  "warning": null,
  "latencyMs": 412
}

The test endpoint:

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, SDK-specific probes for Databricks and Amazon Kinesis)
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)
Omits authConfig from the response (credentials never leave the server)
For CSV connectors with an inline file path/URL, parses the sample, stamps lastSyncRowCount with the row count and lastSyncAt with the probe timestamp so the connector list can show how much data is reachable from the source

Response Fields

Field	Type	Meaning
`success`	boolean	`true` when the probe reached the resource and returned an acceptable response
`message`	string	Human-readable summary — `"Connection test succeeded"` or the failure reason
`warning`	string \| null	Transient informational message when `success: true` but the probe found a soft signal (e.g. an S3 bucket that’s reachable but has no files at the prefix yet). Not persisted — fresh every call.
`latencyMs`	number	Round-trip latency for the probe
`lastError`	string \| null	Cleared to `null` on success. Only set when the probe actually failed. Persisted to the connector row so the detail page can show recent error history.
`status`	string	`"active"` on success, `"error"` on failure — persisted
`lastTestedAt`	string	ISO timestamp of this probe — persisted

Earlier versions of this endpoint wrote warning text into lastError even when the test succeeded, which caused UI surfaces to render a persistent “Last Error” card despite a green success toast. The endpoint now keeps lastError reserved for real failures; soft signals travel in the transient warning field instead. UI clients should suppress red error styling when status === "active".

Connection testing for the coming-soon braze connector reports a generic failure until a dedicated probe is wired. Amazon Kinesis has a working test probe today.

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

​GET /api/v1/connectors

​Query Parameters

​Response

​POST /api/v1/connectors

​Request Body

​Supported Connector Types

​Example

​PUT /api/v1/connectors

​Request Body

​Credential preservation contract

​DELETE /api/v1/connectors

​Query Parameters

​POST /api/v1/connectors/test

​Request Body

​Response

​Response Fields

​Error Responses

​Roles

GET /api/v1/connectors

Query Parameters

Response

POST /api/v1/connectors

Request Body

Supported Connector Types

Example

PUT /api/v1/connectors

Request Body

Credential preservation contract

DELETE /api/v1/connectors

Query Parameters

POST /api/v1/connectors/test

Request Body

Response

Response Fields

Error Responses

Roles