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.
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.
-
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
0points is simple for an agent, and anunknownsignal means the spec doesn't give the scorer enough to measure it: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.yamlReadiness: 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 │The output also lists a few recommendations, and the signal table has more rows than shown here.
error_surfaceisunknownbecause no operation documents an error response, so the scorer can't say what can go wrong. -
Add a gate.
--min-scoremakes 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: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 -
Fix
openapi.yaml. Every operation (eachgetandpost) needs:- an
operationId(for examplelistTasks,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:
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) - an
-
Re-run both checks and compare. Here is what the same fix does to the starter spec:
postman spec lint openapi.yamlpostman spec lint openapi.yamlpostman spec ai-readiness openapi.yamlpostman spec ai-readiness openapi.yamlReadiness: 95/100 (Excellent)Doc coverage: medium (2 signals unknown — readiness is partially evidenced)│ error_surface │ 2 │ 0 ││ error_codes_count │ 2 │ 0 │The score stays at 95, and that is the expected result.
error_surfaceanderror_codes_countmoved fromunknownand0to measured values, so the score is now better evidenced, not higher. Therate_limitingand 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_requiredon, and documenting eight or more error codes putserror_surfacein thehighbucket. 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. -
Check the gate at a realistic threshold (70 is a common floor), then save:
postman spec ai-readiness openapi.yaml --min-score 70postman spec ai-readiness openapi.yaml --min-score 70git save "Make the spec agent-ready"git save "Make the spec agent-ready"The command exits
0when the score is at or above 70, so it would pass in CI.
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.
-
Create the collection:
postman collection new "Tasks API"postman collection new "Tasks API"Created postman/collections/Tasks API -
Add List tasks, a
GETthat expects a200: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). -
Add Create task, a
POSTwith a JSON body that expects a201: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). -
Add Get task, a
GETfor a single task that expects a200: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). -
Lint the collection, then save.
collection lintchecks 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: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"
postman collection import "<curl command>" turns it into a collection.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.
-
Create a
Localenvironment, setbaseUrl, read it back and lint it, then save.environment lintdoes for environment files whatcollection lintdid for the collection: it checks the YAML is valid before anything depends on it. Point it at thepostman/environmentsfolder and it checks every file in there: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.yamlVariable "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.yamlhttp://localhost:4010postman environment listpostman environment listpostman environment lint postman/environmentspostman environment lint postman/environmentsgit save "Add the Local environment"git save "Add the Local environment"The file is plain YAML, so
cat postman/environments/Local.environment.yamlshows thebaseUrlentry you just set.
postman environment var set <key> --secret-id <id> to link a variable to a shared-vault secret instead of committing a value.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.
-
In terminal 1, generate the mock and start it.
mock runkeeps the window busy, so leave it running:postman mock generate ./openapi.yaml --name "Tasks Mock" --port 4010postman mock generate ./openapi.yaml --name "Tasks Mock" --port 4010Mock generated from spec: Tasks MockLocation: postman/mocks/tasks-mockConfig: config.yamlpostman mock run postman/mocks/tasks-mock/config.yamlpostman mock run postman/mocks/tasks-mock/config.yaml -
Open terminal 2 in the repo folder. Call the mock, then run your whole collection against it with the
Localenvironment. When you're done,Ctrl+Cthe mock in terminal 1 and save (git saveworks in any terminal in this repo):postman request GET http://localhost:4010/taskspostman request GET http://localhost:4010/taskspostman 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 mockpostman 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 savegit save "Add Tasks mock"git save "Add Tasks mock"