# Raw requests

`cademi api` sends an authenticated request to any API v3 endpoint and prints the response. Use it for operations added to the API after your CLI version, or when you want to control the method, path, query string, and headers directly.

## Usage

```sh
cademi api [method] <path>
```

- The path is relative to `/api/v3`: `/products` calls `/api/v3/products`. It can include a query string (`/products?status=published`).
- The method defaults to `GET`, or to `POST` when you pass `--data`.
- For `GET`, `-f` and `-F` add query parameters, and `--data` is rejected. For every other method, they build the JSON body, as in [Commands](https://cademi.dev/cli/commands.md#request-bodies).
- Query parameter names are sent as written, and a repeated name is sent once per value: `cademi api /users -f 'tag_id[]=tag_01' -f 'tag_id[]=tag_02'` sends `tag_id[]` twice.
- The request is authenticated like any other command: with `CADEMI_API_KEY` when it is set, and with the current profile otherwise.

```sh
cademi api /credentials/current
cademi api /products -f status=published --all --jq '.[].id'
cademi api POST /users -f name="Ana Souza" -f email=ana@example.com
cademi api PATCH /products/prd_12 --if-match 'W/"product:prd_12:..."' -f name="New name"
cademi api POST /operations/batches -d @batch.json --wait
```

The body of a batch and the rules for its items are in [Asynchronous operations, batches, and idempotency](https://cademi.dev/api/operations.md#batches).

## Flags

| Flag | Effect |
|---|---|
| `-d`, `--data` | JSON body: a literal, `@file`, or `@-` for standard input. |
| `-f`, `--field` / `-F`, `--typed-field` | Query parameters for `GET`, body fields otherwise. |
| `-H`, `--header 'Name: value'` | Adds a request header. Repeat for several headers. |
| `--all` | Follows `next_cursor` and prints every item as a single array. `GET` only. |
| `--idempotency-key` | Sets the `Idempotency-Key` of a write. By default, a new key is sent with every `POST`, `PATCH`, `PUT`, and `DELETE`. |
| `--if-match` | Sends `If-Match` with this `ETag`. |
| `--wait`, `--wait-timeout` | When the API answers `202`, waits for the operation to finish. |
| `--json`, `-o`, `--jq`, `--raw`, `-i` | Output, as in [Commands](https://cademi.dev/cli/commands.md#output). |

By default, `cademi api` prints the `data` of the response. `--raw` prints the whole envelope, and `-i` adds the status and headers.

Retries, exit codes, and error output are the same as for the generated commands: see [Commands](https://cademi.dev/cli/commands.md#writes-retries-and-idempotency) and [Exit codes](https://cademi.dev/cli/exit-codes.md).

## When to use it

- **Operations newer than the CLI.** When the server runs a newer release than your CLI, `cademi doctor` warns you, and the new operations have no command until you update. `cademi api` reaches them right away.
- **Exploring the API.** Pair `cademi api` with `-i` to see the status and headers of a response, such as `X-Cademi-Release`, `X-Request-Id`, and `ETag`.
- **Scripts that mirror HTTP.** If a script already works with paths from the [API reference](https://cademi.dev/api/reference.md), `cademi api` handles authentication, idempotency keys, and retries for it.

For every other case, the generated commands are shorter: they build the path from positional arguments, type the query flags, and list the body fields in `--help`.