Sharing API Simulations Across Coding Agent Sessions

A coding agent working on a checkout endpoint needs to know more than the file it’s editing. It needs to understand how Inventory reserves stock, what Payments returns when a charge is declined, and what the right behavior is when either service goes quiet. Before it can verify anything, it also needs somewhere to make those calls.

Multiply that by every developer, every repo, and every fresh agent session, and your team ends up paying for the same learning over and over. The agent reads dependency code, interprets the API contract, spins up a throwaway mock, and troubleshoots a local environment. Tokens burn. Time burns. And none of that work compounds for the next session.

I’ve been experimenting with Postman simulations as a way to make that knowledge reusable across agents. The idea is simple: the team that owns a service maintains a callable model of its API, including the failure cases consumers should handle. Any agent working on a dependent service can discover that simulation, run it locally, and start from shared ground instead of rediscovering the behavior from scratch.

Here’s what that looked like in practice.

The setup: two agents, one shared simulation

I ran two Claude Code sessions against the same workspace.

Agent A played the role of the dependency owner. It generated mocks for Inventory and Payments from their OpenAPI specifications, composed a baseline simulation, and then added three failure variants that consumers need to handle:

• Inventory out-of-stock → 409 Conflict
• Payment declined → 402 Payment Required
• Payment timeout → an 8-second delayed response

Agent A published all four simulations to a Postman workspace so they’d be discoverable later.

Agent B built a real Node.js checkout service that called those mocks over HTTP. To keep the local setup boring, we put both dependencies behind a single port with path routing:

// checkout service, calling the shared simulation
const INVENTORY_URL = 'http://localhost:4000/inventory/reservations';
const PAYMENTS_URL = 'http://localhost:4000/payments/charges';

async function checkout(order) {
  const reservation = await fetch(INVENTORY_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ sku: order.sku, qty: order.qty }),
  });

  if (reservation.status === 409) {
    return { status: 409, reason: 'out_of_stock' };
  }

  const { reservation_id } = await reservation.json();

  const charge = await fetch(PAYMENTS_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ amount: order.amount, token: order.token }),
    signal: AbortSignal.timeout(3000),
  });

  if (charge.status === 402) {
    // compensate: release the reservation
    await fetch(`${INVENTORY_URL}/${reservation_id}`, { method: 'DELETE' });
    return { status: 402, reason: 'payment_declined' };
  }

  return { status: 201, reservation_id };
}

Agent B didn’t need to read Inventory or Payments source code. It fetched the simulation, ran it, and started coding against known behavior.

Running the simulation locally

The consumer side uses the Postman CLI to pull and run a published simulation. The agent runs something like this:

# list simulations available in the workspace
postman simulation list

# pick a simulation ID and run the baseline simulation on port 4000
postman simulation run <simulation-id> --port 4000

That’s the whole handoff. The dependency owner published; the consumer runs. No one wrote a bespoke mock server, no one spun up a Docker Compose with fake services, no one hand-wrote fixture JSON for the fourth time this quarter.

To test a different scenario, Agent B stopped the baseline and ran one of the failure variants on the same port. Same contract, different behavior.

What we found

Four runs, four different outcomes, and one of them was genuinely useful.

Scenario	Mock behavior	Checkout result
Baseline	201 from both services	201 Created
Out of stock	Inventory returns 409	409, no charge attempted
Payment declined	Payments returns 402	402, Checkout called DELETE /inventory/reservations/{id} to compensate
Payment timeout	Payments delays 8 seconds	Checkout aborted at 3s, outcome unknown

The first three were green lights. The compensation path for a declined payment worked exactly as the contract implied it should.

The fourth was the one worth having. Checkout’s 3-second client timeout fired before the mock’s 8-second response, which left the service in the worst possible state: the remote charge might have succeeded, might have failed, and Checkout had no way to know. That’s not a bug the agent would have found by reading code. It only surfaces when something responds slowly, which is exactly what a shared simulation can do on demand.

Handling that correctly means payment status checks, idempotent retries, and some kind of order reconciliation. The simulation didn’t fix the problem, but it made the problem visible in minutes instead of in production.

Why this matters for agent sessions

Fresh agent sessions start with no memory. That’s the whole premise. Every time a new session boots up to work on a service, it has to reconstruct a mental model of its dependencies. If reconstruction means reading source, writing throwaway mocks, and guessing at failure modes, you’re paying for the same reasoning on repeat.

Shared simulations turn that reasoning into an artifact. The dependency owner captures it once, including the awkward failure cases, and every consumer agent that follows gets to start from there. The simulation becomes a form of durable team knowledge that an agent can execute against, not just read.

The nice part is the simulation lives next to the API contract. If the contract changes, the simulation changes. If a new failure mode comes up in production, the owning team adds a variant and every downstream agent inherits the ability to test against it.

Simulation also collapses the wiring cost. An agent points one port at the whole simulated dependency graph instead of discovering and editing N separate configuration points for N separate mocks. The durable artifact isn’t just the failure-mode knowledge. It’s a one-step way to act on it.

Where this fits in the agentic SDLC

A few places this pattern earns its keep:

• Implementation. Agents build against known behavior instead of inferring it from code. Fewer “I assumed Payments would return 400 here” mistakes.
• Testing. Failure cases that are painful to trigger in a real environment (timeouts, specific error codes, partial outages) become one-line replays.
• Review. The simulation itself is reviewable. A human can look at what assumptions an agent is coding against and push back if they’re wrong.
• CI/CD. The same scenarios can run in a pipeline. Regressions in how a consumer handles a 402 or a timeout get caught before they ship.

How to start without boiling the ocean

Don’t try to simulate your entire system. Pick one service boundary that your team keeps explaining to new engineers (or re-explaining to new agent sessions). Have the owning team capture the baseline behavior and one meaningful failure case in a maintained simulation. Publish it to a workspace where consumer agents can find it.

That’s enough to start. The second boundary is easier because the pattern is already there. The third is easier still.

The thing I keep coming back to from the Claude Code runs: the timeout bug was free. We didn’t set out to find it. It fell out of running the consumer against a simulation that modeled a slow dependency, which is the kind of test you’d normally skip because setting it up is annoying. When the setup cost drops to a single command from the Postman CLI, you run that test, and the bug surfaces before a customer finds it.

Clone one of your service specifications, generate a mock from it, add the one failure case your on-call rotation complains about most, and share it. See what the next agent session does with it.

Resources

• Simulate API conditions (Postman Docs): The reference for building simulations that package multiple mocks and definitions you can run locally or in a shared workspace.
• Postman CLI command reference: Covers postman simulation list and postman simulation run --port for pulling and running shared simulations from a consumer environment.
• Postman CLI overview: Install guide and context for using the Postman CLI in local development and CI/CD.
• OpenAPI Specification: The specification format most teams use to describe APIs, and a natural source for generating mocks.
• RFC 9110: HTTP Semantics: Authoritative reference for status codes (402, 409) and idempotency semantics referenced in the compensation and retry patterns above.
• Claude Code documentation: Background on the coding agent used in the two-session experiment.