**Source URL:** https://limited.veevavault.dev/medical/vault-dx/dx-reference/command-reference/api

# vault api

Call any [Vault API](/medical/vault-api/) endpoint and print the response. The CLI adds your stored session and the API version for you, so you only supply the endpoint path.

## Usage

```sh
vault api <PATH> [--dns <DNS>] [-X <METHOD>] [-H <HEADER>]... [-d <DATA> | -F <KEY=VALUE>...] [-o <FILE>] [-i] [--api-version <VERSION>]
```

## Options

| Option | Type | Required | Description |
| --- | --- | --- | --- |
| `<PATH>` | string | Required | API path, for example `/objects/users/me`. Query parameters can be included inline, for example `/objects/users?limit=10`. Prefixed with `/api/<version>` unless none is passed |
| `--dns <DNS>` | string | Optional | Vault DNS to run against. Default: the active vault |
| `-X, --method <METHOD>` | string | Optional | HTTP method, for example `GET`, `POST`, `PUT`, or `DELETE`. Default: `GET`, or `POST` when `-d` or `-F` is given |
| `-H, --header <HEADER>` | string | Optional | Request header in `"Key: Value"` form. Repeatable. An `Authorization` header replaces the session the CLI adds automatically |
| `-d, --data <DATA>` | string | Optional | Request body. `@file` reads it from a file and `@-` from stdin. The CLI does not set a `Content-Type`. Pass one with `-H` if the endpoint needs it. Cannot be combined with `-F` |
| `-F, --form <KEY=VALUE>` | string | Optional | Multipart form field. Repeatable. `KEY=@file` uploads a file and `KEY=@-` reads stdin. Append `;filename=NAME` to set the upload's filename. Cannot be combined with `-d` |
| `-o, --output <FILE>` | string | Optional | Write the raw response to this file instead of stdout. Required for a non-JSON response, such as a file download |
| `-i, --include` | flag | Optional | Include the response status line and headers in the output |
| `--api-version <VERSION>` | string | Optional | Vault API version to use instead of the negotiated one, for example `v24.2`. `none` omits the `/api/<version>` prefix |

This command also accepts the [global options](/medical/vault-dx/dx-reference/command-reference/global-options/).

## Examples

#### Get the current user

```sh
vault api /objects/users/me
```

#### Run a request against a specific vault

```sh
vault api /objects/users/me --dns myorg-sandbox.veevavault.com
```

#### Send a form-encoded body

```sh
vault api /query -d "q=SELECT id, name__v FROM documents__v" -H "Content-Type: application/x-www-form-urlencoded"
```

#### Send a JSON body from a file

```sh
vault api /vobjects/product__v -d @product.json -H "Content-Type: application/json"
```

#### Upload a file

```sh
vault api /objects/documents -F file=@protocol.pdf -F name__v=Protocol -F type__v=General -F lifecycle__v="General Lifecycle"
```

#### Download a file

```sh
vault api /objects/documents/123/file -o protocol.pdf
```

#### Delete a record

```sh
vault api /vobjects/product__v/00P000000000301 -X DELETE
```

#### Call an endpoint without a version prefix

```sh
vault api /api/mdl/execute --api-version none -d @script.mdl -H "Content-Type: text/plain"
```

## Output

A JSON response is pretty-printed to stdout. With `--output`, the raw response is written to the file and the CLI prints `Saved <N> bytes to <file>`.

A non-JSON response without `--output` is an error. Re-run with `--output <file>` to save it.

## Exit codes

Vault returns HTTP `200` for most API errors, so the CLI sets the exit code from the response's `responseStatus` instead of the HTTP status. Scripts can check the exit code without parsing JSON.

| Exit code | Response |
| --- | --- |
| `0` | `responseStatus` is `SUCCESS` or `WARNING` |
| `0` | Non-JSON response saved with `--output` |
| `4` | Request timed out after 30 seconds |
| `5` | `responseStatus` is `FAILURE` or `EXCEPTION`. The CLI prints `ERROR [TYPE] message` to `stderr` |

Learn more about CLI [Exit codes](/vault-dx/dx-reference/command-reference/#exit-codes).