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
cademi api [method] <path>- The path is relative to
/api/v3:/productscalls/api/v3/products. It can include a query string (/products?status=published). - The method defaults to
GET, or toPOSTwhen you pass--data. - For
GET,-fand-Fadd query parameters, and--datais rejected. For every other method, they build the JSON body, as in Commands. - 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'sendstag_id[]twice. - The request is authenticated like any other command: with
CADEMI_API_KEYwhen it is set, and with the current profile otherwise.
cademi api /credentials/current
cademi api /products -f status=published --all --jq '.[].id'
cademi api POST /users -f name="Ana Souza" -f [email protected]
cademi api PATCH /products/prd_12 --if-match 'W/"product:prd_12:..."' -f name="New name"
cademi api POST /operations/batches -d @batch.json --waitThe body of a batch and the rules for its items are in Asynchronous operations, batches, and idempotency.
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. |
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 and Exit codes.
When to use it
- Operations newer than the CLI. When the server runs a newer release than your CLI,
cademi doctorwarns you, and the new operations have no command until you update.cademi apireaches them right away. - Exploring the API. Pair
cademi apiwith-ito see the status and headers of a response, such asX-Cademi-Release,X-Request-Id, andETag. - Scripts that mirror HTTP. If a script already works with paths from the API reference,
cademi apihandles 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.