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: /products calls /api/v3/products. It can include a query string (/products?status=published).
• The method defaults to GET, or to POST when you pass --data.
• For GET, -f and -F add query parameters, and --data is 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' sends tag_id[] twice.
• The request is authenticated like any other command: with CADEMI_API_KEY when 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 --wait

The body of a batch and the rules for its items are in Asynchronous operations, batches, and idempotency.

Validation before sending

When the method and path match an operation in the API contract built into the CLI, cademi api checks the request before sending it, as the generated commands do. The contract matches the API release that cademi version shows. The command stops with exit code 2, and nothing reaches the API, when the request has any of the following:

• a query parameter that the operation does not declare;
• a body field that the operation does not accept, including fields in --data and the keys of nested objects when the contract lists them;
• a body for an operation that takes none.

The message names what was rejected and lists what the operation accepts:

cademi api '/products?offset=50'

Error: unknown query parameter "offset" for GET /products; accepted: limit, cursor, sort, showcase_id, status, external_id, q, deleted. API v3 paginates with limit and cursor (page.next_cursor)

Query parameter names are compared as written, so an array parameter needs its brackets (tag_id[], not tag_id). A path that matches no known operation is sent without this check.

--skip-validation sends the request as it is. Use it when the server runs a newer API release than your CLI and an operation gained a parameter or a field that your CLI does not know. The API still validates the request and rejects what it does not accept (Errors).

cademi api POST /users --skip-validation -f name="Ana Souza" -f [email protected] -f new_field=value

Flags

You can set the idempotency key with --idempotency-key or with -H 'Idempotency-Key: <key>'. If you pass both, --idempotency-key wins. An Idempotency-Key header with an empty value is ignored, and the write carries a new key as usual. See Writes, retries, and idempotency.

cademi api POST /users -H 'Idempotency-Key: import-ana-2026-09-25' -f name="Ana Souza" -f [email protected]

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 doctor warns you, and the new operations have no command until you update. cademi api reaches them right away. If an existing operation gained a parameter or a field in that release, add --skip-validation.
• Exploring the API. Pair cademi api with -i to see the status and headers of a response, such as X-Cademi-Release, X-Request-Id, and ETag.
• Scripts that mirror HTTP. If a script already works with paths from the API reference, cademi api handles 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.