Programmatic whole-install works only for some templates. The one-shot install API (POST /v1/integrations/template/{id} with a connectionMap body) doesn't run a template's own install steps, so read the preview's Integration object first: if its installSteps include a step with type: template_zip -- most published templates have one -- the install is refused with 422 Install step is invalid: invalid templateZip and creates nothing. Install those from the UI installer. Over MCP, install_template is the same one-shot install, with the same connectionMap.

An MCP-server template installs through its own route. A template whose type is mcpserver takes no body and no connection map: celigo mcp-servers install-template <id>. A prompt-only template creates the MCP server, disabled; a tool-bearing one creates an integration in install mode, where its connections are mapped, and that integration's last step creates the disabled server (building-mcp-servers). The integration route refuses an MCP-server template (400 invalid_template), the MCP-server route answers 404 for an integration template, and no MCP tool installs an MCP-server template.

From a ZIP. An integration downloaded with celigo integrations download <id> installs into another account or environment with celigo templates install --zip <file>; preview it first with celigo templates preview --zip <file> to list the connections to map. The ZIP carries no credentials, so a connection you don't map arrives without them.

An install that timed out may have worked. Each install request that reaches the platform creates another integration, and a gateway timeout (504) or a dropped connection doesn't mean it failed. Before any retry -- including when the user asks you to "run it again" -- look for what the first request would have created: an integration carrying the template's _templateId (usually under the template's name), created around the time of the request, with its flows (the audit log shows the creates). If it's there, the install went through: report it, and don't install again. If you can't tell either way -- a lookup fails, or the list is ambiguous -- ask the user before installing again.

6. Or borrow one piece

Nothing copies a single element out of a template, so recreate it from the preview. Read what you need (celigo templates preview <id> --model Flow, then the exports, imports and scripts the flow references) and create each piece yourself in dependency order: scripts, then exports and imports, then the flow. Replace each placeholder connection id with one of your connections, and point the flow at the ids your creates return.

Always set the target integration when you create a flow: without _integrationId the platform files it under the account's Standalone flows integration, or rejects it with 422 standalone_flows_not_supported.

7. Map connections, satisfy settings, then enable

After resources land in your account:

• Verify each mapped connection points at the right account connection (see configuring-connections).
• Populate any settings references the blueprint expects (e.g., {{settings.integration.region}}) on the target integration or flow grouping -- an unsatisfied reference blocks the flow from running.
• Verify structure, confirm sandbox vs production matches your environment, then enable the flows. Everything installed or recreated is now an ordinary editable resource (an Integration App's locked parts stay locked; see Changing an Installed Integration App).

Changing an Installed Integration App

An Integration App locks its flows' steps, the connection each step uses, the endpoints and hooks the app ships (its own code), and some data-shaping settings. Its import mappings, lookups, input filters and response mappings stay editable. A write that changes a locked field isn't rejected: a PUT answers 200 and keeps the app's value (a PATCH of a locked field gets 422, a change to a flow's steps is refused, and a delete gets 403), so read the resource back after every change to an app's document.

Change the app's behavior through its settings, which the app's own code saves: the app's settings page in the UI, or the CLI's celigo integrations settings <id> followed by celigo integrations persist-settings <id> <field>=<value> (full mode). No MCP tool saves them, so over MCP send the user to the settings page. A plain write of settings, or an edit to the packaged step, skips that code. The save reports success even for a field it didn't store, so read the settings back to confirm each value; persist-settings does this and reports each field as saved, unchanged or not saved. A save can also reconfigure the app's flows, so treat it as a write to every flow the setting governs.

Switch one of the app's flows on or off through the app too, so the app's code runs for the change: the flow's switch on the app's page in the UI, or the CLI's celigo integrations persist-settings <id> --file toggle.json with {"pending": {"flowId": "<flowId>", "disabled": false}} (nested under the store id on a multi-store app), which the CLI checks against the flow afterwards. A direct write of the flow's disabled -- celigo flows set <flowId> disabled=false, or a flow PATCH or update -- changes the flow without the app's code. No MCP tool switches an app's flow through the app, so over MCP don't write the flow: name the flow and point the user to its switch on the app's page, or to the CLI.

Running an app after it's installed -- refreshing a field's options, switching its flows through the app, dating its updates, editions and add-on licenses, uninstalling -- is in managing-integrations > references/integration-apps.md.

Publishing Your Own Templates and Integration Apps

celigo templates list|get|create|update|delete and the celigo connectors group are publisher operations: they manage what an account publishes to the Marketplace, not what it installs. A template record (/v1/templates) becomes a listing once its ZIP is uploaded and it's published (gotcha 12). A connector (/v1/connectors) is an Integration App's listing, with the integrations installed from it (connectors install-base), updates pushed to those installs (connectors push-update, which runs the app's update function on each one), and its licenses (connectors licenses list|get|create|update|delete, each tying one user to their own installed integration). Only accounts Celigo has enabled to publish -- Partner accounts -- can use them. On any other account they answer 403 access_restricted ("You don't have the required permission to perform the request. Please contact Celigo support."), even for its owner with a full-access token: the check is the account's publisher status, not a user permission or token scope, so nothing in the account fixes it. Browsing (templates marketplace, templates preview) and installing (templates install, install_template over MCP) never need it, and no MCP tool manages templates or connectors. To run an Integration App you installed, see managing-integrations > references/integration-apps.md.

CLI Commands

# Browse the marketplace catalog (Integration Apps are excluded unless asked for)
celigo templates marketplace --include-connectors  # Templates and Integration Apps
celigo templates marketplace --type Template       # only Templates
celigo templates marketplace --type Connector      # only Integration Apps
celigo templates marketplace --kind mcpserver      # only templates that install an MCP server

# Check the account before installing (avoid duplicates)
celigo account search "<keyword>"

# Preview a blueprint's contents and dependencies (Templates only; an Integration App 404s)
celigo templates preview <id>
celigo templates preview <id> --summary
celigo templates preview <id> --model Connection    # connections the blueprint expects
celigo templates preview <id> --model Integration   # readme and install steps
celigo platform get v1/templates/<id>/preview --jq '{type, stackRequired}'

# Whole-template / Integration App install -> run in the Celigo Marketplace UI installer
#   (open the listing's preview page in the UI). The one-shot install below refuses a
#    template with a template_zip install step (celigo templates preview <id> --model Integration);
#    map every connection the preview lists, and never retry blindly (each request installs again):
echo '{"connectionMap":{"<sourceConnId>":"<targetConnId>"}}' | celigo templates install <id>

# An MCP-server template (type mcpserver): no body, no connection map
celigo mcp-servers install-template <id>

# An integration's ZIP into another account or environment
celigo integrations download <id> -o <file.zip>
celigo templates preview --zip <file.zip> --model Connection
celigo templates install --zip <file.zip> --file map.json   # map.json: {"connectionMap": {...}}

# Integration App settings: list the fields, then save through the app's own code (full mode)
celigo integrations settings <id>
celigo integrations persist-settings <id> <field>=<value>
# Switch an app's flow through the app (the UI's flow switch); toggle.json: {"pending": {"flowId": "<flowId>", "disabled": false}}
celigo integrations persist-settings <id> --file toggle.json

Pre-Submit Checklist

Before installing a template or Integration App, or recreating a piece of a template, verify:

• You searched the account first (celigo account search) so you don't duplicate an existing integration or connection
• You picked the right catalog type -- Template (you own and maintain it) vs Integration App (vendor-maintained, locked); the choice is hard to reverse
• You previewed a template's blueprint (celigo templates preview <id> --summary) and know which connections it expects, its type and whether it needs a stack (stackRequired); an Integration App has no preview, so you read its listing instead
• An MCP-server template (type: mcpserver) goes through celigo mcp-servers install-template, not templates install
• Every connection the preview lists has an account connection to map it to -- an API install refuses a partial connectionMap
• Every flow you recreate has its target _integrationId set
• Sandbox vs production is correct -- installed flows and connections must match your environment
• After a timeout or unclear error, you looked for the new integration before retrying the install

Gotchas

1. Whole-template install runs in the Marketplace UI. The one-shot install API doesn't run a template's install steps: a template whose preview Integration lists a template_zip install step (most published templates) is refused with nothing created. Install from the preview page in the UI.
2. Templates receive no ongoing updates. A template is a starting point you own and maintain -- if the source app's API changes, you fix it. Choose an Integration App when you need vendor-maintained updates.
3. Integration Apps are structure-locked, and a locked write still answers 200. The app locks its flows' steps, each step's connection, and its own endpoints and hooks; import mappings, lookups, input filters and response mappings stay editable. A PUT that changes a locked field keeps the app's value and answers 200, so read the resource back after every change. Picking an IA when you need deep customization leaves you at the locked-component ceiling.
4. Nothing maps connections for you. An API install needs a connectionMap with every template connection id as a key: a missing map is refused with invalid_connectionMap, and one that doesn't match the template's connections with invalid_connectionId. A ZIP install creates credential-less connections for any you leave out, and the UI installer lets you pick an existing connection or create one -- pick yours, or you'll end up with a duplicate.
5. Nothing copies a single element out of a template. No API call, CLI command or MCP tool does it. Recreate the piece from the preview in dependency order -- scripts, then exports and imports, then the flow with _integrationId set -- with your own connections, or install the whole template and keep what you need.
6. After install, everything is yours. Installed and recreated flows, exports, imports, and scripts are ordinary editable resources -- edit, delete, or run them like anything you built by hand. An Integration App's locked parts are the exception (gotcha 3).
7. Every install request creates a new integration. Installs aren't idempotent: each request that reaches the platform creates another integration (or MCP server). After a timeout or an unclear error, look for the new integration (the template's _templateId, a createdAt near the request) before trying again; a blind retry installs a duplicate.
8. Settings references may not carry over. Template flows can reference integration or flow-grouping settings (e.g., {{settings.integration.region}}). When you recreate a piece, the owning resource doesn't come along: populate those settings on the target before the piece will run.
9. A 403 on install, or on an MCP-server template's preview, is a user permission, not a plan limit. It means this user isn't allowed to install templates: a monitor user, or a user with access to specific integrations only, whose access doesn't allow creating integrations (the owner, administrators and manage users always may). An integration template's preview needs no such permission. An account owner or administrator can grant that or run the install. A 403 access_restricted from the template-management calls (celigo templates list, create, update, delete) or the celigo connectors group is different: those are publisher operations, open only to Partner accounts (Publishing Your Own Templates and Integration Apps).
10. Lookup cache data only travels when flagged. A lookup cache's data is included in a blueprint only when includeDataInTemplatesAndCloning: true; otherwise the cache lands empty.
11. Change an Integration App through its settings, and treat each save as a write. A plain write of settings, or an edit to the packaged step, skips the app's own code. Save through the app's settings page or celigo integrations persist-settings, then read the values back: the save reports success even for a field it didn't store, and it can reconfigure the flows the setting governs.
12. Publishing a template takes an uploaded ZIP. On a Partner account (gotcha 9), a template is created, then its ZIP is uploaded, then it's published: published: true is accepted only after the upload, and the ZIP decides the template's type. The CLI's templates create/update manage the record but upload no ZIP; an MCP server's ZIP comes from celigo mcp-servers download (building-mcp-servers).

Common Errors