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

# The api command

> Call any Bronto API endpoint with bronto api, with authentication, region, retries, and output handled for you.

Not every Bronto endpoint has its own command. `bronto api` calls any of them directly,
using the same credentials, region, retries, `--debug` tracing, and output formatting as
the rest of the CLI.

```sh theme={"dark"}
bronto api <METHOD> <path> [-f key=value]... [--input <file|->]
```

The path is relative to the API base URL, for example `/monitors`. The
[Bronto API reference](https://docs.bronto.io/api-reference/introduction.md) lists the
endpoints.

```console theme={"dark"}
$ bronto api GET /monitors
{
  "monitors": [
    {
      "actions": [
        {
          "email": "ada@example.com",
          "type": "EMAIL"
        },
...
      "name": "Payments latency p95",
      "status": "ALERT",
      "threshold": 1000,
      "window": "Last 10 minutes"
    }
  ]
}
```

Unlike `bronto monitors list`, which prints a table, `bronto api` prints the response
body exactly as the API sent it, with key order and number formatting intact. At a
terminal it's indented, and `-o jsonl` puts it on one line. `--jq`, `--fields`, and
`-o csv` work on the decoded JSON instead.

## Parameters and bodies

`-f key=value` means different things depending on the method:

* For `GET` and `DELETE`, each `-f` becomes a query parameter.
* For other methods, each `-f` becomes a field in a JSON body. Values are parsed as JSON
  when possible, so `-f limit=10` sends a number and `-f enabled=true` a boolean. Each key
  can appear once; for a list, pass a JSON array: `-f 'tags=["a","b"]'`.

```sh theme={"dark"}
bronto api GET /monitors -f limit=10
bronto api POST /search --input query.json
echo '{"time_range":"Last 15 minutes"}' | bronto api POST /search --input -
```

`--input` reads the body from a file, or from stdin with `-`. `--content-type` changes the
`Content-Type` header (default `application/json`). A JSON body must be an object or array;
an empty or invalid one fails before it is sent. Other content types send the body as is.

## Useful endpoints without a command

```sh theme={"dark"}
bronto api GET /usage/organizations/logs   # per-dataset usage; bronto usage shows totals
```

## Safety

`--dry-run` prints the request as a plan for any method except `GET` and `HEAD`, so you can check a
`POST`, `PUT`, or `DELETE` before sending it:

```console theme={"dark"}
$ bronto api POST /search -f 'time_range=Last 15 minutes' --dry-run
{
  "body": {
    "time_range": "Last 15 minutes"
  },
  "dry_run": true,
  "method": "POST",
  "path": "/search"
}
```

The output is the response body as JSON: indented at a terminal, compact when piped.
`--fields` and `--jq` apply to the whole response document. HTTP errors map
to the same error codes and [exit codes](https://docs.bronto.io/cli/reference/exit-codes.md) as every other command.

If you call the same endpoint often, wrap it in a
[plugin](https://docs.bronto.io/cli/extend/plugins.md), or [open an issue](https://github.com/bronto-community/bronto-cli/issues)
asking for a dedicated command.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.