Integration Catalog

The integration catalog provides a browsable library of pre-built vendor integrations. Each catalog entry includes configuration fields, default settings, and industry-specific variants for one-click setup.

The catalog is embedded in the Datafly Signal codebase and versioned alongside the platform. It does not require database storage and is always available.

Catalog Vendor Object

{
  "key": "meta_capi",
  "name": "Meta Conversions API (CAPI)",
  "description": "Send web, app, and offline events directly to Meta via the Conversions API.",
  "category": "advertising",
  "status": "ga",
  "website": "https://developers.facebook.com/docs/marketing-api/conversions-api",
  "config_fields": [
    {
      "key": "pixel_id",
      "label": "Pixel ID",
      "type": "string",
      "required": true,
      "placeholder": "123456789012345",
      "help_text": "Your Meta Pixel ID, found in Events Manager."
    },
    {
      "key": "access_token",
      "label": "Access Token",
      "type": "secret",
      "required": true,
      "placeholder": "EAABsb...",
      "help_text": "A system user access token."
    }
  ],
  "variants": [
    {
      "key": "default",
      "name": "Default",
      "description": "Standard configuration.",
      "default_config": { "batch_size": 100, "hash_pii": true }
    },
    {
      "key": "retail",
      "name": "Retail",
      "description": "Optimised for e-commerce events.",
      "default_config": { "batch_size": 100, "include_catalog_data": true }
    }
  ]
}

Field	Type	Description
`key`	string	Unique vendor identifier (used in API paths)
`name`	string	Display name
`description`	string	Vendor description
`category`	string	Category: `advertising`, `analytics`, `attribution`, `cdp`, `cloud_storage`, `other`
`status`	string	Availability status: `ga` (generally available) or `beta`
`website`	string	Link to vendor documentation
`config_fields`	array	Configuration field definitions (see below)
`variants`	array	Pre-configured variants (see below)

Config Field Object

Field	Type	Description
`key`	string	Field identifier used in config JSON
`label`	string	Human-readable label
`type`	string	Field type: `string`, `secret`, `select`, `boolean`, `number`
`required`	boolean	Whether the field is mandatory
`placeholder`	string	Example placeholder value
`help_text`	string	Help text describing the field
`options`	string[]	Available options (for `select` type fields)
`default`	any	Default value

Variant Object

Field	Type	Description
`key`	string	Variant identifier (e.g. `default`, `retail`, `travel`)
`name`	string	Display name
`description`	string	What this variant is optimised for
`default_config`	object	Default configuration values for this variant

List Catalog

`GET /v1/admin/integration-catalog`

Returns all vendors in the catalog. Supports filtering by category, status, and search term.

Query parameters:

Parameter	Type	Description
`search`	string	Search vendors by name or description
`category`	string	Filter by category (e.g. `advertising`, `analytics`)
`status`	string	Filter by status (`ga` or `beta`)

Request:

curl -X GET "http://localhost:8084/v1/admin/integration-catalog?category=advertising" \
  -H "Authorization: Bearer {access_token}"

Response:

{
  "vendors": [
    {
      "key": "meta_capi",
      "name": "Meta Conversions API (CAPI)",
      "description": "...",
      "category": "advertising",
      "status": "ga",
      "website": "https://...",
      "config_fields": [...],
      "variants": [...]
    }
  ],
  "total": 39,
  "categories": ["advertising", "analytics", "attribution", "cdp", "cloud_storage", "other"]
}

Required role: viewer or above.

Get Catalog Vendor

`GET /v1/admin/integration-catalog/{vendor}`

Returns a single catalog vendor with full details including config fields and variants.

Request:

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

Response: Full catalog vendor object.

Required role: viewer or above.

Install from Catalog

`POST /v1/admin/integration-catalog/{vendor}/install`

One-click installation: creates an integration template and its first revision (v1) atomically. The revision config is built by merging the selected variant’s defaults with any user-provided overrides.

Request:

{
  "name": "Meta CAPI Production",
  "variant": "retail",
  "config": {
    "pixel_id": "1234567890",
    "access_token": "EAABsb..."
  },
  "delivery_mode": "server_side",
  "description": "Meta CAPI for our e-commerce site"
}

Field	Type	Required	Description
`name`	string	Yes	Display name for the integration template
`variant`	string	No	Variant key (defaults to `default`)
`config`	object	No	User-provided config (merged with variant defaults)
`delivery_mode`	string	No	`server_side` (default) or `client_side`
`description`	string	No	Description of the integration

Response (201 Created):

{
  "template": {
    "id": "tmpl_abc123",
    "org_id": "org_xyz",
    "name": "Meta CAPI Production",
    "vendor": "meta_capi",
    "description": "Meta CAPI for our e-commerce site",
    "catalog_vendor_key": "meta_capi",
    "catalog_variant_key": "retail",
    "created_at": "2026-02-25T10:00:00Z",
    "updated_at": "2026-02-25T10:00:00Z"
  },
  "revision": {
    "id": "rev_xyz789",
    "integration_id": "tmpl_abc123",
    "org_id": "org_xyz",
    "revision_number": 1,
    "config": {
      "batch_size": 100,
      "include_catalog_data": true,
      "pixel_id": "1234567890",
      "access_token": "EAABsb..."
    },
    "delivery_mode": "server_side",
    "change_summary": "Initial setup from catalog: Meta Conversions API (CAPI) (retail variant)",
    "created_by": "user_123",
    "created_at": "2026-02-25T10:00:00Z"
  }
}

After installation, assign the integration template to one or more pipelines using the Pipeline Integrations API.

Required role: editor or above.

Pipelines Integration Templates