vault api

Call any 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

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.

Examples

Get the current user

vault api /objects/users/me

Run a request against a specific vault

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

Send a form-encoded body

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

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

Upload a file

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

Download a file

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

Delete a record

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

Call an endpoint without a version prefix

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.