Documentation — MockRoute

Getting Started

1. Create an Endpoint

After signing up, click New Endpoint on your dashboard. Choose a subdomain — this becomes your unique base URL:

Base URL: https://mockroute.com/mock/your-subdomain

Your endpoint accepts any HTTP method at any path beneath this base URL — with no further configuration needed.

2. Make Your First Request

Hit your endpoint with any HTTP client:

# GET request

curl https://mockroute.com/mock/my-api/users

# POST with JSON body

curl -X POST \

-H "Content-Type: application/json" \

-d '{"name":"Alice"}' \

https://mockroute.com/mock/my-api/users

If no mocking rule matches, you'll receive a 404 JSON response. Define rules to customise the response.

Mocking Rules

Mocking rules define how MockRoute responds to incoming requests. Each rule specifies a method + path combination and the response to return.

Field	Description	Example
Name	Human-readable label for the rule	Get all users
Method	HTTP method to match	GET, POST, PUT…
Path	URL path to match (supports wildcards)	/users, /users/*
Status Code	HTTP response status to return	200, 201, 404, 500
Response Body	JSON or any text body to return	{"users":[]}
Response Headers	Extra headers on the response	X-Custom: value
Delay	Simulate slow APIs (ms)	500 → 500ms delay
Priority	Higher = matched first when paths overlap	10

Path Matching

Paths are matched against the portion of the URL after your subdomain. Use * as a wildcard segment.

/users

Exact match — only /users

/users/*

Matches /users/1, /users/abc, etc.

/users/1

Exact match — only /users/1

/orders/*/items

Matches /orders/5/items

Priority

When multiple rules match the same request, the rule with the highest priority number wins. Default priority is 0. Set priority 10 on a rule to ensure it takes precedence over others with 0.

Simulating Delay

Set a delay (in milliseconds) on a rule to simulate slow network or database conditions. Useful for testing loading states and timeout handling in your UI.

Request Logs

Every request to your endpoint is captured and stored. The logs page gives you a full breakdown including method, path, matched rule, status code, response time, and timestamps.

Request Inspector

Click any row in the logs table to open the Request Inspector. It shows four tabs:

Request Body — the payload sent to your endpoint
Response Body — what MockRoute returned
Request Headers — all headers from the caller
Response Headers — headers included in the response

Clearing Logs

Use the Clear All Logs button on the logs page to permanently delete all request history for an endpoint. This action is irreversible.

Request Forwarding Pro

Request Forwarding proxies all incoming requests to a real backend URL and returns the real response — while still logging the full request/response in MockRoute. Perfect for intercepting and inspecting live traffic.

Setup

Open your endpoint's detail page
Scroll to Request Forwarding and toggle it on
Enter your target URL (e.g. https://api.example.com)
Save — all requests will now be proxied to that URL

Note: Mocking rules still take precedence when forwarding is enabled. Only requests with no matching rule are forwarded.

OpenAPI Import Pro

The OpenAPI Import feature lets you upload an OpenAPI 3.x or Swagger 2.0 specification file and instantly generate a full set of mocking rules — one per operation defined in your spec. No manual rule creation required.

Pro feature: OpenAPI Import is available on the Pro and Business plans. Upgrade to unlock →

Import Steps

Open an endpoint's detail page and click Import OpenAPI
Paste your spec as JSON/YAML or drag-and-drop a .json / .yaml file
MockRoute parses every path + method combination and creates a mocking rule for each
Response bodies are auto-generated from the spec's schema.example values where available, otherwise sensible defaults are used
Review and edit the generated rules as needed

Notes & Limits

Supports OpenAPI 3.0 / 3.1 and Swagger 2.0
Path parameters (e.g. /users/{id}) are converted to wildcard rules (/users/*)
Existing rules with the same method + path are overwritten during import
Maximum spec file size: 1 MB
External $ref references to remote URLs are not resolved during import

Dynamic Responses Pro

Dynamic Responses let you embed template expressions directly in your rule's response body. Each request evaluates the template fresh, producing randomised or request-contextual data — without writing any backend code.

Pro feature: Dynamic Responses are available on the Pro and Business plans. Upgrade to unlock →

Template Syntax

Use {{ expression }} placeholders in your response body. Available helpers:

Expression	Output
{{ faker.uuid }}	A random UUID v4
{{ faker.name }}	A random full name
{{ faker.email }}	A random email address
{{ faker.integer(1,100) }}	Random integer between 1 and 100
{{ faker.boolean }}	true or false randomly
{{ faker.isoDate }}	Current timestamp in ISO 8601
{{ request.method }}	The HTTP method of the request
{{ request.path }}	The path of the incoming request
{{ request.header.X-User-Id }}	Value of a specific request header
{{ request.body.name }}	Top-level field from a JSON request body

Examples

Create user — echo back a generated ID and the submitted name:

{
  "id": "{{ faker.uuid }}",
  "name": "{{ request.body.name }}",
  "createdAt": "{{ faker.isoDate }}"
}

List endpoint — return a random number of items:

{
"total": "{{ faker.integer(1, 50) }}",
"items": []
}

Local Tunnel Pro

The MockRoute Local Tunnel exposes a locally running server (e.g. localhost:3000) to the internet via a stable MockRoute subdomain. All traffic is logged in your MockRoute dashboard, giving you real-time inspection of webhooks and external callbacks hitting your local machine.

Pro feature: Local Tunnel is available on the Pro and Business plans. Upgrade to unlock →

1. Install the CLI

The mockroute CLI is available via npm or as a standalone binary:

# Install globally via npm

npm install -g @mockroute/cli

# Or via Homebrew (macOS / Linux)

brew install mockroute-cli

# Verify installation

mockroute --version

2. Authenticate

Log in with your MockRoute API key. Find your key under Account → API Key.

# Authenticate the CLI with your API key

mockroute auth YOUR_API_KEY

Your key is stored locally in ~/.mockroute/config.json and never transmitted except to the MockRoute tunnel server.

3. Run a Tunnel

Start a tunnel forwarding to your local server. Specify the local port and optionally a subdomain:

# Forward localhost:3000 → auto-assigned subdomain

mockroute tunnel --port 3000

# Use a named subdomain (must match an endpoint you own)

mockroute tunnel --port 3000 --subdomain
                                        my-app

# Forward HTTPS local server

mockroute tunnel --port 8443 --https
                                        --subdomain my-app

Once running, the CLI prints your public tunnel URL:


                                    ✔ Tunnel ready: https://mockroute.com/mock/my-app

                                    → Forwarding to http://localhost:3000

                                    → Logging at https://mockroute.com/endpoints/my-app/logs

4. Inspect Traffic

All requests routed through the tunnel are logged to your MockRoute dashboard in real time. Open the Request Logs page for the tunnelled endpoint to:

View every request and its full headers, body, query parameters
Inspect the response your local server returned
Replay any request to trigger it again against your local server
Export log entries as JSON for debugging

Tip: Use tunnel logging to debug webhooks from third-party services (Stripe, GitHub, Twilio, etc.) — point them at your MockRoute tunnel URL and inspect the full payloads instantly.

Stateful Mock Servers Pro

Stateful Mock Servers allow your endpoint to remember data across requests. Instead of always returning a fixed response, the server maintains an in-memory store that your rules can read from and write to — simulating real CRUD behaviour.

Pro feature: Stateful Servers are available on the Pro and Business plans. Upgrade to unlock →

Setup

Open your endpoint's detail page and enable Stateful Mode in the settings panel
Define a seed dataset — the initial in-memory state as a JSON object (e.g. {"users": []})
Use the state helpers in your rule response bodies:

Helper	Description
{{ state.get("users") }}	Return the current value of the users key
{{ state.push("users", request.body) }}	Append the request body to the users array
{{ state.set("users", []) }}	Overwrite a key with a new value
{{ state.delete("users", request.path[2]) }}	Remove item by ID from a collection

State is scoped per endpoint and persists for the lifetime of the session. Multiple concurrent clients share the same state, making it suitable for collaborative testing scenarios.

Resetting State

You can reset the endpoint state at any time:

Dashboard reset — click Reset State on the endpoint settings page to restore to the seed dataset
API reset — send DELETE https://mockroute.com/mock/{subdomain}/_state with your API key to reset programmatically (useful in CI/CD pipelines)
Auto-reset — optionally configure state to auto-reset after a set idle period (1h, 24h, or on each test run via the API)

# Reset state via API (e.g. in a CI teardown step)

curl -X DELETE \
  -H
                                    "X-Api-Key: YOUR_API_KEY" \
  https://mockroute.com/mock/my-app/_state

API Reference

The MockRoute mock handler accepts all requests at the following pattern:

ANY https://mockroute.com/mock/{subdomain}/{path?}

Authentication

Mock endpoint URLs require no authentication — they are publicly accessible by subdomain. Protect sensitive endpoints at the application level using mocking rule conditions.

Examples

REST API Mock — Users

Create these rules on an endpoint with subdomain my-api:

Method	Path	Status	Body
GET	/users	200	{"users": [{"id":1,"name":"Alice"}]}
POST	/users	201	{"id": 2, "name": "Bob"}
GET	/users/*	200	{"id": 1, "name": "Alice"}
DELETE	/users/*	204	(empty)

cURL Examples

# List users

curl <?php echo e(url('/mock/my-api/users')); ?>

# Create user

curl -X POST -H "Content-Type: application/json" -d '{"name":"Alice"}' <?php echo e(url('/mock/my-api/users')); ?>

# Get one user

curl <?php echo e(url('/mock/my-api/users/1')); ?>

# Delete user

curl -X DELETE <?php echo e(url('/mock/my-api/users/1')); ?>

MockRoute Docs

Getting Started

1. Create an Endpoint

2. Make Your First Request

Mocking Rules

Path Matching

Priority

Simulating Delay

Request Logs

Request Inspector

Clearing Logs

Request Forwarding Pro

Setup

OpenAPI Import Pro

Import Steps

Notes & Limits

Dynamic Responses Pro

Template Syntax

Examples

Local Tunnel Pro

1. Install the CLI

2. Authenticate

3. Run a Tunnel

4. Inspect Traffic

Stateful Mock Servers Pro

Setup

Resetting State

API Reference

Authentication

Examples

REST API Mock — Users

cURL Examples