Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

apis

Celigo APIs are custom HTTP endpoints that let external systems push data into, or query data through, Celigo integrations synchronously — the caller gets a structured response back in the same request.

REST API: APIs

celigo apis <subcommand> [args] [flags]

Supports all global flags.

Subcommands

Subcommand
Purpose

list

List all APIs, with optional --name and --disabled server-side filters.

get <id>

Fetch one API by ID.

create

Create an API from a JSON body (--file <path> or stdin).

update <id>

Full-replace an API from a JSON body (--file <path> or stdin); destructive PUT.

set <id> key=value …

Safe field edit: whitelisted fields via atomic PATCH, others GET → modify → PUT. Supports key=file://<path>.

delete <id>

Delete an API.

dependencies <id> (alias used-by)

List resources that depend on this API.

audit <id>

Show the API's audit log (change history).

logs <id>

List recent inbound request logs for an API.

log-detail <id> <key>

Fetch full request/response detail for one log entry.

request-history <id>

List the API's logged request executions — the run index.

execution-logs <apiId> <executionId>

Print one request execution's log (the trace view); --details assembles the full picture.

delete-execution-logs <id>

Queue deletion of stored execution logs in a date range.

clone <id>

Clone a builder-mode API (and its copied export/import resources). --dry-run checks the target route only.

download <id>

Download a builder-mode API and everything it references as a template ZIP.

add-processor <id> <exportOrImportId>

Add a page processor (export or import) to a builder-mode API branch.

remove-processor <id> <exportOrImportId>

Remove a page processor from a builder-mode API branch.

set-group <apiGroupingId> <apiIds...>

Assign one or more APIs to an API group.

unset-group <apiIds...>

Remove one or more APIs from their group.

test-run <id>

Start a test run and return stage-by-stage results.

test-run-step-results <id> <runId> <exportOrImportId>

Get stage-by-stage results for a single test-run step.

test-run-step-logs <id> <runId> <exportOrImportId>

List HTTP request/response logs for a test-run step.

debug-requests <id> <exportOrImportId>

List debug request log entries for an export or import inside the API.

debug-request-detail <id> <exportOrImportId> <key>

Fetch full request/response detail for a debug log entry.

celigo apis list

List all APIs visible to the current profile, with optional server-side filters.

Signature

Arguments

None.

Flags

Flag
Type
Default
Description

--name <substring>

string

—

Filter by name — a server-side substring match, not exact. Added in celigo-cli 2026.8.7.

--disabled

boolean

false

Only APIs with disabled: true. Added in celigo-cli 2026.8.7.

--fields <spec>

string

default

Fields to request per row. default returns _id, name, and the table columns; all returns complete documents; a comma-separated list requests specific fields. See field projection.

--limit <n>

integer

—

Return at most <n> rows, fetching a single page.

Default table columns: _id, name, type, disabled, lastModified.

Example

Corresponds to: GET /v1/apis (operationId: listApis)

celigo apis get <id>

Fetch one API by ID.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

API resource ID.

Flags

Uses global flags only.

Example

Corresponds to: GET /v1/apis/{_id} (operationId: getApiById)

celigo apis create

Create a new API from a JSON body. Read the body from a file with -f, --file (recommended), or pipe it on stdin.

Signature

Arguments

None.

Flags

Flag
Type
Default
Description

-f, --file <path>

string

—

Read the JSON body from a file instead of stdin (--file - also means stdin). Added in celigo-cli 2026.6.1.

Request body

A JSON object matching the POST /v1/apis request schema (builder vs. script mode, routers, page processors, etc.).

Example

Corresponds to: POST /v1/apis (operationId: createApi)

celigo apis update <id>

Full-replace an API from a JSON body (--file <path> or stdin).

⚠️ update erases omitted fields. It sends a PUT, not a PATCH, so any field missing from the body is cleared. GET the API first, edit it, then send back the complete object — or use set for partial edits.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

API resource ID.

Flags

Flag
Type
Default
Description

-f, --file <path>

string

—

Read the JSON body from a file instead of stdin (--file - also means stdin). Added in celigo-cli 2026.6.1.

--force

boolean

false

Submit even if the body contains masked credential values (***) copied from a GET.

Request body

The full API JSON, matching the PUT /v1/apis/{_id} request schema.

Example

Corresponds to: PUT /v1/apis/{_id} (operationId: updateApi)

celigo apis set <id> [assignments...]

Safe field edit. Whitelisted fields — including logging.mode, logging.debugUntil, and traceKeyTemplate since celigo-cli 2026.8.7 — are applied via an atomic PATCH; other fields go through GET → modify → PUT so omitted fields survive. Accepts one or more key=value pairs with dot + bracket path support; key=null removes the field. A key=file://<path> value loads that field's value from a file instead of the command line (a leading ~ and relative paths are supported).

The PATCH route for the logging fields is a correctness fix, not just fewer round trips: the server silently ignores logging changes on a full PUT — every mode value revert-persists as basic, without an error — so set is the only CLI path that can actually change an API's logging level.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

API resource ID.

[assignments...]

key=value strings

Yes (≥1)

Field assignments. Dot notation (a.b.c) and array indexing (routers[0].name=r1) supported. JSON-parsed values: disabled=false, debugUntil=null. Use key=file://<path> to load a value from a file.

Flags

Uses global flags only.

Example

Corresponds to: PUT /v1/apis/{_id} (operationId: updateApi) — issued after an internal GET /v1/apis/{_id} — or an atomic PATCH /v1/apis/{_id} when every assigned field is whitelisted.

celigo apis delete <id>

Delete an API. Prompts for confirmation unless -y is passed.

⚠️ delete is immediate. Callers of the API's endpoint start receiving errors. Run dependencies first to see what relies on it.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

API resource ID.

Flags

Flag
Type
Default
Description

-y, --yes

boolean

false

Skip confirmation prompt.

Example

Corresponds to: DELETE /v1/apis/{_id} (operationId: deleteApi)

celigo apis dependencies <id>

List resources that depend on this API (alias: used-by). Use it to check whether an API is safe to delete — an empty result means nothing references it.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

API resource ID.

Flags

Uses global flags only.

Example

Corresponds to: GET /v1/apis/{_id}/dependencies (operationId: listApiDependencies)

celigo apis audit <id>

Show the audit log (change history) for one API.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

API resource ID.

Flags

Uses global flags only.

Example

Corresponds to: GET /v1/apis/{_id}/audit

celigo apis logs <id>

List recent inbound request logs for an API.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

API resource ID.

Flags

Uses global flags only.

Example

Corresponds to: GET /v1/apis/{_id}/logs (operationId: listApiLogs)

celigo apis log-detail <id> <key>

Fetch full request/response detail for a single API log entry. The key comes from apis logs.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

API resource ID.

<key>

string

Yes

Log entry key from apis logs.

Flags

Uses global flags only.

Example

Corresponds to: GET /v1/apis/{_id}/logs/{key} (operationId: getApiLogByKey)

celigo apis request-history <id>

List an API's logged request executions — the run index behind the UI's Request history panel: one entry per inbound request processed while the API's logging.mode was anything other than no_logging. Defaults to the last 5 minutes; widen the window with --time-gte/--time-lte.

This is jobs' analog for APIs: pick an entry's executionId here, then drill into that run with apis execution-logs. Distinct from apis logs, which returns the legacy file-backed request/response envelopes — use request-history for run history, apis logs for the raw decoded request and response of a single call.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

API resource ID.

Flags

Flag
Type
Default
Description

--time-gte <iso>

ISO 8601

5 minutes ago

Include requests at or after this timestamp.

--time-lte <iso>

ISO 8601

now

Include requests at or before this timestamp.

--status-code <code>

string

—

Filter by HTTP response status code (single value or comma-separated list).

--method <method>

string

—

Filter by HTTP method (case-insensitive).

--trace-key-prefix <prefix>

string

—

Filter on traceKey (prefix match; the API's traceKey param).

--remote-ip <prefix>

string

—

Filter on the client IP address (prefix match).

--relative-uri <prefix>

string

—

Filter on the request relative URI (prefix match).

--search-key <text>

string

—

Free-text search, OR-matched across traceKey (prefix), remoteIP (prefix), and relativeURI (substring); at least 3 characters. Overrides those three filters.

--page-size <n>

integer

—

Entries per page.

--sort-order <dir>

asc | desc

—

Sort direction by request time.

Example

Corresponds to: GET /v1/apis/{_id}/requests

celigo apis execution-logs <apiId> <executionId>

Print one request execution's log: the trace view with one record per step/stage event, recorded for runs logged in detailed or debug mode. The per-run layer under request-history, exactly as flows execution-logs <flowId> <jobId> is the per-run layer under jobs. Get the executionId from apis request-history.

Signature

Arguments

Argument
Type
Required
Description

<apiId>

string

Yes

API resource ID.

<executionId>

string

Yes

Execution ID from apis request-history.

Flags

Flag
Type
Default
Description

--details

boolean

false

Assemble the run's complete picture in one command: every step record gains data (its decoded payload), records that fanned out gain children (first page only, each child with its own data), and payloads too large to inline gain a short-lived downloadUrl on their S3 reference. A failed sub-fetch is reported in place as {"error": ...} instead of failing the command.

Example

Corresponds to: GET /v1/apis/{_id}/requests/{executionId}

celigo apis delete-execution-logs <id>

Queue deletion of stored API execution logs within an inclusive date range. Irreversible. Both bounds are required, and the end must not be in the future. Prompts for confirmation unless -y is passed.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

API resource ID.

Flags

Flag
Type
Default
Description

--time-gte <iso>

ISO 8601

—

Required. Start of the deletion window, inclusive.

--time-lte <iso>

ISO 8601

—

Required. End of the deletion window (must not be in the future).

-y, --yes

boolean

false

Skip the confirmation prompt.

Example

Corresponds to: DELETE /v1/apis/{_id}/requests?startedAt=<iso>&endAt=<iso> — the API names the range params startedAt/endAt; the flags keep the CLI-wide --time-gte/--time-lte names.

celigo apis clone <id>

Clone a builder-mode API into a new API plus copied export/import resources. Returns an array of { model, _id } tuples — not a single resource — so pipe through --jq to flatten.

Script-mode APIs are rejected with Clone is only supported for builder-mode APIs.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

Source builder-mode API ID.

Flags

Flag
Type
Default
Description

--api-version <version>

string

—

Required. Version for the cloned API (e.g. v2).

--name <name>

string

—

Name for the cloned API.

--description <description>

string

—

Description for the cloned API.

--environment <environmentId>

string

—

Clone into a target environment (sent as environmentId).

--dry-run

boolean

false

Check whether the target route is free and create nothing. Returns { canClone }.

--dry-run validates that the combination of target version, method, and relativeURI is not already taken. Use it before a real clone to catch a route conflict without leaving a partial API behind.

Example

Corresponds to: POST /v1/apis/{_id}/clone, or POST /v1/apis/{_id}/clone/validate with --dry-run.

celigo apis download <id>

Download a builder-mode API as a template ZIP file. The archive holds the API plus every resource it references: imports, exports, connections, and scripts. Use it to version an API in git, or to hand it to another account.

The CLI requests the template, follows the signed URL, and writes the file locally.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

Builder-mode API ID. Script-mode APIs cannot be exported.

Flags

Flag
Type
Default
Description

-o, --output <path>

string

<api-name>.zip

Output file path. Without it, the CLI writes <api-name>.zip in the current directory, falling back to api-<id>.zip.

Example

Corresponds to: GET /v1/apis/{_id}/template, which returns a short-lived signed URL. The CLI then downloads the archive from that URL.

celigo apis add-processor <id> <exportOrImportId>

Add a page processor to a builder-mode API branch. Auto-detects whether the supplied ID is an export or an import. The CLI issues a GET on the API, mutates the branch's pageProcessors[], and writes back with a full PUT.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

API resource ID (must be builder-mode).

<exportOrImportId>

string

Yes

Export or import ID to add as a page processor.

Flags

Flag
Type
Default
Description

--router <routerId>

string

—

Target a specific router.

--branch <branchName>

string

—

Target a specific branch.

-y, --yes

boolean

false

Skip confirmation prompt.

Example

Corresponds to: PUT /v1/apis/{_id} (operationId: updateApi) — issued after an internal GET /v1/apis/{_id}.

celigo apis remove-processor <id> <exportOrImportId>

Remove a page processor from a builder-mode API branch by its export or import ID. GET → splice the processor → PUT.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

API resource ID.

<exportOrImportId>

string

Yes

Export or import ID to remove.

Flags

Flag
Type
Default
Description

--router <routerId>

string

—

Target a specific router.

--branch <branchName>

string

—

Target a specific branch.

-y, --yes

boolean

false

Skip confirmation prompt.

Example

Corresponds to: PUT /v1/apis/{_id} (operationId: updateApi) — issued after an internal GET /v1/apis/{_id}.

celigo apis set-group / unset-group

Assign APIs to an API group, or remove them from their group. Mirrors flows set-group/unset-group — pass the API IDs as positional arguments; no stdin body.

Signature

Arguments

Argument
Type
Required
Description

<apiGroupingId>

string

Yes (set-group)

The API group to assign the APIs to.

<apiIds...>

string

Yes

One or more API resource IDs.

Example

Corresponds to: PUT /v1/apis/updateApiGrouping (operationId: updateApiGrouping). unset-group sends _apiGroupingId: null to ungroup.

celigo apis test-run <id>

Start a test run of an API and return stage-by-stage results, including metadata, flowJob, and childJobs.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

API resource ID.

Flags

Flag
Type
Default
Description

--export <exportId>

string

—

Export ID (page generator). Sent as _exportId in the request body.

Example

Corresponds to: POST /v1/apis/{_id}/test/run (internal to the CLI; not published in api.yml).

celigo apis test-run-step-results <id> <runId> <exportOrImportId>

Get stage-by-stage results for a single step within a test run. runId and step IDs come from the test-run response. Base64-encoded responses are automatically decoded.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

API resource ID.

<runId>

string

Yes

Test-run ID returned from apis test-run.

<exportOrImportId>

string

Yes

Step ID (export or import) within the test run.

Flags

Uses global flags only.

Example

Corresponds to: GET /v1/apis/{_id}/test/run/{runId}/{exportOrImportId} (internal to the CLI; not published in api.yml).

celigo apis test-run-step-logs <id> <runId> <exportOrImportId>

List HTTP request/response logs for a single test-run step. Logs are only recorded for steps that issued outbound HTTP calls (exports, imports, lookups). Routers and stages that didn't make HTTP requests return 404 Not Found by design; the CLI rewrites that error into a clearer message.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

API resource ID.

<runId>

string

Yes

Test-run ID from apis test-run.

<exportOrImportId>

string

Yes

Step ID (export or import) within the test run.

Flags

Uses global flags only.

Example

Corresponds to: GET /v1/apis/{_id}/test/run/{runId}/{exportOrImportId}/logs/requestAndResponse (internal to the CLI; not published in api.yml).

celigo apis debug-requests <id> <exportOrImportId>

List debug request log entries for a specific export or import invoked by the API. Requires debugUntil to be set on that step (use exports set or imports set to enable debug first).

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

API resource ID.

<exportOrImportId>

string

Yes

Export or import step ID inside the API.

Flags

Flag
Type
Default
Description

--since <minutes>

integer

60

Show requests from the last N minutes. Translated to time_gt (epoch ms).

Example

Corresponds to: GET /v1/apis/{_id}/{exportOrImportId}/requests?time_gt=<epochMs> (internal to the CLI; not published in api.yml).

celigo apis debug-request-detail <id> <exportOrImportId> <key>

Fetch full request/response detail for one debug log entry. The key comes from apis debug-requests.

Signature

Arguments

Argument
Type
Required
Description

<id>

string

Yes

API resource ID.

<exportOrImportId>

string

Yes

Export or import step ID inside the API.

<key>

string

Yes

Debug log entry key from apis debug-requests.

Flags

Uses global flags only.

Example

Corresponds to: GET /v1/apis/{_id}/{exportOrImportId}/requests/{key} (internal to the CLI; not published in api.yml).

Gotchas

  • No apis test subcommand. For end-to-end testing against a live inbound URL, curl the API's published endpoint directly. test-run is a synthetic, stage-by-stage test harness — not a real HTTP invocation.

  • clone only works on builder-mode APIs. Script-mode APIs throw immediately. --api-version is required.

  • clone returns an array, not a single resource. Pipe with --jq '.[] | {model, id: ._id}' to flatten.

  • clone --dry-run creates nothing. It returns { canClone } after checking the target version, method, and relativeURI for a conflict. Run it first when scripting a clone, so a route collision fails before any resource is copied.

  • download covers builder-mode APIs only. Script-mode APIs cannot be exported as a template. The archive includes referenced imports, exports, connections, and scripts, so it is a complete installable unit rather than the API document alone.

  • add-processor / remove-processor rewrite the whole API. They do GET → mutate → PUT, so any concurrent edits made through the UI between those calls are clobbered.

  • test-run-step-logs returns 404 Not Found by design for steps that didn't issue outbound HTTP calls (e.g., routers, pure transforms). The CLI rewrites the error, but the absence of logs is normal.

  • debug-requests requires debugUntil to be set on the target export or import. Without it the endpoint returns an empty array, not an error.

  • logs (inbound) and debug-requests (outbound) are different surfaces. logs captures callers hitting the API; debug-requests captures the API's own outbound calls to exports/imports.

  • request-history only shows logged runs. An entry is recorded per inbound request only while logging.mode is anything other than no_logging, and the per-step trace that execution-logs prints is recorded only for detailed/debug runs. Turn logging on first: celigo apis set <id> logging.mode=detailed.

  • A full PUT cannot change logging. The server silently ignores logging edits on update — the mode revert-persists as basic without an error. Use apis set, which routes logging.mode, logging.debugUntil, and traceKeyTemplate through an atomic PATCH.

When to use a Celigo API vs. a Flow

Concern
Flow
API

Caller needs an immediate response

No

Yes

Work can be async (queue for batch processing)

Yes

No

Caller can't authenticate to the target

No

Yes (proxy pattern)

High-volume, throughput-focused batch

Yes

No

Related

  • flows — async, scheduled pipelines; the counterpart to synchronous APIs.

  • tools — APIs often orchestrate tools under the hood.

  • mcp-servers — builder-mode APIs can be exposed as MCP endpoints.

Previousai-agents
Nextasync-helpers

Last updated

Was this helpful?