Mock servers

A mock server answers requests with the responses you saved as examples in a collection, without the real API. Use it to build a front end or mobile app before the backend exists, to test how a client handles errors, or to work offline. Each collection can have its own mock server on localhost, matched by method and path like Postman’s mock servers, with a live log of every call.

12345

A running mock server: its routes on the left and the call log on the right.

1. Port (0 picks a free port), response delay and CORS
2. The mock's URL, Copy, and Save as {{mockUrl}}
3. Stop the mock server
4. Routes: one per saved example, with its status and name
5. Calls: each request the mock answered and the example it used

×

Add examples first

A mock server can only answer with examples. A collection gets examples in three ways:

• Send a request, then click Save as Example in the response viewer. See Examples and docs.
• Import an OpenAPI spec or generate a collection from a spec. Each documented response becomes an example.
• Import a Postman collection that already has examples.

Each example stores the method and URL it answers, a status code, headers and a body. The collection’s Overview tab shows how many examples it has.

Start a mock server

1. Open the collection and click Mock in its header. You can also right-click the collection in the sidebar and choose Mock Collection, or click Mocks in the left rail and pick the collection.

   A tab named Mock · Collection name opens, listing the collection’s examples under Routes.

2. Optionally set the Port, a response Delay, and CORS. See Settings.

3. Click Start Mock Server.

   The mock’s URL appears, for example http://localhost:49560. In the Mock Servers section of the sidebar, a green dot and the port show which collections are being served.

4. Send requests to that URL from your app, a browser, curl or another request in Cloak Proxy.

   Terminal

   curl http://localhost:49560/v1/pets/1

5. Click Stop when you’re done.

Start Mock Server is disabled until the collection has at least one example. If the port is already in use, the tab shows Couldn’t start on port with the reason.

The mock listens on this Mac only

Mock servers listen on 127.0.0.1, so only apps on this Mac can reach them. A simulator on this Mac can use localhost. Another device or a teammate can’t connect unless you expose the port yourself, for example with a tunnel. Anything the mock serves is then visible to whoever has the URL.

Settings

Setting	Default	What it does
Port	0 (auto)	The port to listen on. Leave it at 0 to pick a free port each time you start.
Delay	0 ms	Waits this long before every response, from 0 to 30,000 ms in steps of 100. Use it to see loading states and timeouts in your app.
CORS	On	Adds CORS headers to every response and answers browser preflight requests, so a web app on another origin can call the mock.

While the mock’s tab is open, changes apply to the running server right away: a new delay or CORS setting, and edits to the collection. Add or change an example and the mock serves it on the next request, without a restart.

How requests are matched

When a request arrives, the mock picks one example:

1. Method and path must match. The example’s method must equal the request’s method (an example with method ANY matches every method), and the paths must have the same number of segments. Each segment must be equal, or the example’s segment must be a path variable (:id) or a variable ({{petId}}), which match anything. Segments are also compared after URL decoding.

2. A header can choose the example. If the request has an x-mock-response-id, x-mock-response-name or x-mock-response-code header, the mock uses the first matching example that header points to. See Choose an example with headers.

3. Otherwise the best match wins. Each candidate gets a score, and the highest score is used. If two examples tie, the first one in the collection wins.

The host and scheme of the example’s URL are ignored. Variables in example URLs are filled in from the collection’s variables and the environment that was active when you started the mock. So an example saved for {{baseUrl}}/pets/:petId, with baseUrl set to https://api.example.com/v1, answers GET /v1/pets/1. If the leading variable has no value, it’s dropped and the rest of the path is matched.

How examples are scored

Rule	Points
Each path segment that matches exactly (not through a :variable)	+10
Each query parameter in the example that the request has with the same value	+5
Each query parameter in the example that the request doesn’t have at all	−3
The example’s status code is 2xx	+1

So /pets/mine beats /pets/:petId for a request to /pets/mine, an example saved for ?status=sold wins when the request asks for status=sold, and a success response wins over an error response for the same route unless you ask for the error.

Choose an example with headers

Send one of these request headers to pick a specific example among the ones that match the method and path. The mock checks them in this order:

Header	Value	Example
x-mock-response-id	The example’s ID (not case-sensitive).	x-mock-response-id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
x-mock-response-name	The example’s name, exactly.	x-mock-response-name: Not found
x-mock-response-code	A status code; the first example with that code.	x-mock-response-code: 404

Ask for the error example

curl http://localhost:49560/v1/pets/1 -H "x-mock-response-code: 404"

If no example matches the header, the mock falls back to scoring.

What the mock sends back

Part	Value
Status	The example’s status code.
Headers	The example’s enabled headers, except Content-Length, Transfer-Encoding and Content-Encoding, which the mock sets itself.
X-Cloak-Mock-Example	Added to every matched response, with the example’s name, so you can see which example answered.
Body	The example’s body, with {{variables}} and dynamic variables such as {{$randomUUID}} filled in. HEAD requests get no body.
CORS headers	When CORS is on: Access-Control-Allow-Origin (the request’s Origin, or *), Access-Control-Allow-Methods (GET, POST, PUT, PATCH, DELETE, OPTIONS) and Access-Control-Allow-Headers (the headers the browser asked for, or *).

When CORS is on, a preflight request (OPTIONS with an Access-Control-Request-Method header) gets an empty 204 response.

Requests with no match

A request that matches no example gets a 404 with a JSON body that says which request wasn’t matched:

{
  "error": {
    "name": "mockRequestNotFoundError",
    "message": "No example matches GET /v1/orders. Save an example on the request in Cloak Proxy."
  }
}

The call log shows these in red with no match.

The call log

Calls lists every request the mock answered, newest first, with:

• the time,
• the method and path (with the query string),
• the status sent: green when an example matched, red when nothing matched,
• the name of the example used, or no match.

Use it to see exactly what your app requests, and to spot paths you haven’t saved an example for yet. The log stays while the app is open.

Point your app at the mock

While the mock runs, three buttons sit next to its URL:

Button	What it does
Copy	Copies the URL, such as http://localhost:49560.
Save as {{mockUrl}}	Saves the URL as the collection variable mockUrl (creating it, or updating it if it exists). Use {{mockUrl}} in requests to send them to the mock.
Stop	Stops the server. Saved examples and the collection aren’t changed.

A handy pattern: keep two environments where baseUrl points at the real API in one and at the mock URL in the other, then switch between them.

Tip

Pick a fixed Port (for example 4010) when an app or config file needs a URL that doesn’t change between runs.

Run a mock from the command line

cloakctl mock serves a collection’s examples without the app open. It works with a collection in the workspace, a Postman collection file, or an OpenAPI spec file (whose documented responses become examples).

Terminal

cloakctl mock "Petstore" --port 4010

Output

Mock server for “Petstore” on http://localhost:4010 (4 examples). Ctrl-C to stop.
GET /v1/pets → 200 (OK)
GET /v1/pets/42 → 404 (Not found)
GET /v1/orders → 404 (no example)

Argument or flag	What it does
NAME or FILE	A collection in the workspace (by name or ID), or a Postman collection or OpenAPI file.
--port N	The port. Default 0 picks a free port.
--workspace DIR	Use a different workspace folder.

The command uses the workspace’s active environment to fill in variables, and prints one line per call. Press ⌃ C to stop. AI assistants connected to the Cloak Proxy MCP server can use the start_mock_server, list_mock_servers and stop_mock_server tools.

Mock servers and Mock Sets

Cloak Proxy has two ways to fake an API:

	Mock servers (this page)	Mock Sets
What answers	A local server with its own URL	The proxy, for the real host
Your app needs to	Call the mock’s URL	Send its traffic through Cloak Proxy
Responses come from	A collection’s saved examples	Captured responses
Best for	Building against an API that isn’t ready	Demoing or testing an app offline without changing its URLs

Related

Examples and docsSave the responses a mock serves.

SpecsGenerate a collection with examples from OpenAPI.

Mock a backendA step-by-step guide.

Mock SetsAnswer requests from the proxy instead.