The trickiest part of shipping an API change isn’t the code. It’s finding everyone who calls your endpoint before you break them. Rename user_id
to userId
on a GET /users/:id
response and your endpoint compiles, your tests pass, and somewhere else in the org a mobile team’s login flow silently returns null
on Tuesday morning.
Coding agents don’t help much here. They can read the repo in front of them, but they can’t tell you which mobile app fetches this endpoint at boot, which nightly job depends on the response shape, or which partner integration is contract-tested against the old field name.
That’s what the Postman AI Engineer works on before it writes code. It walks the Postman Context Graph to find every downstream consumer of a change, then opens PRs across every repo that needs to move together.
Why multi-repo API work is hard #
In any organization past its first few services, one team’s API is another team’s dependency. A /customers
endpoint gets called by a billing worker, a customer support UI, a mobile app, and a partner-facing collection you forgot existed. Rename a field and any of those consumers can break without a compile error.
Code search only sees one repo at a time. A grep
for the endpoint path works if every consumer literally hardcodes the URL, but most services abstract HTTP calls behind clients, gateways, or generated SDKs. The dependency exists at runtime, not in the source tree, which is why refactors like this usually turn into a week of Slack messages instead of a code change.
The Context Graph fixes this by keeping a live index of API relationships the way they actually run, not the way they appear in a single codebase. It indexes both your Postman artifacts (APIs, collections, specifications, environments, workspaces, monitors) and the source code in your connected repos, on the backend and the frontend. When the graph tells you who calls /customers
, it’s pulling from real code and real requests, not from a wiki page.
What the Context Graph knows about your APIs #
The graph is a purpose-built knowledge graph for API dependencies. Every artifact in your workspace and every connected repo shows up as a node:
| Node type | What it represents |
|---|---|
| API | A service, usually with an |
Edges connect these nodes based on real behavior. A route handler in a backend repo has an edge pointing at the API that owns the endpoint it serves. A fetch('/users/' + id)
call in a React component has an edge pointing at the same API. A collection with a request against GET /users/:id
gets the same edge. A monitor that runs the collection has an edge pointing at the collection. A workspace has an edge pointing at every API and collection it contains.
The graph is continuously updated as code lands and specs change, so it stays honest about what your systems actually do, not what a wiki page said they did in 2023.
A rename that used to take a week #
Here’s the classic scenario. You want to rename user_id
to userId
in the response of GET /users/:id
because you’ve moved to camelCase for new fields, and this endpoint is finally on the list.
Without the graph, this is a week of Slack messages. You post in #eng-general
, wait for owners to raise their hands, chase the ones who don’t respond, and hope you caught everyone before the change hits main
.
With the Postman AI Engineer, you hand it the task and it queries the graph first. The traversal looks something like this:
1. Find the API node for /users
2. Find every backend route handler that serves GET /users/:id
3. Find every call site in frontend and backend repos that hits GET /users/:id
4. Find every Postman Collection with a request against GET /users/:id
5. For each consumer, walk to the owning repo, workspace, and team
6. Find test scripts, unit tests, and integration tests that assert on user_id
7. Find every mock server that stubs GET /users/:id
8. Find every monitor scheduled against those collections
9. Return the impact set with owning teams and consumer classification
The output is a real list, not a guess. In a typical org, it looks like this:
**user-service
backend repo** (owned by the identity team): route handlerGET /users/:id
returns aUserResponse
DTO with auser_id
field**mobile-app
frontend repo** (owned by the mobile team): three call sites parseresponse.user_id
in the login and profile flows**web-dashboard
frontend repo** (owned by the frontend team): one call site reads the field into a TypeScript type**billing-worker
backend repo** (owned by the payments team): a nightly job joins onuser_id
from the response**mobile-app-qa
collection** (owned by the mobile team): assertspm.expect(response.user_id).to.exist
in three tests**partner-integration-suite
collection** (owned by DevRel): contract-tests the field name against aJSON Schema
Now you know exactly which teams to talk to and what each of their consumers does with the field. The dread part of the refactor is done before you’ve touched a line of code.
Making the change across repos in one run #
Here’s where the AI Engineer earns its keep. Once it has the impact list, it can propose changes across every affected repo in a single run.
You kick it off from Postman Agent Mode with a prompt like this:
Rename user_id to userId in the GET /users/:id response.
Update this response, the frontend code, the backend code, and anything else that needs to be updated.
The AI Engineer runs in a sandboxed cloud environment with access to your connected repos through Native Git. It pulls each repo, edits the code and specs, updates any collections stored in the repo, runs the local tests, and opens a PR against the default branch. Backend, frontend, and Postman changes all move together.
What I like most is that every PR description carries the graph context that triggered it. You don’t have to reverse-engineer why the AI Engineer touched a repo. The description says something like:
This repo owns the
mobile-app-qa
collection, which asserts onuser_id
in three test scripts. Updating those assertions to match the new field name in the response.
The test scripts get updated in the same PR:
// Before
pm.test("Response contains user_id", () => {
const body = pm.response.json();
pm.expect(body.user_id).to.exist;
pm.expect(body.user_id).to.be.a('string');
});
// After
pm.test("Response contains userId", () => {
const body = pm.response.json();
pm.expect(body.userId).to.exist;
pm.expect(body.userId).to.be.a('string');
});
Because collections are now versioned alongside code in a diff-friendly YAML format, the reviewer sees the assertion change the same way they’d see a source code change. No opaque JSON blobs.
The consumer classification is what makes this safe #
Not every downstream consumer carries the same risk. A mock server pretending to be your API doesn’t care about your rename until a real client hits it. A contract test in a partner integration cares immediately. A monitor cares tomorrow morning when it wakes up.
The AI Engineer classifies each consumer before proposing a change. You can see the classification on each PR description, and it looks something like this in the audit trail:
{
"consumer": "partner-integration-suite",
"owner_team": "devrel",
"consumer_type": "contract_test",
"urgency": "blocking",
"requires_coordination": true,
"auto_updatable": false
}
Contract tests and monitors get flagged as blocking. Mock servers and internal QA collections get flagged as auto_updatable
, meaning the AI Engineer opens a mechanical PR without waiting for a coordination cycle. That distinction is what lets you actually ship a cross-repo rename in a day instead of a sprint.
Try this against your own workspace #
Open Postman Agent Mode in a workspace that has a few APIs and collections in it, and give it a scoped, read-only task first:
Show me every downstream consumer of GET /orders/:id.
Group them by owning team and consumer type.
Don't make any changes yet.
You get back a list of collections, tests, monitors, and mocks that touch that endpoint, with the owning workspace for each. If your APIs and collections live in Postman, you’ll see the same kind of dependency map I walked through above.
From there, escalate to actual changes. Ask it to rename a field, add a required query parameter, or deprecate an endpoint. It’ll walk the graph, propose PRs, and wait for you to approve.
Gotchas I’ve hit #
The graph is only as good as what you connect to it. Repos that aren’t connected to Postman aren’t in the graph, and neither are call sites hidden behind a completely dynamic URL builder. Standardize on connecting your service and app repos, and on collections for contract tests, so the impact map matches reality. Every repo you connect makes the next multi-repo change safer.
Auto-updatable is not the same as auto-shipped. Even mechanical rename PRs land in review. The AI Engineer never merges for you. That’s a design choice, not a limitation. You want a human on the final button when a change touches five repos.
Read the classification before you approve. I’ve caught myself skimming a PR title and reaching for merge, only to notice the classification says the change is blocking on a partner team I hadn’t looped in. The consumer classification is in the description for a reason.
** Native Git changes the picture.** When collections and specifications version alongside your code, the graph updates on every push. Without it, you’re relying on the cloud copy of the collection to stay current, which works but adds a step you have to remember.
Where this goes next #
Multi-repo API changes have always been a coordination problem more than a code problem. What the Context Graph does is push the coordination into a place where an agent can actually reason about it. The rename I walked through used to take a week of Slack. It now takes a run.
If you want to see the graph in action, pick a real change you’ve been avoiding because of the blast radius. Ask the AI Engineer to map the consumers first, and see what comes back. It’s usually more (and different) than you remembered.
Resources #
Introducing the AI Engineeron the Postman blogManaging downstream dependencies with the AI EngineerWhy context beats code alone for spec driftPostman Agent Mode overviewin Postman DocsNative Gitin Postman DocsPostman AI features overviewin Postman DocsThe New Postman is herefor context on Git-native workflows