---
title: api
description: Use existing authentication to discover and request public APIs.
canonical_url: https://orchestor.io/docs/en/cli/api
markdown_url: https://orchestor.io/docs/en/cli/api.md
contentType: reference
---

# api

`orc api` sends authenticated HTTP requests to the Orchestor API from your terminal. It uses the same credentials as other CLI commands. Discover methods and paths in the public API contract, then make calls with queries or JSON bodies.

Use it to explore operations without dedicated commands, debug responses, or integrate calls into scripts. Before running it, sign in with [`orc auth login`](https://orchestor.io/docs/cli/auth.md) or configure the authentication used by the CLI. Requests go to the configured Orchestor API and use the current principal’s permissions. The list is a public contract catalog, not a determination of your operation permissions.

## Usage

```bash title="terminal"
orc api list
```

*Inspect public API methods, paths, and descriptions.*

```bash title="terminal"
orc api request GET /v1/users/me
```

*Retrieve the current authenticated principal’s profile.*

## Subcommands

### `list`

Return HTTP methods, paths, operationId values, and descriptions from the public API contract bundled with the CLI. Authentication is required. The list is not filtered by account permissions; the server checks permissions when a request runs. `orc api ls` is an alias for `orc api list`.

```bash title="terminal"
orc api list [options]
```

#### Examples

```bash title="terminal"
orc api list --json
```

*Return the API catalog as JSON for scripts.*

### `request`

Specify an HTTP method and an API path beginning with `/`. Supported methods are `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`. The method cannot be omitted and is not inferred from the body. The path must match the public contract shown by `api list`. Replace path parameters such as `{id}` with actual resource IDs.

Put queries in a quoted path. Unknown queries and duplicate values supplied in both the path and flags cause errors. For create and update operations with JSON bodies, pass a JSON object through `--stdin`; it is validated against the API contract’s types and required fields.

```bash title="terminal"
orc api request <method> <path> [options]
```

#### Examples

Save a JSON object such as `{ "locale": "ja" }` in `profile.json`. Profile changes require human account authentication and server-side permissions.

```bash title="terminal"
orc api request PATCH /v1/users/me --stdin < profile.json
```

*Update a profile from saved JSON.*

### `ls`

List public contract operations; server authorization still applies

```bash title="terminal"
orc api ls [options]
```

## Examples

### Retrieve the current principal

Use saved authentication to return your profile in a JSON envelope.

```bash title="terminal"
orc api request GET /v1/users/me
```

*Retrieve the current principal*

### Retrieve information for a Workspace

Set the `X-Workspace-ID` sent with the request using `--workspace`. The server checks access to the specified Workspace.

```bash title="terminal"
orc api request GET /v1/workspaces/<workspace-id> --workspace <workspace-id>
```

*Retrieve information for a Workspace*

### Pass a request body from a JSON file

Use this for create and update operations with bodies. File redirection and piped JSON are both read as standard input.

```bash title="terminal"
orc api request PATCH /v1/users/me --stdin < profile.json
```

*Pass a request body from a JSON file*

### Set the number of list results with a query

Append a query defined by the target API to the path. Query names, types, and requirements follow the public API contract.

```bash title="terminal"
orc api request GET '/v1/workspaces?limit=10'
```

*Set the number of list results with a query*

### Retrieve every page of a list

For APIs with cursor pagination, output records from every page as one NDJSON record per line. This cannot be combined with `--json`, `--pretty`, or `--format` values such as JSON. Use `--output` to save a file if needed.

```bash title="terminal"
orc api request GET /v1/workspaces --page-all
```

*Retrieve every page of a list*

### Skip deletion confirmation

Check the deletion target before running the command. `--yes` skips the CLI confirmation. Server authorization and deletion conditions still apply.

```bash title="terminal"
orc api request DELETE /v1/brands/<brand-id> --workspace <workspace-id> --yes
```

*Skip deletion confirmation*

### Extract a response field

`--field` extracts a response field. It does not add a field to the request body.

```bash title="terminal"
orc api request GET /v1/users/me --field id --raw
```

*Extract a response field*

### Inspect request duration

Return the response on stdout and the duration on stderr.

```bash title="terminal"
orc api request GET /v1/users/me --timing
```

*Inspect request duration*

## How it works

1. The CLI resolves the current authentication.
2. It matches the method and path against the bundled public API contract and validates queries and the JSON body.
3. It sends an authenticated request to the configured API. If a Workspace is specified, it also adds `X-Workspace-ID`.
4. The server checks the current principal’s access and the CLI outputs the response.

The default output is a JSON envelope containing `success`, `data`, and `metadata`. Credential fields are redacted during output. Failure reasons go to stderr; scripts should use exit codes to determine success or failure.

Use `orc api list` for discovery. The API contract is bundled with the CLI rather than fetched on every execution. External URLs, paths beginning with `//`, path traversal, and internal or backend-only APIs are rejected. Redirects are not followed.

## Global Options

The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc api`:

- [`--help`](https://orchestor.io/docs/cli/global-flags.md#help)
- [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace)
- [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format)
- [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output)
- [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output)
- [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager)
- [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run)
- [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation)
- [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#all-pages)
- [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing)

For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md).

## Troubleshooting

### A method or path is rejected

Check methods and paths with `orc api list`. Path endings, resource IDs, and methods must also match the contract. Check the CLI version if a new API is missing from the list.

### Authentication or permission errors

Check authentication and sign in again with [`orc auth login`](https://orchestor.io/docs/cli/auth.md) if needed. If a Workspace is specified, check access to it as well. An operation appearing in the list does not necessarily mean the current account can use it.

### JSON body validation fails

Pass a valid JSON object through `--stdin` and check the target API’s required fields and types. Arrays and individual strings are not accepted as resource definitions. Bodies are used for `POST`, `PUT`, and `PATCH` operations.

### Deletion fails in a non-interactive environment

`DELETE` requires confirmation. In scripts, check the target and pass `--yes`. This does not change operation permissions.

## Related

- [Authentication](https://orchestor.io/docs/cli/auth.md)
- [Workspace](https://orchestor.io/docs/cli/workspace.md)
- [Global options](https://orchestor.io/docs/cli/global-flags.md)

---

[Documentation index](https://orchestor.io/docs/llms.txt)