Skip to content
Quickstart

Quickstart

Five minutes, five steps: save → run → environment → collection → inspect. Every command below works against the public jsonplaceholder.typicode.com API.

Save a request

apigent save "list-users" https://jsonplaceholder.typicode.com/users

A saved request has a name, a method, a URL, and optional headers, body, auth and extraction rules. You can also paste a curl command:

apigent save "create-user" --curl "curl -X POST -H 'Content-Type: application/json' -d '{\"name\":\"Ada\"}' https://jsonplaceholder.typicode.com/users"

Check what you saved:

apigent list
apigent show "create-user"

Run it

apigent run "list-users"

The response body goes to stdout; status lines and notes go to stderr, so piping works:

apigent run "list-users" | jq '.[0].email'

Add assertions, or make non-2xx responses fail the command:

apigent run "list-users" --assert "status=200" --fail

Move values into an environment

Hard-coded hosts and tokens don’t belong in saved requests. Use {{placeholders}} and put the values in an environment:

apigent env create dev \
  --var BASE_URL=https://jsonplaceholder.typicode.com \
  --var API_KEY=- --secret API_KEY          # KEY=- reads the value from stdin, without echo

apigent save "get-user" '{{BASE_URL}}/users/{{id}}' -H 'Authorization: Bearer {{API_KEY}}'

apigent run "get-user" --env dev --var id=1

Secret values are encrypted at rest and shown as ***** by apigent env show dev. If a placeholder can’t be filled, apigent refuses to send the request and names every missing variable. See Variables & placeholders.

Group requests in a collection

apigent collection create "users-api" --var id=1
apigent edit "get-user" --collection users-api
apigent edit "list-users" --collection users-api

apigent collection run "users-api" --env dev

Collection variables sit above environment variables and below --var. A collection run executes its requests in order (see apigent sequence).

Inspect what happened

Every run is recorded, including failures:

apigent history "get-user"          # short ids, status, duration
apigent diag <id>                   # request as sent, variable origins, response, changes since last success

Next steps