Integration Templates & Revisions

Integration templates are org-level reusable integration definitions. Each template can have multiple immutable revisions, allowing you to version configuration changes over time while maintaining a full audit trail.

Architecture

Integration Template (org-level, reusable)
  └── Revision v1 (immutable config snapshot)
  └── Revision v2 (immutable config snapshot)
  └── Revision v3 (immutable config snapshot)

Pipeline A → uses Template at Revision v3
Pipeline B → uses Template at Revision v2

Templates can be created manually or installed from the Integration Catalog. Once created, templates are assigned to pipelines via Pipeline Integrations.

Integration Template Object

{
  "id": "tmpl_abc123",
  "org_id": "org_xyz",
  "name": "Meta CAPI Production",
  "vendor": "meta_capi",
  "description": "Meta CAPI for our e-commerce properties",
  "catalog_vendor_key": "meta_capi",
  "catalog_variant_key": "retail",
  "created_at": "2026-02-20T10:00:00Z",
  "updated_at": "2026-02-25T14:30:00Z"
}

Field	Type	Description
`id`	string	Unique template identifier
`org_id`	string	Organisation identifier
`name`	string	Display name (unique within org)
`vendor`	string	Vendor key (e.g. `meta_capi`, `ga4`, `google_ads`)
`description`	string	Template description
`catalog_vendor_key`	string	Catalog vendor key (if created from catalog)
`catalog_variant_key`	string	Catalog variant used (if created from catalog)
`created_at`	string	ISO 8601 creation timestamp
`updated_at`	string	ISO 8601 last-updated timestamp

Integration Revision Object

{
  "id": "rev_xyz789",
  "integration_id": "tmpl_abc123",
  "org_id": "org_xyz",
  "revision_number": 3,
  "config": {
    "pixel_id": "1234567890",
    "access_token": "EAABsb...",
    "batch_size": 100,
    "hash_pii": true
  },
  "delivery_mode": "server_side",
  "change_summary": "Updated access token for Q1 2026",
  "created_by": "user_123",
  "created_at": "2026-02-25T14:30:00Z"
}

Field	Type	Description
`id`	string	Unique revision identifier
`integration_id`	string	Parent template ID
`org_id`	string	Organisation identifier
`revision_number`	integer	Auto-incrementing revision number
`config`	object	Full integration configuration (vendor-specific)
`delivery_mode`	string	`server_side` or `client_side`
`change_summary`	string	Human-readable description of what changed
`created_by`	string	User ID who created this revision
`created_at`	string	ISO 8601 creation timestamp

Revisions are immutable. To change configuration, create a new revision. This ensures a complete audit trail and allows pipelines to pin to specific revisions.

Using Pipeline Parameters in Revision Config

Revision config values can reference pipeline parameters using the {{pipeline_param.KEY}} syntax. This allows a single integration revision to be shared across multiple pipelines, with each pipeline providing its own values for credentials and IDs.

For example, a GA4 revision config with parameter references:

{
  "config": {
    "measurement_id": "{{pipeline_param.ga4_measurement_id}}",
    "api_secret": "{{pipeline_param.ga4_api_secret}}",
    "debug_mode": false
  },
  "delivery_mode": "server_side",
  "change_summary": "GA4 config with pipeline parameter references"
}

When this revision is assigned to a pipeline, the event processor substitutes {{pipeline_param.ga4_measurement_id}} and {{pipeline_param.ga4_api_secret}} with the values defined in that pipeline’s parameters object. Static values like debug_mode are used as-is.

List Integration Templates

`GET /v1/admin/integration-templates`

Returns a paginated list of integration templates for the current organisation.

Query parameters:

Parameter	Type	Default	Description
`limit`	integer	50	Items per page (max 100)
`offset`	integer	0	Offset for pagination

Request:

curl -X GET "http://localhost:8084/v1/admin/integration-templates?limit=20" \
  -H "Authorization: Bearer {access_token}"

Response:

{
  "integrations": [
    {
      "id": "tmpl_abc123",
      "name": "Meta CAPI Production",
      "vendor": "meta_capi",
      "description": "Meta CAPI for our e-commerce properties",
      "catalog_vendor_key": "meta_capi",
      "catalog_variant_key": "retail",
      "created_at": "2026-02-20T10:00:00Z",
      "updated_at": "2026-02-25T14:30:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Required role: viewer or above.

Create Integration Template

`POST /v1/admin/integration-templates`

Create a new integration template manually (without using the catalog).

Request:

{
  "name": "Custom GA4 Setup",
  "vendor": "ga4",
  "description": "GA4 for internal analytics"
}

Field	Type	Required	Description
`name`	string	Yes	Display name (must be unique within org)
`vendor`	string	Yes	Vendor key (must be a valid vendor in the catalog)
`description`	string	No	Description

Response (201 Created): Full template object.

To create a template with pre-filled configuration, use the Install from Catalog endpoint instead.

Required role: editor or above.

Get Integration Template

`GET /v1/admin/integration-templates/{id}`

Retrieve a single integration template by ID.

Request:

curl -X GET http://localhost:8084/v1/admin/integration-templates/tmpl_abc123 \
  -H "Authorization: Bearer {access_token}"

Response: Full template object.

Required role: viewer or above.

Update Integration Template

`PUT /v1/admin/integration-templates/{id}`

Update metadata on an integration template. Only name and description can be updated.

Request:

{
  "name": "Meta CAPI - E-commerce",
  "description": "Updated description"
}

Response: Updated template object.

Required role: editor or above.

Delete Integration Template

`DELETE /v1/admin/integration-templates/{id}`

Soft-delete an integration template.

Request:

curl -X DELETE http://localhost:8084/v1/admin/integration-templates/tmpl_abc123 \
  -H "Authorization: Bearer {access_token}"

Response:

{
  "status": "deleted"
}

⚠️

Deletion will fail if the template is still assigned to any pipeline. Remove all pipeline assignments first.

Required role: admin or above.

Revisions

List Revisions

`GET /v1/admin/integration-templates/{id}/revisions`

Returns all revisions for an integration template, ordered by revision number descending (newest first).

Request:

curl -X GET http://localhost:8084/v1/admin/integration-templates/tmpl_abc123/revisions \
  -H "Authorization: Bearer {access_token}"

Response:

{
  "revisions": [
    {
      "id": "rev_xyz789",
      "integration_id": "tmpl_abc123",
      "revision_number": 3,
      "config": { "pixel_id": "1234567890", "batch_size": 100 },
      "delivery_mode": "server_side",
      "change_summary": "Updated access token",
      "created_by": "user_123",
      "created_at": "2026-02-25T14:30:00Z"
    },
    {
      "id": "rev_abc456",
      "integration_id": "tmpl_abc123",
      "revision_number": 2,
      "config": { "pixel_id": "1234567890", "batch_size": 50 },
      "delivery_mode": "server_side",
      "change_summary": "Increased batch size",
      "created_by": "user_123",
      "created_at": "2026-02-22T09:00:00Z"
    }
  ]
}

Required role: viewer or above.

Create Revision

`POST /v1/admin/integration-templates/{id}/revisions`

Create a new immutable revision with updated configuration.

Request:

{
  "config": {
    "pixel_id": "1234567890",
    "access_token": "EAABsb_new_token...",
    "batch_size": 100,
    "hash_pii": true
  },
  "delivery_mode": "server_side",
  "change_summary": "Rotated access token for Q1 2026"
}

Field	Type	Required	Description
`config`	object	Yes	Full integration configuration
`delivery_mode`	string	Yes	`server_side` or `client_side`
`change_summary`	string	No	Description of what changed

Response (201 Created): Full revision object with auto-assigned revision_number.

Creating a new revision does not automatically update any pipelines. To deploy the new revision, update the pipeline integration assignment to point to the new revision ID.

Required role: editor or above.

Get Revision

`GET /v1/admin/integration-templates/{id}/revisions/{rev}`

Retrieve a specific revision by revision number.

Request:

curl -X GET http://localhost:8084/v1/admin/integration-templates/tmpl_abc123/revisions/3 \
  -H "Authorization: Bearer {access_token}"

Response: Full revision object.

Required role: viewer or above.

Integration Catalog Pipeline Integrations