Mocking API Responses

When your backend isn’t ready—or you want to simulate specific responses—Inspectr lets you mock APIs based on an OpenAPI specification and override responses in real time.

Inspectr leverages Stoplight Prism behind the scenes, giving you access to both static and dynamic mocking powered by Faker and JSON Schema Faker.

Want a fast demo? Jump to theMocking Quick Start →

Use Cases

There a great articles about why and how it is useful to mock API responses:

Very common use cases for mocking are the following:

Frontend development before backend is available
Testing edge cases (timeouts, errors, unexpected payloads)
Demos and offline API development
Simulating invalid or large payloads for robustness testing

Providing OpenAPI for mocking

You can provide the OpenAPI documents as a local file or as a public URL by using the --mock-backend parameter.

Local File:

inspectr --mock-backend=./openapi.yaml

Public URL:

inspectr --mock-backend=https://inspectr.dev/demo/hello.openapi.yaml

Quick Launch OpenAPI mock

You can also launch an OpenAPI Mock using Inspectr, by just using the URL https://inspectr.dev/launch with a reference to any remote OpenAPI document:

https://inspectr.dev/launch?openapi=https://inspectr.dev/demo/hello.openapi.yaml

Replace the openapi parameter with the URL of your own OpenAPI file. Inspectr will start immediately with mocking enabled.

You can easily mock the typical OpenAPI example APIs, by clicking the launch link:

Museum API

by Redocly

Launch in Inspectr Visit the Direct URL

Train Travel API

by Bump.sh

Launch in Inspectr Visit the Direct URL

Galaxy API

by Scalar

Launch in Inspectr Visit the Direct URL

Mocking Authenticated APIs

Even endpoints that require authentication can be mocked with Inspectr.

Basic Authentication

Add a basicAuth security scheme and apply it to a path:

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
paths:
  /basic-auth-protected:
    get:
      security:
        - basicAuth: []
      responses:
        '200':
          description: Protected resource
          content:
            application/json:
              example:
                message: OK
        '401':
          description: Unauthorized

Start Inspectr as usual:

inspectr --mock-backend=./openapi.yaml

Then include credentials when calling the mock:

curl -u user:pass http://localhost:8080/basic-auth-protected

API Key Header

Define an API key scheme that expects a header:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
paths:
  /api-key-protected:
    get:
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                message: OK
        '401':
          description: Unauthorized

Start Inspectr with the spec and send the header:

curl http://localhost:8080/api-key-protected -H "X-API-Key: secret"

Try both authentication styles with this ready-to-use spec:

Launch Authenticated API example

Static Mocking

Static mocking uses predefined examples in your OpenAPI spec to return consistent, predictable responses.

Step 1: Prepare Your OpenAPI File

paths:
  /items:
    get:
      responses:
        '200':
          description: Success
          content:
            application/json:
              examples:
                default:
                  value:
                    items: ['A', 'B', 'C']

Save it as openapi.yaml.

Step 2: Start Inspectr in Static Mock Mode

inspectr --mock-backend=./openapi.yaml

Returns mock responses based on OpenAPI examples
No backend service needed
Captures requests in the Inspectr UI at http://localhost:4004

Step 3: Use Response Overrides

Use headers to simulate conditions or return different examples:

Header	Description
`inspectr-response-status`	Override status code (e.g. `404`, `500`)
`inspectr-response-delay`	Add artificial delay in milliseconds
`inspectr-response-example`	Choose a specific OpenAPI example by name
`inspectr-response-content-type`	Override `Content-Type` header

Example:

curl http://localhost:8080/items \
  -H "inspectr-response-status: 404"

See the guide Response Overrides → for more examples

Dynamic Mocking

Dynamic mocking generates data using Faker and JSON Schema Faker based on your OpenAPI schema and x-faker extensions.

Step 1: Extend Your OpenAPI with x-faker

components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
          x-faker: name.firstName
        photoUrls:
          type: array
          items:
            type: string
            x-faker: image.imageUrl

If x-faker is missing or invalid, Prism falls back to JSON Schema Faker.

Step 2: Start Inspectr in Dynamic Mode

inspectr --mock-backend=./openapi.yaml --mock-dynamic=true

Example Response (Generated):

{
  "id": 12608726,
  "name": "Addison",
  "photoUrls": ["http://lorempixel.com/640/480", "http://lorempixel.com/640/480"]
}

Comparison: Static vs. Dynamic Mocking

Mode	Behavior
Static	Returns predefined examples from OpenAPI spec
Dynamic	Generates data using Faker/JSF from schema and `x-faker` annotations

Use static mode for stable mocks based on the provided examples. Use dynamic mode to simulate variability and more dynamic data.

Summary

Mock mode in Inspectr gives you full flexibility when developing against APIs. Whether you need consistent fixtures or random data, mocking accelerates frontend and QA workflows.