> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# JSON requests and responses - Omni CLI

> The shape of request bodies, response payloads, and error output for Omni CLI commands.

Every Omni CLI command that sends or receives data uses the same JSON conventions, whatever the command group. This page covers how to pass a request body, what a successful response looks like, what the CLI writes when a request fails, and how to reach a query parameter the CLI has no flag for.

## Request bodies

Pass a request body with `--body`, in one of three forms:

* An inline JSON string: `--body '{"name":"Blob Sales"}'`
* A file path prefixed with `@`: `--body @request.json`
* `-` to read from stdin: `--body -`

The CLI validates the body as JSON before sending it, so a malformed payload fails locally instead of round-tripping to the API first. Simple bodies can also be set field-by-field with a command's promoted flags instead of `--body` (shown in that command's `--help` output). The two approaches can't be combined on the same call.

<Tip>
  Run any command with `--schema` to print its arguments, flags, request body shape, and response shape without making an API call. For example:

  ```bash theme={null}
  omni documents duplicate --schema
  ```
</Tip>

## Response payloads

A successful response (`--format json`, the default when output is piped) is the API's JSON body, unmodified, and `--compact` prints it non-indented, which is easier to pipe into `jq` or other tools. List endpoints return one of two shapes:

```json theme={null}
// Paginated list
{ "records": [ /* ... */ ], "pageInfo": { "hasMore": true, "cursor": "abc123" } }

// Non-paginated list, resource-named
{ "connections": [ /* ... */ ] }
```

A single-resource endpoint (get, create, update, delete) returns that resource's JSON object directly, with no wrapper.

See [output formats](/developers/cli/reference/output-formats) for how `--format human` renders these same payloads as tables and key-value summaries instead.

## Errors

A failed request writes nothing to `stdout`, even a partial response body, and writes exactly one JSON document to `stderr`:

```json theme={null}
{
  "error": "<human-readable detail, extracted from the upstream error body when possible>",
  "status": 404,
  "body": { "...": "the raw upstream error body, omitted if there wasn't one" }
}
```

In `--format human`, the same failure prints as a single line instead: `Error: <detail> (HTTP <status>)`. See [errors and exit codes](/developers/cli/reference/errors-and-exit-codes) for what a failure means for the process's exit code.

## Query escape hatch

If the CLI's generated flags for a command don't cover a query parameter the API supports (for example, one added to the API after this CLI version was built), add it with the `--query` escape hatch instead. It's repeatable, for multiple parameters:

```bash theme={null}
omni documents list --query "includeArchived=true" --query "labelId=lbl_123"
```

Required query parameters that aren't supplied, whether by a named flag or `--query`, cause the CLI to fail before sending a request, rather than letting the API reject an incomplete call.

<Note>
  A list command's pagination flags (a cursor, a page size, or both) aren't named consistently across every command. Check that command's own `--help` output for the exact flag name.
</Note>