---
title: "Create a connection."
method: POST
path: "/connections"
tags: ["Connection Operations"]
---

# Create a connection.

`POST /connections`

## Request

- Base URL: `https://replace-with-account.api.decodable.co/v1alpha2`
- URL: `https://replace-with-account.api.decodable.co/v1alpha2/connections`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://auth.decodable.co/authorize?audience=https://api.decodable.co/`
    - Token URL: `https://auth.decodable.co/oauth/token` scopes: `write:connection`
- TypeScript: <https://skmtc.dev/decodable/apis/decodable-control-plane/docs/connections/post.ts> (a function with typed inputs; its response is checked against the schema)

Requires permissions matching: 
- `connection:write:default.<name>`
- `stream:read-data:default.<stream-name>` on attached streams for sink connections
- `stream:write-data:default.<stream-name>` on attached streams for source connections

## Query parameters

- `stream_name` string
- `stream_description` string
- `enable_experimental` boolean
- `response_schema_v` 'v1' | 'v2'

## Request body

- ConnectionCommon: `kind: connection`, `spec_version: v1`.
  - `name` string: The connection name.
  - `description` string: The connection description.
  - `connector` 'astra-streaming' | 'clickhouse' | 'confluent-cloud' | 'datadog' | 'datagen' | 'delta-lake' | 'druid' | 'dynamodb-cdc' | 'elasticsearch' | 'gcp-pubsub' | 'hudi' | 'influxdb' | 'kafka' | 'kinesis' | 'mongodb' | 'mongodb-cdc' | 'ms-sql' | 'mysql-cdc' | 'oracle' | 'oracle-cdc' | 'pinot' | 'polaris' | 'postgres' | 'postgres-cdc' | 'pulsar' | 'redis' | 'redpanda' | 'redshift' | 'rest' | 'rockset' | 's3' | 's3-lambda' | 's3-v2' | 'singlestore-db' | 'snowflake' | 'startree' | 'streamnative' | 'timescale': The connector used by the connection.
  - `type` 'source' | 'sink': The connection type.
  - `stream_mappings` object[]: The connection stream mappings. If present, `schema` and `stream_id` must be `null`.
    - `stream_id` string: An opaque ID, created by Decodable, that uniquely identifies a resource.
    - `external_resource_specifier` unknown
  - `stream_id` string: An opaque ID, created by Decodable, that uniquely identifies a resource.
  - `schema` object[]: Record schema.
    - `name` string: The field name.
    - `type` string: The field type.
  - `schema_v2` SchemaV2: Record schema, version 2.
    - `fields` union[]: The fields in this schema.
      - union
        - PhysicalField: A physical field.
          - `kind` 'physical', required
          - `name` string
          - `type` string
        - ComputedField: A computed field.
          - `kind` 'computed', required
          - `name` string
          - `expression` string
        - MetadataField: A metadata field.
          - `kind` 'metadata', required
          - `name` string
          - `type` string
          - `key` string
    - `watermarks` object[]: Watermark expressions for this stream. At this time only one expression is supported.
      - `name` string
      - `expression` string
    - `constraints` object
      - `primary_key` string[]: Column names to use for primary key.
  - `properties` object: The connection properties.
  - `autoscale_configuration` AutoscaleConfiguration, nullable: The configuration for autoscale conditions.
    - `pause_conditions` object, nullable: A map of pause conditions and their given setting values.
    - `resume_conditions` object, nullable: A map of resume conditions and their given setting values.

## Response `200`

Connectivity was successfully established but the connection was not created.

## Other responses

- `201`: A connection creation response.
- `400`: An invalid request was received.
- `403`: Access denied: requesting user lacks a required permission.
- `409`: A conflicting resource already exists.
- `default`: An error has occurred.

---

[API](https://skmtc.dev/decodable/apis/decodable-control-plane.md) - [All operations](https://skmtc.dev/decodable/apis/decodable-control-plane/llms.txt) - [OpenAPI document](https://skmtc.dev/decodable/apis/decodable-control-plane/revisions/9718a3019da8?raw)