Mock server guide

About this feature

The mock server feature is only available to Pro and Enterprise customers.

A mock server imitates a real API server by providing mock API responses to requests. This feature allows you to try out your API as you design and develop it, and provide instant feedback on how it may be used.

To use the mock server feature, you must first add an API to the registry, then enable the mock server in the settings for that API.

Step 1: Set up your API

Follow the instructions in the API registry quickstart to connect your repository to the API registry and add an API definition.

Your API will be added to the registry. You will be redirected to the API Overview page, where the first build will automatically start.

By default, the mock server feature is disabled, and the Overview page doesn't display the mock server link.

The next step is to enable the feature.

Step 2: Enable mock server feature

Only users with the Admin project-level role for an API can enable the mock server feature.

The mock server feature is disabled by default.

To enable the mock server:

  1. On the API registry page, select the API for which you want to enable mock server feature. The API Overview page displays.
  2. From the top, navigate to Settings > Mock servers .
  3. Check the Enable mock servers for all branches box.

Anyone who has access to your mock server URLs can use the mock server to discover endpoints. If you have a private API, and do not wish to expose it to the public, we recommend disabling the mock server feature.

To disable the mock server, uncheck the Enable mock servers for all branches box.

Back on the Overview page, you will see the mock server button for each published branch and all active preview branches of the current API.

Mock server feature

Select the button to copy the mock server URL.

Step 3: Test the mock server

To test your mock server, copy the mock server link and use it as the server URL when sending a request in any API testing tool.

The mock server URL has the following format: <mock-server-id> The <mock-server-id> part is automatically generated by Redocly. The URL is static and does not change when you modify the code in the branch or rebuild your API definition in the registry.

In the following example, we are sending a test request with cURL to the mock server with the URL The API definition tells us which path, operation, and parameters to use in the request.

Example API definitionExample cURL request
openapi: 3.1.0
        - User
      summary: Get user info by username
      description: |
        Some description of the operation.
        You can use `Markdown` here.
      operationId: getUserByName
        - name: username
          in: path
          description: "Name of a registered user. Must be an exact match."
          required: true
            type: string
        - name: all
          in: query
          description: "Specifies whether to return all available information about the user. If omitted, the API returns only the basic set of information (email, registration date)."
            type: boolean
            default: false
        - bearerAuth: []
      type: http
      scheme: bearer
curl --request GET \
  --url '' \
  -H "Authorization: Bearer anything-you-want-here"

Authentication for the mock server

Security for the mock server is based on the OpenAPI security definitions (such as apikey, bearer, or basicauth) of your API in the registry. You must pass security parameters to the request in the correct format with any value. The mock server does not validate the actual credentials provided (only their format, such as the correct header name).

Custom headers for the mock server

Redocly supports the following custom headers that help you test the response content of your APIs:

  • x-redocly-response-status - forces the mock server to reply with the specified HTTP status code, ignoring any validation or authentication if provided in the request. A response with the specified HTTP status code must be defined in the OpenAPI document for the particular operation you're testing. If such a response is not found, the mock server responds with its own default response.
  • x-redocly-response-body-example - forces the mock server to reply with an example matching the specified example ID. If an example with the requested ID is not found in the OpenAPI document, the mock server responds with its own 500 error.

The following examples show how to force specific responses from the mock server by adding these headers to your request. We're using cURL to send requests to the mock server with the URL

Force a status codeForce an example
curl --request GET \
  --url '' \
  -H "Authorization: Bearer anything-you-want-here" \
  -H "x-redocly-response-status: 429"
curl --request GET \
  --url '' \
  -H "Authorization: Bearer anything-you-want-here" \
  -H "x-redocly-response-body-example: UserObject"

To further control the mock server behavior, use the features.mockServer section in your Redocly configuration file. Note that you must add this configuration file to your API project in the registry for changes to apply.