---
title: "Create a connection"
method: POST
path: "/api/v3/destinations/{destination_name}/connections"
tags: ["Destination connections"]
---

# Create a connection

`POST /api/v3/destinations/{destination_name}/connections`

## Request

- Base URL: `https://embedded.improvado.io`
- URL: `https://embedded.improvado.io/api/v3/destinations/{destination_name}/connections`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `dts_session_id`
- TypeScript: <https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/docs/api/v3/destinations/:destination_name/connections/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a destination connection of a given type.

The set of `connection_params` fields depends on the destination. For `s3`:

- `connection_option` — authentication method: `aws_credentials` (default), `bucket_policy`, or `role_chaining`
- `aws_access_key_id`, `aws_secret_access_key` — AWS credentials; required only for `aws_credentials` (secret fields)
- `assume_role_arn` — customer IAM role ARN; required only for `role_chaining`
- `improvado_assume_role_arn`, `improvado_assume_role_externalid` — managed by Improvado and returned read-only; use them to build the trust policy on the customer side for `role_chaining`
- `aws_default_region` — AWS region code, e.g. `eu-west-1`
- `bucket_name`, `folder`, `filename` — target location; `filename` supports templates like `{{ filename }}-{{ YYYY }}-{{ MM }}-{{ DD }}`
- `file_format` (`parquet` | `csv` | `csv_gzip` | `csv_gz` | `json` | `json_gzip` | `json_gz` | `avro`), `separator`, `partition_by` (`by_day` | `by_month`)
- `max_file_size_mb` — optional chunking limit (45–100000); requires `{{chunk_id}}` in `filename` and `file_format: parquet`
- `encryption` (`no_storage_encryption` | `sse_s3` | `sse_kms` | `sse_kms_with_customer_managed_key`), `encryption_key` — required secret field: the KMS key id when using `sse_kms_with_customer_managed_key`, the literal placeholder `stub` for every other encryption option
- `use_load_by_accounts` — split delivered files by account

## Path parameters

- `destination_name` string, required

## Request body

- object
  - `title` string: Connection title
  - `create_load_for_new_tables` boolean: Create load for new tables
  - `destination_name` string: Destination name
  - `connection_params` object: Connection params

## Response `201`

Create a Connection

## Other responses

- `400`: Bad Request
- `401`: Forbidden

---

[API](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3.md) - [All operations](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/revisions/a881099bd6c4?raw)