Name: getting-started
Author: celigo

Orientation for Celigo integrations -- core concepts, build order, account discovery, planning discipline, sandbox awareness, and which skill to use for each task. Start here when the task is unclear or the user is new to Celigo.

<! 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) Sync a Celigo Data Ingestion pipeline that replicates many tables from one source application into a data warehouse, with a historical backfill and schema drift handling. It isn't a flow: it has no steps and lives in its own kind of integration ([building syncs](../building syncs/SKILL.md)) Topic an Event Streams channel: a publisher step turns records into messages, and every listener flow receives all of them from its own position ([configuring topics](../configuring topics/SKILL.md)) Celigo Storage file and folder storage built into the account, shared by flows, MCP servers, trading partners on the hosted SFTP server, and people ([managing file storage](../managing file storage/SKILL.md)) How each surface is invoked The three pipeline carrying resources differ mainly in what starts them: Resource Started by Schedule/listeners Runtime controls Flow Itself cron schedule, listener/webhook, or another flow chaining into it Yes Yes ( proceedOnFailure , skipRetries , chaining, ...) API An external HTTP caller; the request IS the source record No No errors land on the fail response; retries are the caller's concern Tool A consumer flow step, AI agent, API, MCP server, or another tool No No the consumer decides error behavior "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: Never start by creating a flow its exports and imports must exist first, and those require connections. Every flow belongs to an integration: pick the one the work belongs to (or create it) and set integrationId on each flow. Without it the flow lands in the account's "Standalone flows" integration, or the create fails with 422 standalone flows not supported . 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 match <url or name finds the one for an API and what its connection form needs list is abridged, with no base URIs or auth); 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. Undo in reverse. Keep a list of every resource you create (type, id , name) and report it when you finish. To take a build down, delete in the reverse order flows, then exports and imports, then scripts and connections, then iClients, and the integration last. A delete is refused (422, naming each blocker) while something still uses the resource: a connection while an export, import or flow uses it, an integration while it holds a flow. A resource deleted to the recycle bin still blocks deleting an iClient it uses and purging anything it points at, so purge in the same order. <! TIER:2 First Steps 0. Pick your surface: CLI or MCP There are two ways to run the operations these skills describe: The Celigo CLI ( celigo ... ). The Celigo Platform MCP server if your agent is connected to it, the operations are MCP tools: list <type lists a resource family or, with an id , reads one document; upsert <type creates (no id ) or replaces a whole document (with id ); patch flow changes whitelisted flow fields in place; and delete resource deletes. run flow , cancel flow run , list flow runs , list current jobs , list flow errors , triage flow errors , list execution logs , install template , and get schema cover running, monitoring, error handling, deploying, and schema lookups; list users / manage user cover users, and search docs covers celigo docs search . A skill with a references/mcp.md and references/cli.md describes each step by what it reads or changes and keeps the exact calls in those two files read the one that matches your tools. Skills without them still show celigo commands; on MCP, map each command onto the tools above: list <type / upsert <type replace celigo <type list get create update , delete resource replaces celigo <type delete , and triage flow errors covers celigo flows retry errors resolve errors assign errors tag errors . Change a single flow field with patch flow rather than a read and a full upsert flow ; no other resource has a patch tool. Some operations have no MCP tool: the local account index ( celigo account snapshot search dependencies lint ), stacks, on premise agents, test runs of flows, tools and APIs, integration and flow clones, integration revisions and snapshots, connection pings and debug logs, export and import invokes, processor runs (Handlebars, filters, file parsers), notifications, long runtime alerts, event reports, and the recycle bin ( celigo recycle bin restore purge ; the MCP server restores only Celigo Storage files and folders). For those, use the CLI, the integrator.io REST API, or the UI. API tokens are managed only in the UI there is no CLI command or MCP tool, and the REST endpoints refuse bearer token callers (see [managing api tokens](../managing api tokens/SKILL.md where tokens are managed)). Syncs ([building syncs](../building syncs/SKILL.md)), Event Streams topics ([configuring topics](../configuring topics/SKILL.md)), network policies ([managing network policies](../managing network policies/SKILL.md)), end users with their groups and roles ([managing end users](../managing end users/SKILL.md)), and Storage Query and the hosted SFTP file server ([managing file storage](../managing file storage/SKILL.md); Celigo Storage files and folders do have MCP tools) have no MCP tools either, and each of those skills' references/mcp.md says what the server can still do around them. 1. Configure the CLI The person sets up the credential, in their own terminal not the agent: Never ask for a token in chat or put one on a command line you run; a token pasted into the conversation is compromised ask the person to replace it ([managing api tokens](../managing api tokens/SKILL.md)). The base URL selects only the region: https://api.integrator.io by default, or https://api.eu.integrator.io , https://api.au.integrator.io , or https://api.ca.integrator.io , given when the profile is made ( celigo base url <url login , or profile add <name api base url <url ; a signed in profile keeps its session's host). The credential selects the account and environment a sandbox has its own token at the same host and celigo profile whoami names the account and environment a profile reaches. A profile's API token can be either kind from Resources API tokens : a personal access token (administrators, manage, and monitor users each generate their own the account owner can't; 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; the only kind the owner can have). See [managing api tokens](../managing api tokens/SKILL.md). Which account the CLI targets. The CLI keeps one profile per account or environment ( celigo profile list ; each holds its own token). Every command resolves its profile as profile CELIGO PROFILE the machine wide active profile that celigo profile use <name selects. A person switching with profile use moves every session that did NOT pin a profile a session still passing profile <name keeps hitting <name . An agent once carried a stale profile for a day and wrote flows into another customer's account while the person believed their switch had moved it. Rules: 1. Confirm the target before the first write of a session run celigo profile whoami , and read the celigo: profile '<name ' → <host line every write prints on stderr. If it names a profile other than the one the user means, stop and ask. 2. Do not pass profile unless the user asked for that specific profile in this request. Work on the active profile. If a session must stay on one account, bind it once with export CELIGO PROFILE=<name rather than repeating the flag a repeated flag is how a stale value survives a switch. 3. (pinned with profile; the active profile is '<other ') on a stderr line is a stop sign (CLI 2026.9.2 and later, printed on reads too): the person switched profiles and your pin did not follow. Ask which account they mean before the next command. Under profile pin policy = strict the CLI refuses such a command outright do not run celigo profile use , change profile pin policy , or edit ~/.celigo/config.json to get past it; which account a machine targets is the person's decision, never the agent's. A machine wide policy file can force strict too ( /etc/celigo/policy.json , or %ProgramData%\Celigo\policy.json on Windows); the CLI never changes it, and neither do you. 4. Never run config set api token or profile use in response to an error. Profile 'x' does not exist means the NAME is wrong, not the token; celigo profile list shows what exists pick from it, never guess a name. 2. Build the Account Index The account index is a local snapshot of the account's resources the ones your credential may read. It enables fast search, dependency analysis, and linting without repeated API calls. The index auto refreshes when stale (default: 15 minutes, configurable via CELIGO INDEX STALE MINUTES ). 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