How to connect Celigo MCP with TypeScript

Data source steps (page generators) that fetch records from external systems. Each export is tied to a connection and defines what data to pull. adaptorType (e.g. HTTPExport, NetSuiteExport) determines the connector. Exports live inside flows as pageGenerators[]. Dual-purpose tool: omit `_id` to list the collection (optional `include`/`exclude` projection and pagination via `limit`/`cursor`); set `_id` to fetch the full resource configuration. Pagination and `include`/`exclude` are ignored when `_id` is set. Default list projection (when you omit include/exclude): lastModified,_connectionId,adaptorType,draft (plus _id and name from the API). Override with `include` or `exclude` as needed. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/exports

Create (omit `_id`; POST) or update (set `_id`; PUT) a export. Data source steps (page generators) that fetch records from external systems. Each export is tied to a connection and defines what data to pull. adaptorType (e.g. HTTPExport, NetSuiteExport) determines the connector. Exports live inside flows as pageGenerators[]. PUT is a full-document replace, not a patch — first fetch the current doc via `list_exports` with `_id`, modify it, and send the complete document (omitted fields may be cleared). Call `get_schema(target='resource', name='export')` for exact field requirements. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/exports

Data destination steps (page processors) that write records to external systems. Each import is tied to a connection and defines how to push data. adaptorType (e.g. HTTPImport, NetSuiteDistributedImport, AiAgentImport) determines the connector. Imports live inside flows as pageProcessors[]. Dual-purpose tool: omit `_id` to list the collection (optional `include`/`exclude` projection and pagination via `limit`/`cursor`); set `_id` to fetch the full resource configuration. Pagination and `include`/`exclude` are ignored when `_id` is set. Default list projection (when you omit include/exclude): lastModified,_connectionId,adaptorType (plus _id and name from the API). Override with `include` or `exclude` as needed. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/imports

Create (omit `_id`; POST) or update (set `_id`; PUT) a import. Data destination steps (page processors) that write records to external systems. Each import is tied to a connection and defines how to push data. adaptorType (e.g. HTTPImport, NetSuiteDistributedImport, AiAgentImport) determines the connector. Imports live inside flows as pageProcessors[]. PUT is a full-document replace, not a patch — first fetch the current doc via `list_imports` with `_id`, modify it, and send the complete document (omitted fields may be cleared). Call `get_schema(target='resource', name='import')` for exact field requirements. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/imports

Pipelines that move data from source (exports) to destination (imports). A flow contains pageGenerators[] (exports) and pageProcessors[] (imports/lookups), optionally with routers[] for branching. Flows can be scheduled via cron or triggered by webhooks. Always create flows with disabled: true until verified. Prefer `patch_flow` (JSON Patch) over `upsert_flow` PUT for toggling `disabled` or other single fields. For error triage, use list_flows with hasOpenErrors or includeErrorCounts before drilling into list_flow_errors. Dual-purpose tool: omit `_id` to list the collection (optional `include`/`exclude` projection and pagination via `limit`/`cursor`); set `_id` to fetch the full resource configuration. Pagination and `include`/`exclude` are ignored when `_id` is set. Default list projection (when you omit include/exclude): disabled,lastModified,_integrationId,schedule (plus _id and name from the API). Override with `include` or `exclude` as needed. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/flows

Create (omit `_id`; POST) or update (set `_id`; PUT) a flow. Pipelines that move data from source (exports) to destination (imports). A flow contains pageGenerators[] (exports) and pageProcessors[] (imports/lookups), optionally with routers[] for branching. Flows can be scheduled via cron or triggered by webhooks. Always create flows with disabled: true until verified. Prefer `patch_flow` (JSON Patch) over `upsert_flow` PUT for toggling `disabled` or other single fields. For error triage, use list_flows with hasOpenErrors or includeErrorCounts before drilling into list_flow_errors. PUT is a full-document replace, not a patch — first fetch the current doc via `list_flows` with `_id`, modify it, and send the complete document (omitted fields may be cleared). Call `get_schema(target='resource', name='flow')` for exact field requirements. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/flows

Run a flow — queues an on-demand execution and returns `_jobId`. Use `list_flow_runs` with `_id` set to that `_jobId` to poll status and inspect results (parent job + per-step children). The flow must be enabled (`disabled: false`) and belong to an enabled integration. Optional `body` parameters: - `export.startDate` / `export.endDate` — override the delta window for this run only (useful for backfills). - `_exportIds` — array of export ids to run only specific generators (useful for multi-source flows). Omit `body` or send `{}` to run with the flow's configured behavior. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/flows

List open errors for flow steps. Four modes: 1. With `_id` + `_stepId`: errors for a specific step (body-paginated, returns `{ errors, nextCursor?, hasMore }`) 2. With `_id` only: errors for all steps in that flow (grouped by step, each with its own nextCursor). Empty steps (no errors) are omitted. 3. With `_stepId` only: finds the flow containing that step, then returns errors for that step 4. Without `_id` or `_stepId`: errors across all flows, optionally filtered by `_integrationId`. Scans at most 100 flows per call. When more remain, the response includes `hasMore: true` and `nextCursor` — pass that `cursor` on the next call to continue. Also returns `scannedFlows` / `totalFlows` so clients know whether the account was fully scanned. `totalErrors` / `affectedFlows` cover only the flows scanned in this page. - Default (`summary` omitted or `true`): returns `{ summary: true, totalErrors, affectedFlows, flows: [...], scannedFlows, totalFlows, hasMore, nextCursor? }`. Only flows/steps with errors are included. Use this to locate problems, then drill into specific flows with mode 1 or 2. - `summary=false`: returns full error objects per step (same shape as modes 2-3) plus the same scan pagination fields. Empty flows and steps are omitted. Modes 2-3 (detail): `{ flows: [{ flowId, flowName, steps: [{ stepId, stepName, stepType, errors, nextCursor?, hasMore }] }] }`. Mode 4 detail adds top-level `scannedFlows`, `totalFlows`, `hasMore`, and optional `nextCursor` for the flow scan. Each step's `nextCursor` can be used with mode 1 (`_id` + `_stepId` + `cursor`) to fetch more errors for that step. Each error object includes: - `errorId` — use in `triage_flow_errors` actions: `resolve` (`errors`), `assign` (`errorIds`), `tag` (`errors[].id`) - `retryDataKey` — use in `triage_flow_errors` actions: `retry` (`retryDataKeys`), `tag` (`errors[].rdk`); also pass to `get_flow_error_retry_data` - `message`, `code`, `traceKey`, `occurredAt` — diagnostic info For the full retry snapshot, call `get_flow_error_retry_data` with `_id`, `_stepId`, and `retryDataKey`. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/flows

Get the stored retry-data snapshot for one error (`retryDataKey` from `list_flow_errors`). Returns the envelope the runtime captured at failure (`data`, `stage`, request/response fields where applicable). Use before `update_flow_error_retry_data` when fixing staged payload. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/flows

Full-replace of the stored retry-data snapshot for one error. Body is the complete envelope from `get_flow_error_retry_data` (mutate `data` as needed). Does not reprocess — call `triage_flow_errors` with action `retry` afterward. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/flows

Flow run execution logs (debug/trace). Requires `_id` (flow) and `_jobId` (parent job from `run_flow` or `list_flow_runs`). Flow must have debug logging armed (`logging.debugUntil` on the flow). Three modes: 1. **Index** — `_id` + `_jobId` only → `GET /v1/flows/{id}/jobs/{jobId}/logs`. Returns entries with `recordId`, `groupId`, `traceKey`, `_expOrImpId`. Optional client filters: `_stepId`, `traceKey` (substring). 2. **Metadata** — `_id` + `_jobId` + `_stepId` + `recordId` + `groupId` (+ optional `traceKey`) → `POST .../logs/metadata/query`. Step execution timeline without full payloads. 3. **Data** — same as metadata + `stage` → `POST .../logs/data/query`. Returns request/response payloads for one stage (can be large). Typical path: `run_flow` → `_jobId` → mode 1 → pick a row → mode 2 or 3. `traceKey` from `list_flow_errors` can narrow index results or enable cross-step trace in metadata mode. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/flows

Partially update a flow via JSON Patch (safer than `upsert_flow` PUT for one-field changes). Common disable/enable toggle: `body: [{ "op": "replace", "path": "/disabled", "value": true }]` Other whitelisted paths include `/name`, `/description`, `/schedule/cron`, `/logging/debugUntil` (ISO timestamp, max 1 hour ahead to arm debug logging). Unlisted paths return 422. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/flows

Credentials and configuration for external systems. Each connection holds auth details (API keys, OAuth tokens, etc.) and is shared across exports and imports. Name connections after the system, not the operation (e.g. 'Shopify - my-store', not 'Shopify - Customer Upsert'). The type field determines the connector (e.g. http, netsuite, salesforce). Dual-purpose tool: omit `_id` to list the collection (optional `include`/`exclude` projection and pagination via `limit`/`cursor`); set `_id` to fetch the full resource configuration. Pagination and `include`/`exclude` are ignored when `_id` is set. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/connections

Create (omit `_id`; POST) or update (set `_id`; PUT) a connection. Credentials and configuration for external systems. PUT is a full-document replace, not a patch — first fetch via `list_connections` with `_id`, modify, and send the complete document. SAFETY (PUT branch only): payloads containing the API's masked-credential placeholder (`******`) are rejected unless `force: true` is set, so a re-PUT of a previously read connection cannot wipe stored writeOnly secrets. To edit a non-credential field, omit credential fields from `body` entirely — Celigo preserves writeOnly values when they're absent from the PUT. Call `get_schema(target='resource', name='connection')` (or `connection/http`, etc.) for exact field requirements. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/connections

Top-level containers that group flows, connections, and resources into a logical project. Every flow belongs to an integration. Use list_integrations to see all projects in the account. Dual-purpose tool: omit `_id` to list the collection (optional `include`/`exclude` projection and pagination via `limit`/`cursor`); set `_id` to fetch the full resource configuration. Pagination and `include`/`exclude` are ignored when `_id` is set. Default list projection (when you omit include/exclude): mode,sandbox,lastModified,description (plus _id and name from the API). Override with `include` or `exclude` as needed. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/integrations

Create (omit `_id`; POST) or update (set `_id`; PUT) a integration. Top-level containers that group flows, connections, and resources into a logical project. Every flow belongs to an integration. Use list_integrations to see all projects in the account. PUT is a full-document replace, not a patch — first fetch the current doc via `list_integrations` with `_id`, modify it, and send the complete document (omitted fields may be cleared). Call `get_schema(target='resource', name='integration')` for exact field requirements. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/integrations

JavaScript hook scripts for data transformation and custom logic. Scripts are referenced by exports/imports via the hooks object (preSavePage, preMap, postMap, postSubmit, postResponseMap). The content field holds the JS code. Dual-purpose tool: omit `_id` to list the collection (optional `include`/`exclude` projection and pagination via `limit`/`cursor`); set `_id` to fetch the full resource configuration. Pagination and `include`/`exclude` are ignored when `_id` is set. Default list projection (when you omit include/exclude): lastModified (plus _id and name from the API). Override with `include` or `exclude` as needed. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/scripts

Create (omit `_id`; POST) or update (set `_id`; PUT) a script. JavaScript hook scripts for data transformation and custom logic. Scripts are referenced by exports/imports via the hooks object (preSavePage, preMap, postMap, postSubmit, postResponseMap). The content field holds the JS code. PUT is a full-document replace, not a patch — first fetch the current doc via `list_scripts` with `_id`, modify it, and send the complete document (omitted fields may be cleared). Call `get_schema(target='resource', name='script')` for exact field requirements. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/scripts

Celigo AI Agents (import steps with adaptorType AiAgentImport). Configure via `aiAgent` — provider (openai/gemini), model, system instructions, tools (Celigo tools and/or MCP). POST/PUT /v1/imports. Dual-purpose tool: omit `_id` to list the collection (optional `include`/`exclude` projection and pagination via `limit`/`cursor`); set `_id` to fetch the full resource configuration. Pagination and `include`/`exclude` are ignored when `_id` is set. Default list projection (when you omit include/exclude): lastModified,_connectionId,adaptorType (plus _id and name from the API). Override with `include` or `exclude` as needed. Note: results are filtered to adaptorType=AiAgentImport after pagination — a page can be empty while `hasMore: true`; keep paging with `nextCursor` until `hasMore` is false. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/ai-agents

Create (omit `_id`; POST) or update (set `_id`; PUT) a ai agent. Celigo AI Agents (import steps with adaptorType AiAgentImport). Configure via `aiAgent` — provider (openai/gemini), model, system instructions, tools (Celigo tools and/or MCP). POST/PUT /v1/imports. PUT is a full-document replace, not a patch — first fetch the current doc via `list_ai_agents` with `_id`, modify it, and send the complete document (omitted fields may be cleared). Call `get_schema(target='resource', name='ai-agent')` for exact field requirements. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/ai-agents

Guardrail resources — safety/compliance checks (PII, moderation, AI eval) implemented as import steps (`adaptorType=GuardrailImport`); they also appear in `list_imports`. Configure via `guardrail` — type (pii/ai_agent/…), rules, and optional BYOK connection. POST/PUT /v1/imports. Dual-purpose tool: omit `_id` to list the collection (optional `include`/`exclude` projection and pagination via `limit`/`cursor`); set `_id` to fetch the full resource configuration. Pagination and `include`/`exclude` are ignored when `_id` is set. Default list projection (when you omit include/exclude): lastModified,_connectionId,adaptorType (plus _id and name from the API). Override with `include` or `exclude` as needed. Note: results are filtered to adaptorType=GuardrailImport after pagination — a page can be empty while `hasMore: true`; keep paging with `nextCursor` until `hasMore` is false. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/guardrails

Create (omit `_id`; POST) or update (set `_id`; PUT) a guardrail. Guardrail resources — safety/compliance checks (PII, moderation, AI eval) implemented as import steps (`adaptorType=GuardrailImport`); they also appear in `list_imports`. Configure via `guardrail` — type (pii/ai_agent/…), rules, and optional BYOK connection. POST/PUT /v1/imports. PUT is a full-document replace, not a patch — first fetch the current doc via `list_guardrails` with `_id`, modify it, and send the complete document (omitted fields may be cleared). Call `get_schema(target='resource', name='guardrail')` for exact field requirements. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/guardrails

Celigo API resources — custom HTTP endpoints you publish so external systems can invoke a flow/tool synchronously over REST. Dual-purpose tool: omit `_id` to list the collection (optional `include`/`exclude` projection and pagination via `limit`/`cursor`); set `_id` to fetch the full resource configuration. Pagination and `include`/`exclude` are ignored when `_id` is set. Default list projection (when you omit include/exclude): lastModified (plus _id and name from the API). Override with `include` or `exclude` as needed. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/apis

Create (omit `_id`; POST) or update (set `_id`; PUT) a api. Celigo API resources — custom HTTP endpoints you publish so external systems can invoke a flow/tool synchronously over REST. PUT is a full-document replace, not a patch — first fetch the current doc via `list_apis` with `_id`, modify it, and send the complete document (omitted fields may be cleared). Call `get_schema(target='resource', name='api')` for exact field requirements. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/apis

Account environments (sandbox/staging). Feature-gated: accounts without multi-environment return an empty list + `_warning` (not an error). See each integration's `sandbox` flag for classic sandbox membership. Dual-purpose tool: omit `_id` to list the collection (optional pagination via `limit`/`cursor`); set `_id` to fetch the full resource configuration. Pagination is ignored when `_id` is set. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/environments

iClient resources — shared OAuth2 app registrations (client id/secret, token URI) that connections reference to authenticate. On PUT, resend `oauth2.clientSecret` as `******` (or omit it) to keep the existing secret — unlike connections, the mask is a keep-sentinel, not a wipe. Dual-purpose tool: omit `_id` to list the collection (optional pagination via `limit`/`cursor`); set `_id` to fetch the full resource configuration. Pagination is ignored when `_id` is set. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/iclients

Create (omit `_id`; POST) or update (set `_id`; PUT) a iclient. iClient resources — shared OAuth2 app registrations (client id/secret, token URI) that connections reference to authenticate. On PUT, resend `oauth2.clientSecret` as `******` (or omit it) to keep the existing secret — unlike connections, the mask is a keep-sentinel, not a wipe. PUT is a full-document replace, not a patch — first fetch the current doc via `list_iclients` with `_id`, modify it, and send the complete document (omitted fields may be cleared). Call `get_schema(target='resource', name='iclient')` for exact field requirements. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/iclients

In-memory key-value stores for lookups and deduplication. Use `list_lookup_caches` (Phase 1) to find a cache `_id`; `upsert_lookup_cache` (Phase 2) creates the cache resource. Dual-purpose tool: omit `_id` to list the collection (optional pagination via `limit`/`cursor`); set `_id` to fetch the full resource configuration. Pagination is ignored when `_id` is set. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/lookup-caches

Create (omit `_id`; POST) or update (set `_id`; PUT) a lookup cache. In-memory key-value stores for lookups and deduplication. Use `list_lookup_caches` (Phase 1) to find a cache `_id`; `upsert_lookup_cache` (Phase 2) creates the cache resource. PUT is a full-document replace, not a patch — first fetch the current doc via `list_lookup_caches` with `_id`, modify it, and send the complete document (omitted fields may be cleared). Call `get_schema(target='resource', name='lookup-cache')` for exact field requirements. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/lookup-caches

Read entries from an existing lookup cache. Requires cache `_id` from `list_lookup_caches`. Omit filters for the first page (~1000 entries); pass `key` (single entry), `keys` (array), or `startsWith` (prefix). Response includes `data[]` with `value` or `error` per key. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/lookup-caches

Load or replace entries in an existing lookup cache. Body: `{ data: [{ key, value }, ...] }`. Automatically splits into batches of 1000 entries (API limit per request). Returns merged per-key results; includes `batches` when more than one request was sent. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/lookup-caches

Remove entries from a lookup cache. Pass `key` or `keys` to delete specific entries (`DELETE .../data` with `{ keys }`). To purge **every** entry, set `all: true` (calls `.../data/purge`; cache resource is kept). Omitting keys without `all: true` is rejected. Does not delete the cache itself — use `delete_resource` for that. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/lookup-caches

Celigo Tool resources — reusable integration building blocks (lookups/imports/transforms behind an input/output contract) stored in your account. NOT the MCP tool list. Dual-purpose tool: omit `_id` to list the collection (optional `include`/`exclude` projection and pagination via `limit`/`cursor`); set `_id` to fetch the full resource configuration. Pagination and `include`/`exclude` are ignored when `_id` is set. Default list projection (when you omit include/exclude): lastModified (plus _id and name from the API). Override with `include` or `exclude` as needed. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/tools

Create (omit `_id`; POST) or update (set `_id`; PUT) a tool. Celigo Tool resources — reusable integration building blocks (lookups/imports/transforms behind an input/output contract) stored in your account. NOT the MCP tool list. PUT is a full-document replace, not a patch — first fetch the current doc via `list_tools` with `_id`, modify it, and send the complete document (omitted fields may be cleared). Call `get_schema(target='resource', name='tool')` for exact field requirements. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/tools

Celigo-hosted MCP server resources your account publishes to external AI agents — not this server. Dual-purpose tool: omit `_id` to list the collection (optional `include`/`exclude` projection and pagination via `limit`/`cursor`); set `_id` to fetch the full resource configuration. Pagination and `include`/`exclude` are ignored when `_id` is set. Default list projection (when you omit include/exclude): lastModified (plus _id and name from the API). Override with `include` or `exclude` as needed. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/mcp-servers

Create (omit `_id`; POST) or update (set `_id`; PUT) a mcp server. Celigo-hosted MCP server resources your account publishes to external AI agents — not this server. PUT is a full-document replace, not a patch — first fetch the current doc via `list_mcp_servers` with `_id`, modify it, and send the complete document (omitted fields may be cleared). Call `get_schema(target='resource', name='mcp-server')` for exact field requirements. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/mcp-servers

Dual-purpose job inspector. **Get job family** (recommended): Set `_id` to a parent flow job id to fetch the complete run — returns the parent job plus `children[]` with per-step export/import results, status, timing, and record counts. Set `includeFiles: true` with `_id` to also fetch short-lived S3 presigned download URLs (`signedURLs[]`) for the parent and each child job via `POST /v1/jobs/{id}/files/signedURL`. URLs expire in ~15 minutes — fetch file bytes immediately with HTTP GET, do not persist. Jobs with no files get `signedURLs: []`. Ignored when `_id` is omitted. **List historical flow runs**: Omit `_id` and set `type`. For `flow`, `retry`, or `bulk_retry`, also provide `_integrationId` or `_flowId`. For `export` or `import`, also provide `_flowJobId` or `_parentJobId`. Defaults to `limit=25` when omitted. To list queued/running/canceling jobs, use `list_current_jobs` instead. Each job includes: `status` (queued/running/completed/failed/cancelled), timing (`startedAt`, `endedAt`, `createdAt`), and record counts (`numSuccess`, `numError`, `numOpenError`). List-only filters are ignored when `_id` is set. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/jobs

List currently in-progress jobs via `POST /v1/jobs/current`. Returns only queued, running, or canceling jobs as `{ items, hasMore, nextCursor? }`; terminal jobs belong in `list_flow_runs`. Optional `body` filters: `_flowIds`, `_integrationIds`, `status` (array containing queued/running/canceling), `applicationIds`, `category`, `time_gt`, and `time_lte`. The server always sends `sandbox: false`. Pass `nextCursor` back as `cursor` to fetch the next page. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/jobs

Cancel a queued/running flow run by job `_id` (from `run_flow`'s `_jobId` or `list_flow_runs`). Cancelling a parent flow job cancels its child export/import jobs. Finished jobs return a no-op/error from the API. Returns the updated job record. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/jobs

List all error tags in the account. Use each entry's `tagId` short code (not Mongo `_id`) in `triage_flow_errors` (`tagIds` on action `tag`). Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/tags

List audit log entries (newest first). Returns a page `{ items, hasMore, paginationNote }` where each item includes `resourceType`, `_resourceId`, `fieldChanges[]` (fieldPath, oldValue, newValue), `byUser`, and `time`. Defaults to `limit=50` when omitted (API max 1000). Filter by `resourceType` (and optional `_resourceId`), `_byUserId` (or `support` for Celigo support), and date range (`from`, `to` ISO-8601). Optional `source`, `action`. Page forward in time using `to` — see `paginationNote` in the response. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/audit-logs

EDI interchange envelope profiles for B2B Manager (X12 ISA/GS and EDIFACT UNB control fields). Define sender/receiver IDs, qualifiers, and standards versions used when exchanging EDI documents with trading partners. Required to configure B2B EDI flows. Dual-purpose tool: omit `_id` to list the collection (optional pagination via `limit`/`cursor`); set `_id` to fetch the full resource configuration. Pagination is ignored when `_id` is set. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/edi-profiles

Create (omit `_id`; POST) or update (set `_id`; PUT) a edi profile. EDI interchange envelope profiles for B2B Manager (X12 ISA/GS and EDIFACT UNB control fields). Define sender/receiver IDs, qualifiers, and standards versions used when exchanging EDI documents with trading partners. Required to configure B2B EDI flows. PUT is a full-document replace, not a patch — first fetch the current doc via `list_edi_profiles` with `_id`, modify it, and send the complete document (omitted fields may be cleared). Call `get_schema(target='resource', name='edi-profile')` for exact field requirements. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/edi-profiles

File structure and parsing rules for structured files (CSV, fixed-width, EDI X12, EDI EDIFACT). Exports and imports reference a file definition to control how rows, columns, segments, and elements are parsed or generated. Required alongside EDI profiles when building B2B flows. Dual-purpose tool: omit `_id` to list the collection (optional `include`/`exclude` projection and pagination via `limit`/`cursor`); set `_id` to fetch the full resource configuration. Pagination and `include`/`exclude` are ignored when `_id` is set. Default list projection (when you omit include/exclude): lastModified,format,version (plus _id and name from the API). Override with `include` or `exclude` as needed. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/file-definitions

Create (omit `_id`; POST) or update (set `_id`; PUT) a file definition. File structure and parsing rules for structured files (CSV, fixed-width, EDI X12, EDI EDIFACT). Exports and imports reference a file definition to control how rows, columns, segments, and elements are parsed or generated. Required alongside EDI profiles when building B2B flows. PUT is a full-document replace, not a patch — first fetch the current doc via `list_file_definitions` with `_id`, modify it, and send the complete document (omitted fields may be cleared). Call `get_schema(target='resource', name='file-definition')` for exact field requirements. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/file-definitions

Query the B2B Manager EDI transaction log. Dual-purpose: omit `_id` to list (POST /v1/ediTransactions/query); set `_id` to return one transaction (scans the query log). With `_id`, list defaults (`fileType=X12`, `limit=100`, 30-day `startDate`) are not applied; optional filters you pass (`fileType`, `documentType`, `startDate`, …) narrow the scan. `fileType` is the EDI standard family (`X12` or `EDIFACT`, default `X12`). `documentType` is the specific document code (X12: `"850"`, `"810"`, `"997"`; EDIFACT: `"ORDERS"`, `"INVOIC"`, …). **`X12` and `EDIFACT` are not valid `documentType` values** — the API rejects them. Defaults: `fileType=X12`, `limit=100`, `startDate` = last 30 days. Dates accept ISO-8601 strings or epoch milliseconds. Set `includeFaDetails` and/or `includeMdn` to fetch extra GETs (`/faDetails`, `/mdn`) per returned transaction — one (or two) additional API call **per row** on the current page, run in parallel. With default `limit=100` and both flags set, that can mean 1 query POST plus up to 200 GETs. Prefer `_id` for a single transaction, or use a smaller `limit`, when you need FA/MDN detail on list results. FA details require `fileType` on the record (from the query result or your `fileType` arg). Set `includeFiles: true` **with `_id`** to obtain a short-lived presigned URL for that transaction's raw EDI file. The tool uses the transaction's `_flowJobId` and `s3Key` to call `POST /v1/jobs/{_flowJobId}/files/signedURL` with `{ "fileIds": ["<s3Key>"] }`, then attaches the result as `ediFileSignedURL`. The URL expires in ~15 minutes — fetch the file promptly with HTTP GET and do not persist the URL. This returns only the URL, not the EDI text, so file content does not consume the model context. Rejected without `_id` to prevent signed-URL fan-out across a list page. List mode always returns `{ ediTransactions, hasMore, nextCursor? }`. Use `nextCursor` from the response as `cursor` on the next call (maps to API `pageToken`). Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/edi-transactions

Update functional-acknowledgement status on a batch of EDI transactions (PATCH /v1/ediTransactions). Body: `{ "fileType": "X12"|"EDIFACT", "ediTransactions": [{ "_id": "...", "faStatus": "accepted"|"rejected" }, ...] }`. Only `accepted` and `rejected` are writable — other `faStatus` values are system-managed and records are silently skipped. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/edi-transactions

Browse the published marketplace catalog or preview one template's full blueprint. **List** (omit `_id`): `POST /v1/published/combined` sorted by `numInstalls` (default). The API returns the **full published catalog** in one call; `docType` and `includeConnectors` filter that result client-side (the upstream API has no server-side type filter). Returns lightweight rows `{ _id, name, description, summary }` where `summary` carries `docType`, `numInstalls`, `applications`, and `lastModified`. **Templates only by default** — Connectors (integration apps) are excluded unless `includeConnectors` is true or `docType` is set. Prefer preview mode (`_id` set) when you already know which template you need. **Preview one template** (set `_id`): `GET /v1/templates/{_id}/preview` — full install blueprint (`objects[]` with `{ model, doc }` per resource, plus `stackRequired`). Use Connection entries' `_id` values to build `connectionMap` for `install_template`. Only works for `docType=Template` marketplace ids — Connector ids return 404. Distinct from account-owned template CRUD at `/v1/templates` (partner publishing); this tool targets the **published** catalog only. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/marketplace

Browse or search Celigo Storage (managed files & folders). Three modes: **List** (default): returns the direct children of one folder plus a `breadcrumb` of the path. Set `_parentId` to a folder id, or omit it for the account root. **Search**: set `search` (min 2 chars) to recursively match file/folder names across the whole account (case-insensitive substring; matches names only, not file contents). Each hit carries its containing folder as `location`. `_parentId` is ignored. Newly created/renamed items can take a few seconds to appear in search results. **Recycle bin**: set `deleted: true` to list soft-deleted items (newest deletion first; only items deleted directly — descendants removed by a folder delete are hidden and travel with their parent). Each entry carries `deletedAt`/`deletedBy` and stays recoverable for 30 days. Recover with `restore_storage_item`. Other filters do not apply in this mode. There is no get-one-by-id mode — to inspect a single item, list its parent folder or search its name. Each item: `{ _id, type: "file"|"folder", name, size, mimeType, status, isSystem, createdAt, lastModified }`. `status: "pending"` means an upload/replace has not finalized yet (flips to "active" within seconds; until then the file cannot be downloaded, moved, or renamed). `isSystem: true` items are platform-managed and reject mutation. Use an item's `_id` with `upsert_storage_item` (modify), `get_storage_file_download_url` (fetch file content), or `delete_resource` with resourceType "storage-items" (soft delete to the recycle bin; recover with `restore_storage_item`). Returns `{ items, breadcrumb?, nextCursor?, hasMore }` — pass `nextCursor` back as `cursor` for the next page (filters are carried inside the cursor). Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/file-storage

Restore a soft-deleted Celigo Storage item from the recycle bin back to its original location. Find recycle-bin ids with `list_storage_items` (`deleted: true`); items are recoverable for 30 days after deletion. Restoring a folder also brings back the descendants deleted with it — the folder returns immediately and its contents follow asynchronously, so a listing taken right after may be briefly incomplete. A descendant removed by its parent's deletion cannot be restored on its own; restore that parent folder instead. Returns `{ restored, _id, item? }`. Permanent purge is not exposed via MCP. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/file-storage

Get a short-lived presigned URL for one Celigo Storage file's content. Returns `{ downloadUrl, expiresIn }` (seconds the URL stays valid). Fetch the bytes with a plain HTTP GET on that URL — no auth header needed; the content does not pass through this tool or the model context. The URL grants access to anyone holding it until it expires, so hand it to the user or fetch it promptly rather than persisting it. Files only: folders and still-`pending` uploads have no content to download. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/file-storage

Abort an abandoned pending multipart **create** upload, discard uploaded parts, and release its reserved quota. Do not call this for `presignedUpload.operation: "replace"`: the upstream cancel API hard-deletes the pending item and may delete the existing file instead of restoring its previous content. Single-PUT uploads do not use cancellation. If S3 completion already succeeded, storage activates the item and rejects cancellation because it is no longer pending. Returns `{ cancelled: true, _id }` on success. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/file-storage

Install a published marketplace template, creating a new integration (POST /v1/integrations/template/{_id}). **Requires `connectionMap`** in `body`: maps each template Connection `_id` (from `list_marketplace(_id)` preview `objects` where `model=Connection`) to a real connection `_id` in your account. Example: `{ "connectionMap": { "61f92026dd053843b5d72350": "64a1234567890abcdef12345" } }` Run `list_marketplace` with `_id` first to discover which connections the template expects and to review example flow/export/import configs before deploying. **Response:** On success the API returns either: - `{ "_integrationId": "<id>" }` — most common; use this id with `list_integrations`, `list_flows`, etc., or - An array of created resources `[{ "model": "Integration", "_id": "..." }, { "model": "Flow", "_id": "..." }, ...]` — find the entry with `model: "Integration"` and use its `_id` as the new integration id. There is no top-level `_id` on the object form; do not assume the response is the integration document itself. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/templates

Delete a resource by `_id`. Pass `resourceType` to select the resource family (allowed values: exports, imports, flows, connections, integrations, scripts, ai-agents, guardrails, async-helpers, apis, iclients, lookup-caches, tools, mcp-servers, edi-profiles, file-definitions, storage-items). A dependency pre-flight runs for every resource type first and dependents are returned in `warnings[]` — but the delete **always proceeds** (warnings are advisory only; the scan is best-effort). Returns `{ deleted, id, warnings, response }`. The `force` flag is reserved for future blocking behavior; today it is a no-op. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference

**Essential companion to upsert_* tools.** Returns exact field structures, required properties, enum values, and array vs object distinctions. Call BEFORE creating or updating resources to avoid validation errors. **Targets:** `target='resource'` — Platform resource schemas (flow, export, import, connection, script, etc.). Use 'resource/sub' for adaptor-specific shapes (e.g., 'connection/netsuite', 'import/http'). Examples: `get_schema(target='resource', name='flow')` before `upsert_flow`. `target='connector'` — **Discover fields before building an export.** Two modes: - Pass a **connection `_id`** (NetSuite, Salesforce, RDBMS, etc.) to retrieve native application metadata — record types, fields, picklist values. This is the "what can I pull from this system?" discovery step before constructing export queries. - Pass an **HTTP connector ID or name** to get catalog connector definitions. `target='connector_openapi'` — OpenAPI document fragment for an HTTP connector's REST surface. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference

Search the Celigo Knowledge Base and get AI-generated answers about integrator.io. Returns `{ answer, sources[], thread_id }`. Use for how-to/product questions; use `get_schema` (not this) for exact field schemas before upsert_*. Uses RAG (Retrieval-Augmented Generation) to search relevant documentation (help center, community, guides) and synthesize answers. Supports conversational follow-ups using thread_id for context continuity. Enable context_aware mode with a url parameter to get answers specific to a UI location. Queries the Celigo Knowledge Base — see https://docs.celigo.com

List every user in the current account: the account **owner** (prepended, `accessLevel: "owner"`) plus all invited/shared users from the account-share list (`ashares`). Works for both sign-in cases — account owner and shared user acting in the account — because the API resolves the effective account server-side. **Requires account owner or administrator access** (403 otherwise). Use this to discover valid assignees for `triage_flow_errors` (action `assign` takes an `email`) and to get the `_ashareId` handle needed by `manage_user` (`update_permissions` / `disable` / `enable`). Each item: `_id` (user id), `email`, `name` (hidden by the platform for pending invites), `accessLevel` (`owner` | `administrator` | `manage` | `monitor` | `tile`), `integrationAccessLevel` (per-integration grants), `status` (`accepted` | `pending` | `dismissed` | `disabled`), `_ashareId` (absent for the owner row), `lastSignIn`. The owner's `email` can be `null` when the platform exposes no profile endpoint for the token; invitee emails are always present. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/users

Perform one account-user management action. **Admin-only** (account owner or administrator); `update_permissions` and `disable` carry blast radius — confirm with the user before calling. Actions: - `invite` — requires `email`; optional `body` `{ accessLevel, integrationAccessLevel }`. Invites a user into the account (`POST /v1/invite`). One user per call. - `update_permissions` — requires `_ashareId` (from `list_users`) and `body` with at least one of `accessLevel` (`administrator` | `manage` | `monitor`) or `integrationAccessLevel` (`[{ _integrationId, accessLevel }]`). The platform enforces who may change account-level users. - `disable` — requires `_ashareId`. Revokes the user's access (kept in the list, `status: "disabled"`). No-op with `changed: false` if already disabled. - `enable` — requires `_ashareId`. Re-enables a previously disabled user. No-op with `changed: false` if already enabled. The owner cannot be managed (owner has no `_ashareId`). Disabling requires the invite to be accepted and not dismissed; the platform also blocks disabling a production admin from a non-production environment. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/users

Create or update a Celigo Storage item (file or folder). Omit `_id` to create; pass `_id` (from `list_storage_items`) to update. The operation is chosen from the fields you send. **Create** (no `_id`): - Folder: `type: "folder"` + `name` (+ optional `_parentId`, `description`). - File: `name` + `content` (UTF-8 text — CSV/JSON/XML/etc.) **or** `contentBase64` (binary, base64) (+ optional `_parentId`, `mimeType`). The server transfers the bytes to storage for you. A name that already exists in the destination folder is rejected — pass the existing item's `_id` instead to replace it. `description` cannot be set in the same call as a new upload (the item is still pending); apply it afterwards with `_id` + `description`. **Update** (with `_id`) — fields can be combined in one call: - Rename / edit description: `name` and/or `description`. - Move: `_parentId` (destination folder id, or `null` for the account root). - Replace file content: `content` or `contentBase64` (files only; the item's `_id`, placement, and references are preserved). **Direct upload from local disk**: use `presignedUpload` instead of `content`/`contentBase64`. The tool initiates a single or multipart create/replace and returns presigned S3 transfer instructions; the client streams bytes directly from disk to those URLs without a Celigo Authorization header and includes any returned `requiredHeaders`. For multipart, retain each part's ETag and POST ordered S3 completion XML to `completeUrl`. Use `stage: "continue"` to request the next part-URL batch through the deployed initiate/replace resumption contract; `refresh-urls` is not deployed. Abandon a pending multipart create with `cancel_storage_upload`. Never cancel a replacement: upstream may hard-delete the existing file instead of restoring its prior content. Inline content is size-capped (default 4 MB). After a file create or content replace the item is `status: "pending"` and finalizes to "active" asynchronously (usually within seconds); until then it cannot be downloaded, moved, or renamed. Metadata-only changes apply immediately. When combining updates, metadata changes are applied before content replacement. Presigned URLs are temporary credentials: consume them promptly and never print, log, or persist them. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/file-storage

Perform one flow-step error action. Requires `_id` (flow), `_stepId` (export/import id), and `action`. Pass `body` for targeted ops, or `resolveAll` / `retryAll` to act on every open error for the step (platform bulk endpoints — do not enumerate ids in the MCP layer). Field mapping from `list_flow_errors` response: - `errorId` — unique error identifier, use in `resolve` and `assign` actions - `retryDataKey` (alias `rdk`) — retry snapshot key, use in `retry` and `tag` actions Actions: - `retry` — body `{ retryDataKeys: [...] }` **or** `retryAll: true` — reprocess errors (**writes to destinations; confirm with user first**) - `resolve` — body `{ errors: [...] }` **or** `resolveAll: true` — mark errors as resolved/handled - `tag` — `{ errors: [{ id, rdk }, ...], tagIds: [...] }` — apply tags (codes from `list_tags`) - `assign` — `{ errorIds: [...], email: "..." }` — assign errors to a user Typical workflow: `list_flow_errors` → (optional) `get_flow_error_retry_data` / `update_flow_error_retry_data` → `triage_flow_errors`. Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference/flows

Submit product feedback about the Celigo CLI or platform MCP experience (`POST /v1/feedbacks`). Use when the user (or you) wants to report a bug, confusion, missing capability, docs issue, praise, or other product signal tied to a command or MCP tool. Required: `source`, `version`, `category`. Optional free-text (`command`, `expected`, `actual`, `message`) is secret-scrubbed server-side — still avoid putting tokens or secrets in the body. `context` is auto-collected env only (os/node/mode/exitCode); never include argv or PII. Identical submissions (same acting user + source/command/category/expected/actual) within a 10-minute window collapse to the original id with `deduped: true` (`message`/`version`/`severity` do not affect dedup). Returns `{ id, deduped? }`. Set `dry_run: true` to validate without persisting (`{ valid: true, errors: [] }`). Calls the Celigo integrator.io REST API — see https://developer.celigo.com/api/api-reference