Connection Templates

CoreStandardProEnterprise FlexSelf-Managed EnterpriseEmbedded Compare

A connection template pre-defines the destination side of every pipeline your customers spin up through the API or Embedded Widget. It answers two questions up-front:

Where should the data land?
How often should it sync?

When a customer finishes configuring a source, Airbyte automatically creates the connection by combining their source settings with your template.

Creating connection templates

You'll need the following to create a connection template:

Your organization ID
The destination definition ID
The destination configuration
The destination name: We'll automatically create a destination with the given name in your user's workspaces
(Optional) A cron expression describing when to run syncs. The cron expression must follow the Quartz syntax. You can use freeformatter.com to help validate the expression
(Optional) Tags to organize and filter templates

Example request

curl --request POST 'https://api.airbyte.ai/api/v1/integrations/templates/connections' \

  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <bearer_token>" \
  --data-raw '{

    "organization_id": "<organization_id>",
    "destination_name": "string",
    "destination_definition_id": "<destination_definition_id>",
    "destination_config": {
      "access_key_id": "<aws_access_key>",
      "secret_access_key": "<aws_secret_key>",
      "s3_bucket_name": "<s3_bucket>",
      "s3_bucket_path": "<s3_prefix>",
      "s3_bucket_region": "<s3_region>",
      "format": {
        "format_type": "CSV",
        "compression": {
          "compression_type": "No Compression"
        },
        "flattening": "Root level flattening"
      }
    },
    "cron_expression": "0 0 12 * * ?",
    "non_breaking_changes_preference": "propagate_columns",
    "sync_on_create": true,
    "tags": ["analytics", "standard-sync"]
  }'

You can find the full connector specification in the Connector Registry.

Alternatively, if you want to view the full JSON for a given connector when creating a source or destination from scratch in Airbyte Cloud. After configuring the connector to your desired specifications (partially complete if you want an end user to complete the rest), you can select "Copy JSON". This will give you necessary details like the configuration and the destination_definition_id.

You can find the reference docs for creating a connection template here.

Configuration options

sync_on_create

Controls whether the connection should automatically start syncing immediately after creation.

true (default) - Connection starts syncing as soon as it's created
false - Connection is created but won't sync until its scheduled time or a manual trigger

Example:

{
  "sync_on_create": false
}

Use sync_on_create: false when you want users to review the connection configuration before the first sync runs.

non_breaking_changes_preference

Controls how Airbyte handles non-breaking schema changes (for example, new columns added to a table).

Available Options:

Value	Behavior
`ignore`	Ignore schema changes; continue syncing only previously configured columns
`disable`	Disable the connection when schema changes are detected
`propagate_columns`	Automatically add new columns to the sync but don't update data types
`propagate_fully`	Automatically propagate all schema changes including column additions and data type updates

Example:

{
  "non_breaking_changes_preference": "propagate_columns"
}

Use Cases:

ignore: Use when you have strict schema requirements and don't want unexpected columns
disable: Use when schema changes require manual review
propagate_columns: Best for most use cases; adds new columns automatically
propagate_fully: Use when you want complete automation of schema evolution

Cron expression validation

Airbyte provides an endpoint to validate and describe cron expressions:

curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/connections/cron/describe \

  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{

    "cron_expression": "0 0 12 * * ?"
  }'

This endpoint returns a human-readable description of when the cron will execute.

Managing connection templates

List connection templates

curl 'https://api.airbyte.ai/api/v1/integrations/templates/connections' \

  -H 'Authorization: Bearer <token>'

Filter by tags

You can filter connection templates by tags:

curl 'https://api.airbyte.ai/api/v1/integrations/templates/connections?tags=analytics&tags=standard-sync&tags_mode=all' \

  -H 'Authorization: Bearer <token>'

Tag Selection Modes:

any - Template must have at least one of the specified tags
all - Template must have all of the specified tags

Get connection template

curl 'https://api.airbyte.ai/api/v1/integrations/templates/connections/{id}' \

  -H 'Authorization: Bearer <token>'

Update connection template

Use the PATCH endpoint to update an existing connection template:

curl -X PATCH 'https://api.airbyte.ai/api/v1/integrations/templates/connections/{id}' \

  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{

    "cron_expression": "0 0 6 * * ?",
    "non_breaking_changes_preference": "propagate_fully"
  }'

Delete connection template

curl -X DELETE 'https://api.airbyte.ai/api/v1/integrations/templates/connections/{id}' \

  -H 'Authorization: Bearer <token>'

Managing template tags

Add tag to connection template

curl -X POST https://api.airbyte.ai/api/v1/integrations/templates/connections/{id}/tags \

  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{

    "tag": "premium-features"
  }'

Remove tag from connection template

curl -X DELETE https://api.airbyte.ai/api/v1/integrations/templates/connections/{id}/tags/{tag_name} \

  -H 'Authorization: Bearer <token>'

For complete tag management documentation, see Template Tags.

Using connection templates with sources

When a user creates a source from a source template, Airbyte automatically:

Creates the destination configured in your connection template
Creates a connection between the source and destination
Applies the schedule (cron expression) to the connection
Applies the schema change preference
Starts syncing if sync_on_create is true

Filter connection templates by tags

You can control which connection templates are available when creating sources by using tag filtering in widget tokens or scoped tokens:

curl -X POST https://api.airbyte.ai/api/v1/embedded/widget-token \

  -H 'Authorization: Bearer <operator_token>' \
  -H 'Content-Type: application/json' \
  -d '{

    "workspace_name": "customer_workspace",
    "allowed_origin": "https://yourapp.com",
    "selected_connection_template_tags": ["standard-sync"],
    "selected_connection_template_tags_mode": "any"
  }'

This ensures that only connection templates tagged with "standard-sync" are available when the user creates a source.

Common patterns

Multi-tenant destinations

Create separate connection templates for different customer tiers:

Free tier - Basic S3 sync:

{
  "destination_name": "Free Tier S3",
  "destination_definition_id": "s3-definition-id",
  "destination_config": {
    "s3_bucket_name": "free-tier-bucket",
    "format": { "format_type": "CSV" }
  },
  "cron_expression": "0 0 12 * * ?",
  "non_breaking_changes_preference": "ignore",
  "tags": ["free-tier"]
}

Enterprise tier - Optimized BigQuery sync:

{
  "destination_name": "Enterprise BigQuery",
  "destination_definition_id": "bigquery-definition-id",
  "destination_config": {
    "project_id": "enterprise-project",
    "dataset_id": "enterprise_data"
  },
  "cron_expression": "0 */4 * * * ?",
  "non_breaking_changes_preference": "propagate_fully",
  "sync_on_create": true,
  "tags": ["enterprise"]
}

Testing vs production

Create separate templates for different environments:

# Development template - hourly syncs
{
  "destination_name": "Dev Database",
  "cron_expression": "0 0 * * * ?",
  "tags": ["development", "testing"]
}

# Production template - daily syncs
{
  "destination_name": "Prod Database",
  "cron_expression": "0 0 2 * * ?",
  "tags": ["production"]
}

Compliance-based templates

Create templates for different compliance requirements:

# HIPAA-compliant template
{
  "destination_name": "HIPAA Compliant Warehouse",
  "destination_definition_id": "snowflake-definition-id",
  "destination_config": {
    "encryption": "enabled",
    "region": "us-west-2"
  },
  "tags": ["hipaa-compliant", "healthcare"]
}

# GDPR-compliant template
{
  "destination_name": "GDPR Compliant Warehouse",
  "destination_definition_id": "bigquery-definition-id",
  "destination_config": {
    "region": "europe-west1"
  },
  "tags": ["gdpr-compliant", "eu-region"]
}

Template Tags - Organize and filter templates with tags
Source Templates - Configure which sources are available
Authentication - Generate tokens with template filtering
Configuring Sources - How sources and connections work together

Creating connection templates​

Example request​

Configuration options​

sync_on_create​

non_breaking_changes_preference​

Cron expression validation​

Managing connection templates​

List connection templates​

Filter by tags​

Get connection template​

Update connection template​

Delete connection template​

Managing template tags​

Add tag to connection template​

Remove tag from connection template​

Using connection templates with sources​

Filter connection templates by tags​

Common patterns​

Multi-tenant destinations​

Testing vs production​

Compliance-based templates​

Related documentation​