# Multi-repo API changes with the Postman AI Engineer

> Source: <https://blog.postman.com/multi-repo-api-changes-with-the-postman-ai-engineer/>
> Published: 2026-08-13 16:00:00+00:00

# Multi-repo API changes with the Postman AI Engineer

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](https://blog.postman.com/introducing-the-ai-engineer/) works on before it writes code. It walks the [Postman Context Graph](https://blog.postman.com/managing-downstream-dependencies-with-the-ai-engineer/) 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](https://blog.postman.com/api-specification-drift-why-context-beats-code-alone/) 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](https://en.wikipedia.org/wiki/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](https://blog.postman.com/introducing-the-ai-engineer/) 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 handler`GET /users/:id`

returns a`UserResponse`

DTO with a`user_id`

field`**mobile-app`

frontend repo** (owned by the mobile team): three call sites parse`response.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 on`user_id`

from the response`**mobile-app-qa`

collection** (owned by the mobile team): asserts`pm.expect(response.user_id).to.exist`

in three tests`**partner-integration-suite`

collection** (owned by DevRel): contract-tests the field name against a[JSON Schema](https://json-schema.org/)

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](https://learning.postman.com/docs/use/agent-mode/overview) 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](https://learning.postman.com/docs/agent-mode/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 on`user_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:

``` js
// 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](https://blog.postman.com/new-postman-is-here/) 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](https://learning.postman.com/docs/use/agent-mode/overview) 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 Engineer](https://blog.postman.com/introducing-the-ai-engineer/)on the Postman blog[Managing downstream dependencies with the AI Engineer](https://blog.postman.com/managing-downstream-dependencies-with-the-ai-engineer/)[Why context beats code alone for spec drift](https://blog.postman.com/api-specification-drift-why-context-beats-code-alone/)[Postman Agent Mode overview](https://learning.postman.com/docs/use/agent-mode/overview)in Postman Docs[Native Git](https://learning.postman.com/docs/agent-mode/native-git/)in Postman Docs[Postman AI features overview](https://learning.postman.com/docs/postman-ai-agent-builder/overview/)in Postman Docs[The New Postman is here](https://blog.postman.com/new-postman-is-here/)for context on Git-native workflows