---
title: "alpacon api"
description: "Send a request to the Alpacon API with your signed-in CLI session. Learn how to build fields and bodies, read responses, handle MFA, and use exit codes."
---

> Full documentation index: https://docs.alpacax.com/llms.txt

# alpacon api

Send one request to the Alpacon API of the current workspace, using the identity you signed in with.

## Usage

`alpacon api ENDPOINT [flags]`

## Key facts

- `ENDPOINT` is a path on the current workspace, such as `/api/iam/users/`. An absolute URL or another host is refused.
- With no `-X`, the method is `GET`, or `POST` once you pass a field or `--input`.
- Fields go to the query string for `GET` and `HEAD`, and to a JSON body for other methods. With `--input`, they always go to the query string.
- The response body goes to stdout even for an error; an error also prints `HTTP <code>` to stderr and exits with code `1`.
- When an action needs a fresh MFA check, the CLI shows the MFA link and sends the request again once you finish.

## Flags

| Flag | Type | Description | Default |
| --- | --- | --- | --- |
| `-F, --field` | `field` | Typed field (key=value) | — |
| `-H, --header` | `stringArray` | Request header (key:value; Host, Transfer-Encoding, Trailer, Content-Length unsupported) | — |
| `-h, --help` | `bool` | help for api | `false` |
| `-i, --include` | `bool` | Include response headers | `false` |
| `--input` | `string` | Request body file (- for stdin) | — |
| `-X, --method` | `string` | HTTP method | `GET` |
| `-f, --raw-field` | `field` | String field (key=value) | — |
| `--silent` | `bool` | Suppress response body | `false` |
| `--verbose` | `bool` | Print request and response headers to stderr | `false` |
| `--output` | `string` | Output format: table or json | `table` |

## Examples

Show your own user record

```bash
alpacon api /api/iam/users/-/
```

Search users, with the status line and response headers

```bash
alpacon api -X GET -i -f search=admin /api/iam/users/
```

Create a resource from typed fields (sent as `POST`)

```bash
alpacon api -F name=my-server /api/servers/servers/
```

Update a resource from a JSON file

```bash
alpacon api -X PATCH --input update.json /api/servers/servers/123/
```

## Request fields

`-f key=value` always sends a string. `-F key=value` reads the value first:

| Value | Sent as |
| --- | --- |
| `true`, `false` | Boolean |
| `null` | `null` |
| A whole number | Integer |
| `@file` | The file's contents, as a string |
| `@-` | Standard input, as a string |
| Anything else | String |

Bracket keys build nested values. `-f 'tags[]=one' -f 'tags[]=two'` sends an array, and `-f 'filter[name]=demo'` sends an object. In a query string the brackets stay in the parameter name.

With `--input`, the file (or standard input for `--input -`) is the request body, and any `-f`/`-F` fields go to the query string. `POST`, `PUT`, and `PATCH` requests are sent as `Content-Type: application/json`; pass `-H 'Content-Type: ...'` for another body type. Only one field or `--input` can read standard input.

## Response output

The response body is written to stdout. In a terminal, control characters are removed from the body and a JSON body is indented; piped or redirected output is left exactly as the server sent it, so `jq` and other tools read the original body.

`-i` adds the status line and response headers before the body, and `--verbose` prints the request and response headers to stderr. Both show `Authorization`, `Proxy-Authorization`, `Cookie`, and `Set-Cookie` as `[REDACTED]`. `--silent` drops the body; the exit code still reports the result.

A redirect within the workspace is followed. A redirect to another host is not: the CLI prints `HTTP <code>` and `redirect to <location> not followed` to stderr and exits with code `1`.

## Permissions and MFA

A request runs with the permissions of the identity you signed in with through [`alpacon login`](/reference/cli/login/). The server refuses what that identity cannot do, and the refusal body is printed like any other response. See the [API reference](/reference/api/) for endpoints and error codes.

Some actions, such as granting a role, need a fresh MFA check. When the server asks for one, the CLI prints the workspace MFA link, opens it in your browser when one is available, and waits for about three minutes while you finish MFA. It then sends the request again and prints only the final response. If the wait runs out, the server's response is printed, stderr shows its `HTTP <code>` and `MFA authentication timed out`, and the command exits with code `1`.

When you pass your own `-H 'Authorization: ...'` header, the CLI sends it unchanged and does not open an MFA prompt. A token cannot complete MFA, so sign in as yourself for actions that need a fresh check.

## Exit codes

- 0: the server answered with a `2xx` status.
- 1: the server answered with another status, the request could not be sent, or an unknown flag was passed.
- 2: the endpoint, method, a field, a header, or the input file was invalid. Nothing was sent.

## Related

- [API reference](/reference/api/)
- [API tokens](/reference/api/tokens/)
- [alpacon login](/reference/cli/login/)
- [alpacon whoami](/reference/cli/whoami/)

Source: https://docs.alpacax.com/reference/cli/api/