Your progress is only saved in this browser. to protect it and pick up on any device.

Connect a Postman API key to check your work

You do each step in Postman, then LiftOff uses your key to look at your workspace and confirm it's done. Connect once and it works for every module. Your key is saved in this browser and is only used to check your work in Postman.

0 of 4 steps0%
3

Lint the Spec and Score Its AI Readiness

Two commands look at the same spec and ask different questions. postman spec lint asks "does this spec follow the rules?" It checks structure and the governance ruleset from your workspace, and it only fails on errors, so warnings still exit 0. postman spec ai-readiness asks "how hard would this API be for an agent to use?" It is a complexity score. A small, plain API scores high, and anything that adds work for an agent, such as auth, lots of endpoints, deep schemas or many error codes, takes points off. Documenting your API doesn't raise the score. What it changes is how many signals are measured instead of unknown.

  1. Run both on the spec that came with your fork. Lint prints its warnings and moves on. For the score, read three parts of the output: the Readiness line, the Doc coverage line, and the Value and Pts columns of the signal table. A signal worth 0 points is simple for an agent, and an unknown signal means the spec doesn't give the scorer enough to measure it:

    zsh — ~/postman-terminal-demo
    postman spec lint openapi.yamlpostman spec lint openapi.yaml
    ✖ 4 problems (0 errors, 4 warnings, 0 infos, 0 hints)
    postman spec ai-readiness openapi.yamlpostman spec ai-readiness openapi.yaml
    Readiness: 95/100 (Excellent)
    Complexity: 0.5/10 (Simple)
    Doc coverage: medium (3 signals unknown — readiness is partially evidenced)
    │ auth_required │ no │ 0 │
    │ total_endpoints │ 3 │ 0 │
    │ schema_depth │ 1 │ 0 │
    │ avg_response_size_kb │ unknown │ 0 │
    │ error_surface │ unknown │ 0 │
    │ error_codes_count │ 0 │ 0 │
    │ parameter_complexity │ medium │ 1 │
    │ rate_limiting │ unknown │ 0 │
    0/2 runoutput shown is an example

    The output also lists a few recommendations, and the signal table has more rows than shown here. error_surface is unknown because no operation documents an error response, so the scorer can't say what can go wrong.

  2. Add a gate. --min-score makes the command exit non-zero when the score is below the number you give it, which is how you'd fail a CI job. Set it above your score so you can see a gate fail:

    zsh — ~/postman-terminal-demo
    postman spec ai-readiness openapi.yaml --min-score 99; echo "exit code: $?"postman spec ai-readiness openapi.yaml --min-score 99; echo "exit code: $?"
    exit code: 1
    0/1 runoutput shown is an example
  3. Fix openapi.yaml. Every operation (each get and post) needs:

    • an operationId (for example listTasks, createTask, getTask)
    • a description (one sentence on what it does)
    • one documented client error response, such as "400" or "404", with a description

    The score doesn't measure operation IDs or descriptions, but agents pick operations by them, and the Postman Plugin module relies on them. You can edit by hand, or give a coding agent this prompt. It is deliberately narrow, because an agent left to "improve" a spec often adds auth schemes and a long list of error codes. Those are real complexity, and they will pull your score down:

    Your coding agent — ~/postman-terminal-demo

    Read AGENTS.md and postman/skills, then update `openapi.yaml`. For each of the three operations, add an `operationId` (listTasks, createTask, getTask), a one-sentence `description`, and exactly one documented client error response: 400 for listTasks and createTask, and 404 for getTask. Also add an `info.description`. Do not add authentication, security schemes, 5xx or 429 responses, new paths, or change any schemas. Then run `postman spec lint openapi.yaml` and `postman spec ai-readiness openapi.yaml`, and tell me the readiness score and how many signals are unknown, before and after.

    I updated `openapi.yaml`: added operationIds, descriptions and one 4xx response per operation, plus `info.description`. I made no other changes.
    • Readiness: 95/100 before, 95/100 after
    • Unknown signals: 3 before, 2 after (error_surface is now measured)
    Paste this into your agent · reply shown is an example, yours will differ
  4. Re-run both checks and compare. Here is what the same fix does to the starter spec:

    zsh — ~/postman-terminal-demo
    postman spec lint openapi.yamlpostman spec lint openapi.yaml
    postman spec ai-readiness openapi.yamlpostman spec ai-readiness openapi.yaml
    Readiness: 95/100 (Excellent)
    Doc coverage: medium (2 signals unknown — readiness is partially evidenced)
    │ error_surface │ 2 │ 0 │
    │ error_codes_count │ 2 │ 0 │
    0/2 runoutput shown is an example

    The score stays at 95, and that is the expected result. error_surface and error_codes_count moved from unknown and 0 to measured values, so the score is now better evidenced, not higher. The rate_limiting and response-size signals stay unknown until you add rate-limit headers or saved example responses.

    If your score went down, look at the signal table for the rows that gained points. Adding auth turns auth_required on, and documenting eight or more error codes puts error_surface in the high bucket. On this spec, adding bearer auth and eight error codes drops it from 95 to 60. That drop is real complexity the agent introduced, not a better or worse spec. Undo the extras, or keep them if your API genuinely needs them.

  5. Check the gate at a realistic threshold (70 is a common floor), then save:

    zsh — ~/postman-terminal-demo
    postman spec ai-readiness openapi.yaml --min-score 70postman spec ai-readiness openapi.yaml --min-score 70
    git save "Make the spec agent-ready"git save "Make the spec agent-ready"
    0/2 run

    The command exits 0 when the score is at or above 70, so it would pass in CI.

4

Build a Collection From the Terminal

A collection is a folder of YAML files you can diff and commit, and the CLI can build one with no GUI. You'll add three requests, each with a test.

  1. Create the collection:

    zsh — ~/postman-terminal-demo
    postman collection new "Tasks API"postman collection new "Tasks API"
    Created postman/collections/Tasks API
    0/1 runoutput shown is an example
  2. Add List tasks, a GET that expects a 200:

    zsh — ~/postman-terminal-demo
    postman collection request add "List tasks" --collection "Tasks API" && \ postman collection request update "List tasks" --collection "Tasks API" \ --method GET --url "{{baseUrl}}/tasks" \ --scripts 'test:pm.test("returns 200", () => pm.response.to.have.status(200));'postman collection request add "List tasks" --collection "Tasks API" && \ postman collection request update "List tasks" --collection "Tasks API" \ --method GET --url "{{baseUrl}}/tasks" \ --scripts 'test:pm.test("returns 200", () => pm.response.to.have.status(200));'
    Updated request "List tasks" (postman/collections/Tasks API/List tasks.request.yaml).
    0/1 runoutput shown is an example
  3. Add Create task, a POST with a JSON body that expects a 201:

    zsh — ~/postman-terminal-demo
    postman collection request add "Create task" --collection "Tasks API" && \ postman collection request update "Create task" --collection "Tasks API" \ --method POST --url "{{baseUrl}}/tasks" \ --body 'json:{"title":"Write the module"}' \ --scripts 'test:pm.test("returns 201", () => pm.response.to.have.status(201));'postman collection request add "Create task" --collection "Tasks API" && \ postman collection request update "Create task" --collection "Tasks API" \ --method POST --url "{{baseUrl}}/tasks" \ --body 'json:{"title":"Write the module"}' \ --scripts 'test:pm.test("returns 201", () => pm.response.to.have.status(201));'
    Updated request "Create task" (postman/collections/Tasks API/Create task.request.yaml).
    0/1 runoutput shown is an example
  4. Add Get task, a GET for a single task that expects a 200:

    zsh — ~/postman-terminal-demo
    postman collection request add "Get task" --collection "Tasks API" && \ postman collection request update "Get task" --collection "Tasks API" \ --method GET --url "{{baseUrl}}/tasks/1" \ --scripts 'test:pm.test("returns 200", () => pm.response.to.have.status(200));'postman collection request add "Get task" --collection "Tasks API" && \ postman collection request update "Get task" --collection "Tasks API" \ --method GET --url "{{baseUrl}}/tasks/1" \ --scripts 'test:pm.test("returns 200", () => pm.response.to.have.status(200));'
    Updated request "Get task" (postman/collections/Tasks API/Get task.request.yaml).
    0/1 runoutput shown is an example
  5. Lint the collection, then save. collection lint checks the YAML files on disk (valid structure, well-formed requests and scripts) without sending any requests. It exits non-zero on errors, so it's the same check you'd put in CI:

    zsh — ~/postman-terminal-demo
    postman collection lint "postman/collections/Tasks API"postman collection lint "postman/collections/Tasks API"
    git save "Add the Tasks API collection"git save "Add the Tasks API collection"
    0/2 run
Tip: Already have a cURL command? postman collection import "<curl command>" turns it into a collection.
5

Create a Local Environment

Environments hold values that change between targets, like the base URL, so one collection can run against a mock today and a real server tomorrow. Your requests already use {{baseUrl}}, so you'll define it here. Locally, an environment is a single YAML file.

  1. Create a Local environment, set baseUrl, read it back and lint it, then save. environment lint does for environment files what collection lint did for the collection: it checks the YAML is valid before anything depends on it. Point it at the postman/environments folder and it checks every file in there:

    zsh — ~/postman-terminal-demo
    postman environment new "Local"postman environment new "Local"
    postman environment var set baseUrl http://localhost:4010 -e postman/environments/Local.environment.yamlpostman environment var set baseUrl http://localhost:4010 -e postman/environments/Local.environment.yaml
    Variable "baseUrl" set in local environment.
    postman environment var get baseUrl -e postman/environments/Local.environment.yamlpostman environment var get baseUrl -e postman/environments/Local.environment.yaml
    http://localhost:4010
    postman environment listpostman environment list
    postman environment lint postman/environmentspostman environment lint postman/environments
    git save "Add the Local environment"git save "Add the Local environment"
    0/6 runoutput shown is an example

    The file is plain YAML, so cat postman/environments/Local.environment.yaml shows the baseUrl entry you just set.

Note: Keep secrets out of this file. Use postman environment var set <key> --secret-id <id> to link a variable to a shared-vault secret instead of committing a value.
6

Generate and Run a Mock Locally

A mock lets you build and test a client before the real backend exists. The CLI generates one from your spec, and it lives in the repo as code. postman request is the terminal version of a request tab. You'll use two terminals: one serves the mock, one calls it.

  1. In terminal 1, generate the mock and start it. mock run keeps the window busy, so leave it running:

    terminal 1 — mock server
    postman mock generate ./openapi.yaml --name "Tasks Mock" --port 4010postman mock generate ./openapi.yaml --name "Tasks Mock" --port 4010
    Mock generated from spec: Tasks Mock
    Location: postman/mocks/tasks-mock
    Config: config.yaml
    postman mock run postman/mocks/tasks-mock/config.yamlpostman mock run postman/mocks/tasks-mock/config.yaml
    0/2 runoutput shown is an example
  2. Open terminal 2 in the repo folder. Call the mock, then run your whole collection against it with the Local environment. When you're done, Ctrl+C the mock in terminal 1 and save (git save works in any terminal in this repo):

    terminal 2 — client
    postman request GET http://localhost:4010/taskspostman request GET http://localhost:4010/tasks
    postman request POST http://localhost:4010/tasks \ -H "Content-Type:application/json" -d '{"title":"Hello from the terminal"}'postman request POST http://localhost:4010/tasks \ -H "Content-Type:application/json" -d '{"title":"Hello from the terminal"}'
    # your whole collection, with the Local environment, against the mock
    postman collection run "postman/collections/Tasks API" -e postman/environments/Local.environment.yamlpostman collection run "postman/collections/Tasks API" -e postman/environments/Local.environment.yaml
    # then Ctrl+C the mock in terminal 1 and save
    git save "Add Tasks mock"git save "Add Tasks mock"
    0/4 run