<!-- TIER:1 -->

Getting Started with Celigo Integrations

Core Concepts

Celigo integrations move data between external systems through a small set of resource types:

• Connection -- credentials and configuration that authenticate to an external system (Salesforce, NetSuite, HTTP API, database, FTP, etc.)
• Export -- data source step that fetches records from a connected system (or receives them via webhook)
• Import -- data destination step that writes records to a connected system
• Flow -- pipeline that connects exports to imports, with optional branching, transformation, and scripting
• Integration -- named container that groups related flows, connections, and resources
• Script -- JavaScript hook that runs at specific points in the data pipeline (preSavePage, preMap, postMap, postSubmit, postResponseMap)
• API -- custom HTTP endpoint that exposes integration logic for synchronous external consumption
• Tool -- reusable building block (input schema -> routers with lookups/imports -> output contract) callable from flows, APIs, AI agents, MCP servers, and other tools
• AI agent -- LLM-powered pipeline step (stored as an import) that classifies, extracts, summarizes, or generates data mid-pipeline
• Guardrail -- safety/compliance check (PII, moderation, AI evaluation) that flags records; the parent pipeline decides what happens to flagged records
• Lookup cache -- account-level key-value store for fast in-memory reference lookups (cross-reference IDs, large translation tables, dedup markers)

How each surface is invoked

The three pipeline-carrying resources differ mainly in what starts them:

"Every night at 2 AM" or "when a webhook fires" always points at a flow. "Reachable from outside Celigo over HTTP" points at an API. "Reusable from multiple places inside Celigo" points at a tool (and a recipe needed both inside and outside is a tool exposed behind an API).

Build Order

Always build bottom-up. Resources reference each other, so dependencies must exist first:

1. Connection     (credentials for each system)
2. Export + Import (data source and destination steps, each referencing a connection)
3. Flow           (pipeline wiring exports to imports)

Never start by creating a flow -- its exports and imports must exist first, and those require connections.

At each layer, match the connector to the target application -- raw HTTP is the fallback, not the default. Use the application-specific adaptor when one exists (NetSuite, Salesforce, databases, FTP/S3); otherwise check for a pre-built HTTP connector (550+ apps: celigo http-connectors list); hand-write HTTP config only when neither covers the target. See [configuring-connections](../configuring-connections/SKILL.md#4-check-for-a-pre-built-connector-and-global-iclient) and the adaptor decision matrices in [configuring-exports](../configuring-exports/SKILL.md#adaptor-decision-matrix) / [configuring-imports](../configuring-imports/SKILL.md#adaptor-decision-matrix).

For APIs and tools, the same principle applies: build the connections, exports, and imports that the API/tool will use, then wire them into the API/tool definition.

<!-- TIER:2 -->

First Steps

0. Pick your surface: CLI or MCP

Skills in this pack show celigo ... CLI commands, but there are two equivalent ways to execute most operations:

• The Celigo CLI -- what the command blocks in these skills show.
• The Celigo Platform MCP server -- if your agent is connected to it, the same operations are MCP tools. Translate CLI blocks directly: list<type> / upsert<type> replace celigo <type> list|get|create|update, deleteresource replaces celigo <type> delete, and runflow, canceljob, listjobs, listflowerrors, listexecutionlogs, deploytemplate, and getschema cover running, monitoring, deploying, and schema lookups. The MCP server also has tools with no CLI equivalent, such as searchknowledgebase and triageflowerrors.

A few operations are CLI-only (no MCP tool): the local account index (celigo account snapshot|search|dependencies|lint), API-token management (celigo accesstokens ...), stacks, on-premise agents, and user management. For those, use the CLI, the integrator.io REST API, or the UI.

1. Configure the CLI

celigo config set api_token <your-token>       # Set your API bearer token
celigo config set base_url <url>               # Optional: override base URL for sandbox/EU
celigo config show                             # Verify configuration

The CLI accepts either token kind from Resources > API tokens as its bearer token: a personal access token (any user can generate one; inherits your own permissions; expires after 90 days by default) or an account API token (owner/admin-created, scopeable, long-lived -- prefer it for CI). See [managing-api-tokens](../managing-api-tokens/SKILL.md).

2. Build the Account Index

The account index is a local snapshot of all resources in your Celigo account. It enables fast search, dependency analysis, and linting without repeated API calls.

celigo account snapshot                        # Fetch all resources, build dependency graph
celigo account search <keyword>                # Find resources by name or keyword
celigo account dependencies <type> <id>        # Show what a resource uses and what uses it
celigo account lint                            # Find orphaned resources, offline connections, untriggered flows
celigo account stats                           # Resource counts by type

The index auto-refreshes when stale (default: 4 hours, configurable via CELIGOINDEXSTALE_HOURS). Commands that depend on the index refresh it automatically unless --no-refresh is passed.

3. Discover Before Building

Before creating new resources, always check what already exists:

• celigo account search "customer sync" -- find existing flows, exports, imports by keyword
• celigo account dependencies flow <id> -- see the full resource tree for an existing flow
• celigo account lint -- identify orphaned exports/imports you might reuse

Planning Discipline

Before writing any JSON or CLI commands, answer these questions:

What kind of operation is this?

• Modifying an existing resource's config (export settings, import mappings, scripts) -- work on the resource directly with celigo <type> set or celigo <type> get + edit + celigo <type> update. Don't rebuild the flow
• Modifying an existing flow's structure (add/remove steps, change schedule) -- GET the flow, modify the structure, PUT it back
• Building something new where every step is clear -- build directly, bottom-up
• Any ambiguity about what to build -- design first (see checklist below)

Design checklist (when ambiguity exists):

• What source systems? What destination systems?
• What data moves between them, in which direction?
• How often? (cron schedule, webhook trigger, on-demand)
• What happens when a step fails? (proceedOnFailure, error notifications)
• Do downstream steps need data from upstream responses? (response mapping)
• Is this a one-off or a reusable template? (abstract/instance flow)
• Sandbox or production? (never mix -- sandbox: true flows only use sandbox: true connections)

<!-- TIER:3 -->

Sandbox vs Production

Celigo enforces strict separation:

• A sandbox: true connection can only be used by sandbox: true flows
• A production (non-sandbox) connection can only be used by production flows
• Mixing sandbox and production resources will cause runtime errors

When testing, always create flows with disabled: true and verify before enabling.

Which Skill to Use

When No Skill Covers the Shape

The reference schemas shipped with these skills cover the high-stakes shapes where guessing corrupts data, not the whole API surface. When you need a field or resource no skill documents, use the live sources — in this order:

1. A real resource is ground truth. celigo <type> get <id> returns the exact wire shape; request bodies for create/update are exactly what GET returns. Copying a live resource beats any documentation.
2. The developer docs are agent-native and always current. Every API reference page is fetchable as markdown — append .md to any page URL (e.g. https://developer.celigo.com/api/api-reference/flows.md), start from the index at https://developer.celigo.com/llms.txt, or ask a direct question: GET https://developer.celigo.com/readme.md?ask=<question>;.
3. Prefer a shipped schema when one exists — schemas under each skill's references/ are synced from the API specs and reviewed before shipping, and their x-celigo-ai-guidance notes carry hazards the raw docs don't.