> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/cli/commands/apis.md).

# 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](https://developer.celigo.com/api/api-reference/apis)

```
celigo apis <subcommand> [args] [flags]
```

Supports all [global flags](/cli/getting-started/global-flags.md).

***

## 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).                                                                                 |
| `graph [ref]`                                           | Render the API's Flow Builder graph from the local tree, offline — as JSON, Mermaid, or DOT. Added in celigo-cli 2026.9.1. |
| `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**

```bash
celigo apis list [--name <substring>] [--disabled]
```

**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](/cli/getting-started/global-flags.md). |
| `--limit <n>`        | integer | —         | Return at most `<n>` rows, fetching a single page.                                                                                                                                                                                  |

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

**Example**

```bash
celigo apis list --format table

# Disabled order-related APIs
celigo apis list --name order --disabled
```

**Corresponds to**: [`GET /v1/apis`](https://developer.celigo.com/api/api-reference/apis#get-v1-apis) (operationId: `listApis`)

***

## `celigo apis get <id>`

Fetch one API by ID.

**Signature**

```bash
celigo apis get <id>
```

**Arguments**

| Argument | Type   | Required | Description      |
| -------- | ------ | -------- | ---------------- |
| `<id>`   | string | Yes      | API resource ID. |

**Flags**

Uses [global flags](/cli/getting-started/global-flags.md) only.

**Example**

```bash
celigo apis get 5f83a9b2c7d3e8f1a2b3c4d5 --format json
```

**Corresponds to**: [`GET /v1/apis/{_id}`](https://developer.celigo.com/api/api-reference/apis#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**

```bash
celigo apis create --file <path>
celigo apis create < api.json     # or pipe on stdin
```

**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**

```bash
celigo apis create --file ./api.json
```

**Corresponds to**: [`POST /v1/apis`](https://developer.celigo.com/api/api-reference/apis#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**

```bash
celigo apis update <id> --file <path>
celigo apis update <id> < api.json     # or pipe on stdin
```

**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**

```bash
celigo apis get 5f83a9b2c7d3e8f1a2b3c4d5 --format json \
  | jq '.name = "Renamed API"' \
  | celigo apis update 5f83a9b2c7d3e8f1a2b3c4d5
```

**Corresponds to**: [`PUT /v1/apis/{_id}`](https://developer.celigo.com/api/api-reference/apis#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**

```bash
celigo apis set <id> key=value [key2=value2 ...]
```

**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](/cli/getting-started/global-flags.md) only.

**Example**

```bash
celigo apis set 5f83a9b2c7d3e8f1a2b3c4d5 disabled=false debugUntil=null

# Turn on detailed request logging (feeds request-history / execution-logs)
celigo apis set 5f83a9b2c7d3e8f1a2b3c4d5 logging.mode=detailed
```

**Corresponds to**: [`PUT /v1/apis/{_id}`](https://developer.celigo.com/api/api-reference/apis#put-v1-apis-_id) (operationId: `updateApi`) — issued after an internal [`GET /v1/apis/{_id}`](https://developer.celigo.com/api/api-reference/apis#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**

```bash
celigo apis delete <id> [-y]
```

**Arguments**

| Argument | Type   | Required | Description      |
| -------- | ------ | -------- | ---------------- |
| `<id>`   | string | Yes      | API resource ID. |

**Flags**

| Flag          | Type    | Default | Description               |
| ------------- | ------- | ------- | ------------------------- |
| `-y`, `--yes` | boolean | `false` | Skip confirmation prompt. |

**Example**

```bash
celigo apis delete 5f83a9b2c7d3e8f1a2b3c4d5 -y
```

**Corresponds to**: [`DELETE /v1/apis/{_id}`](https://developer.celigo.com/api/api-reference/apis#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**

```bash
celigo apis dependencies <id>
```

**Arguments**

| Argument | Type   | Required | Description      |
| -------- | ------ | -------- | ---------------- |
| `<id>`   | string | Yes      | API resource ID. |

**Flags**

Uses [global flags](/cli/getting-started/global-flags.md) only.

**Example**

```bash
celigo apis dependencies 5f83a9b2c7d3e8f1a2b3c4d5
```

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

***

## `celigo apis audit <id>`

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

**Signature**

```bash
celigo apis audit <id>
```

**Arguments**

| Argument | Type   | Required | Description      |
| -------- | ------ | -------- | ---------------- |
| `<id>`   | string | Yes      | API resource ID. |

**Flags**

Uses [global flags](/cli/getting-started/global-flags.md) only.

**Example**

```bash
celigo apis audit 5f83a9b2c7d3e8f1a2b3c4d5
```

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

***

## `celigo apis graph [ref]`

Render an API's Flow Builder graph from the local tree, offline — the request as the one source, the steps and branchings, and the response router with its responses as the terminals, as the canvas draws them. Each step carries its name, category, application, and step components (filters, mappings, hooks, response mapping, error handling), resolved through the tree that `celigo pull` wrote. See [The local tree](/cli/local-tree.md). Added in celigo-cli 2026.9.1.

The graph is rendered from the documents on disk, so no profile or token is needed and the command is never mode-gated. `[ref]` is a tree path, a link, a resource folder, `type:id`, or a bare id. Any `api.json` on disk works through `--file` (`-` for stdin), but its references stay unresolved unless the file sits in a pulled tree. A `flow:`, `api:`, or `tool:` ref renders with its own builder's shape from any of the three groups, and a `--file` document whose shape names no builder renders as an API. The JSON output is the graph the Celigo VS Code extension's Flow Canvas consumes ([VS Code extension](/cli/vscode-extension.md)); `--as mermaid` renders natively in GitHub pull requests, and `--as dot` is Graphviz input. The full contract is the same as [`flows graph`](/cli/commands/flows.md#celigo-flows-graph).

**Signature**

```bash
celigo apis graph [ref] [--dir <path>] [--as json|mermaid|dot] [--file <path>] [--status] [--no-components]
```

**Arguments**

| Argument | Type   | Required | Description                                                                                                                                                                                                                                                           |
| -------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[ref]`  | string | No       | The API to render: a tree path, a link, a resource folder, `api:<id>` (or `flow:`/`tool:`), or a bare id. Required unless `--file` is given; with neither, the command exits `1` with `Provide a ref (a tree path, type:id, or id) or --file <path> ('-' for stdin).` |

**Flags**

| Flag              | Type                         | Default | Description                                                                                                                                                                                    |
| ----------------- | ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--dir <path>`    | string                       | `.`     | Tree root directory.                                                                                                                                                                           |
| `--as <format>`   | `json` \| `mermaid` \| `dot` | `json`  | Output format. `json` is the graph the VS Code canvas consumes; `mermaid` renders natively in GitHub pull requests; `dot` is for Graphviz.                                                     |
| `--file <path>`   | string                       | —       | Read the document from a file instead of the tree (`-` for stdin). References render unresolved unless the file sits in a pulled tree.                                                         |
| `--status`        | boolean                      | `false` | Add the tree's `celigo status` state (`clean`, `modified`, `missing`, or `untracked`) for the document and each step's resource. In `mermaid`/`dot` output the states appear as comment lines. |
| `--no-components` | boolean                      | `false` | Leave the step component chips out of `mermaid`/`dot` output.                                                                                                                                  |

**Example**

```bash
# From inside a pulled tree
celigo apis graph api:5f83a9b2c7d3e8f1a2b3c4d5

# Mermaid for a pull request description
celigo apis graph "integrations/Shop/apis/Public Lookup API/api.json" --as mermaid
```

**Corresponds to**: no API call — the graph is built from the local tree.

***

## `celigo apis logs <id>`

List recent inbound request logs for an API.

**Signature**

```bash
celigo apis logs <id>
```

**Arguments**

| Argument | Type   | Required | Description      |
| -------- | ------ | -------- | ---------------- |
| `<id>`   | string | Yes      | API resource ID. |

**Flags**

Uses [global flags](/cli/getting-started/global-flags.md) only.

**Example**

```bash
celigo apis logs 5f83a9b2c7d3e8f1a2b3c4d5 --format json
```

**Corresponds to**: [`GET /v1/apis/{_id}/logs`](https://developer.celigo.com/api/api-reference/apis) (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**

```bash
celigo apis log-detail <id> <key>
```

**Arguments**

| Argument | Type   | Required | Description                     |
| -------- | ------ | -------- | ------------------------------- |
| `<id>`   | string | Yes      | API resource ID.                |
| `<key>`  | string | Yes      | Log entry key from `apis logs`. |

**Flags**

Uses [global flags](/cli/getting-started/global-flags.md) only.

**Example**

```bash
celigo apis log-detail 5f83a9b2c7d3e8f1a2b3c4d5 01H9XK7M...
```

**Corresponds to**: [`GET /v1/apis/{_id}/logs/{key}`](https://developer.celigo.com/api/api-reference/apis) (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](/cli/commands/jobs.md)' 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**

```bash
celigo apis request-history <id> [filters]
```

**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**

```bash
# Failed requests in the last hour
celigo apis request-history 5f83a9b2c7d3e8f1a2b3c4d5 \
  --time-gte "$(date -u -v-1H +%FT%TZ)" --status-code 500

# Pick a run to drill into
celigo apis request-history 5f83a9b2c7d3e8f1a2b3c4d5 --jq '.[0].executionId'
```

**Corresponds to**: [`GET /v1/apis/{_id}/requests`](https://developer.celigo.com/api/api-reference/apis)

***

## `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>`](/cli/commands/flows.md#celigo-flows-execution-logs) is the per-run layer under `jobs`. Get the `executionId` from `apis request-history`.

**Signature**

```bash
celigo apis execution-logs <apiId> <executionId> [--details]
```

**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**

```bash
celigo apis execution-logs 5f83a9b2c7d3e8f1a2b3c4d5 exec_01J9XK7M --details
```

**Corresponds to**: [`GET /v1/apis/{_id}/requests/{executionId}`](https://developer.celigo.com/api/api-reference/apis)

***

## `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**

```bash
celigo apis delete-execution-logs <id> --time-gte <iso> --time-lte <iso> [-y]
```

**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**

```bash
celigo apis delete-execution-logs 5f83a9b2c7d3e8f1a2b3c4d5 \
  --time-gte 2026-07-01T00:00:00Z --time-lte 2026-07-31T23:59:59Z -y
```

**Corresponds to**: [`DELETE /v1/apis/{_id}/requests?startedAt=<iso>&endAt=<iso>`](https://developer.celigo.com/api/api-reference/apis) — 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**

```bash
celigo apis clone <id> --api-version <version> [--name <name>] [--description <description>] [--environment <environmentId>]
```

**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**

```bash
celigo apis clone 5f83a9b2c7d3e8f1a2b3c4d5 \
  --api-version v2 \
  --name "My API (v2)" \
  --jq '.[] | {model, id: ._id}'

# Check the route first
celigo apis clone 5f83a9b2c7d3e8f1a2b3c4d5 --api-version v2 --dry-run
```

**Corresponds to**: `POST /v1/apis/{_id}/clone`, or [`POST /v1/apis/{_id}/clone/validate`](https://developer.celigo.com/api/api-reference/apis) 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**

```bash
celigo apis download <id> [-o <path>]
```

**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**

```bash
celigo apis download 5f83a9b2c7d3e8f1a2b3c4d5

# A stable path for a git-tracked export
celigo apis download 5f83a9b2c7d3e8f1a2b3c4d5 -o ./templates/orders-api.zip
```

**Corresponds to**: [`GET /v1/apis/{_id}/template`](https://developer.celigo.com/api/api-reference/apis), 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**

```bash
celigo apis add-processor <id> <exportOrImportId> [--router <routerId>] [--branch <branchName>] [-y]
```

**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**

```bash
celigo apis add-processor 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f --router r1 -y
```

**Corresponds to**: [`PUT /v1/apis/{_id}`](https://developer.celigo.com/api/api-reference/apis#put-v1-apis-_id) (operationId: `updateApi`) — issued after an internal [`GET /v1/apis/{_id}`](https://developer.celigo.com/api/api-reference/apis#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**

```bash
celigo apis remove-processor <id> <exportOrImportId> [--router <routerId>] [--branch <branchName>] [-y]
```

**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**

```bash
celigo apis remove-processor 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f -y
```

**Corresponds to**: [`PUT /v1/apis/{_id}`](https://developer.celigo.com/api/api-reference/apis#put-v1-apis-_id) (operationId: `updateApi`) — issued after an internal [`GET /v1/apis/{_id}`](https://developer.celigo.com/api/api-reference/apis#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**

```bash
celigo apis set-group <apiGroupingId> <apiIds...>
celigo apis unset-group <apiIds...>
```

**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**

```bash
celigo apis set-group 60a1b2c3d4e5f60012345678 5f8d43a1b9e5a80011a35f2c 5f8d43a1b9e5a80011a35f2d
celigo apis unset-group 5f8d43a1b9e5a80011a35f2c
```

**Corresponds to**: [`PUT /v1/apis/updateApiGrouping`](https://developer.celigo.com/api/api-reference/apis#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**

```bash
celigo apis test-run <id> [--export <exportId>]
```

**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**

```bash
celigo apis test-run 5f83a9b2c7d3e8f1a2b3c4d5 --format json
```

**Corresponds to**: [`POST /v1/apis/{_id}/test/run`](https://developer.celigo.com/api/api-reference/apis) (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**

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

**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](/cli/getting-started/global-flags.md) only.

**Example**

```bash
celigo apis test-run-step-results 5f83a9b2c7d3e8f1a2b3c4d5 run_01H9X... 6a1b2c3d4e5f6a7b8c9d0e1f
```

**Corresponds to**: [`GET /v1/apis/{_id}/test/run/{runId}/{exportOrImportId}`](https://developer.celigo.com/api/api-reference/apis) (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**

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

**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](/cli/getting-started/global-flags.md) only.

**Example**

```bash
celigo apis test-run-step-logs 5f83a9b2c7d3e8f1a2b3c4d5 run_01H9X... 6a1b2c3d4e5f6a7b8c9d0e1f
```

**Corresponds to**: [`GET /v1/apis/{_id}/test/run/{runId}/{exportOrImportId}/logs/requestAndResponse`](https://developer.celigo.com/api/api-reference/apis) (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**

```bash
celigo apis debug-requests <id> <exportOrImportId> [--since <minutes>]
```

**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**

```bash
celigo apis debug-requests 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f --since 15
```

**Corresponds to**: [`GET /v1/apis/{_id}/{exportOrImportId}/requests?time_gt=<epochMs>`](https://developer.celigo.com/api/api-reference/apis) (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**

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

**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](/cli/getting-started/global-flags.md) only.

**Example**

```bash
celigo apis debug-request-detail 5f83a9b2c7d3e8f1a2b3c4d5 6a1b2c3d4e5f6a7b8c9d0e1f 01H9X...
```

**Corresponds to**: [`GET /v1/apis/{_id}/{exportOrImportId}/requests/{key}`](https://developer.celigo.com/api/api-reference/apis) (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](/cli/commands/flows.md) — async, scheduled pipelines; the counterpart to synchronous APIs.
* [tools](/cli/commands/tools.md) — APIs often orchestrate tools under the hood.
* [mcp-servers](/cli/commands/mcp-servers.md) — builder-mode APIs can be exposed as MCP endpoints.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.celigo.com/cli/commands/apis.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.