Mock API Builder guide

1. 1

   Add an endpoint

   Click Add Endpoint, pick a method, and type a path such as /users or /users/:id.
2. 2

   Write the response

   Choose a status code and type, then write the body. Plain JSON works as is. Add placeholders like {{faker.person.fullName}} when you want a fresh value on every call.
3. 3

   Call it

   The endpoint editor shows a ready-made curl command for the selected endpoint. Copy it, or copy the Base URL from the toolbar and add your path. On a phone the toolbar hides the base URL, so use the curl command.

A GET /users/:id endpoint with this body:

{
  "id": "{{params.id}}",
  "name": "{{faker.person.fullName}}",
  "email": "{{faker.internet.email}}"
}

answers a request for user 42 like this:

$ curl https://webtoolz.dev/api/mock-api/YOUR_CONFIG/users/42

{
  "id": "42",
  "name": "Maria Lopez",
  "email": "maria.lopez@example.net"
}

There is no account and no server to set up. Your whole API (every endpoint, response, and rule) is packed into one piece of the URL. The mock server reads that piece on each request and answers from it.

The same piece shows up in three addresses, so if you have one you can get to the other two:

• /api/mock-api/CONFIG/your/path
  The live API your app calls
• /json/mock-api/CONFIG
  The builder, opened with this API loaded
• /json/mock-api/docs/CONFIG
  Interactive docs for this API

Because the URL is the API, the URL changes whenever you edit something. The builder also keeps your current work in this browser, so it is still there when you come back.

An endpoint is a method plus a path. The builder supports GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS. You can reuse a path with different methods, such as GET /users and POST /users. If two endpoints end up with the same method and path, the path field turns red, and only the higher one is ever used.

Path parameters

Start a segment with : to accept any value there. The value is available in the response as {{params.name}}.

/users
/users/:id                          ->  {{params.id}}
/projects/:projectId/tasks/:taskId  ->  {{params.projectId}}, {{params.taskId}}

How a request finds its endpoint

• The method must match exactly. A HEAD request needs its own HEAD endpoint; it does not fall back to GET.
• The path must have the same number of segments, and fixed segments are case-sensitive. /users/42/posts does not match /users/:id.
• A trailing slash makes no difference: /users/ matches /users.
• Endpoints are checked from the top of the list down, and the first match wins.

Sample request body

POST, PUT, and PATCH endpoints have a Sample Request Body field. It fills in the curl command and the request form on the docs page, so whoever tests the endpoint starts with a valid body. Generate from templates builds one from the {{body.*}} fields your responses read.

Adding, copying, and deleting

Add Endpoint always creates GET /, so change its method or path before adding another. To copy an endpoint with all its responses, use the duplicate button on its card; the copy gets a -2 suffix on its path. The trash button on a card deletes the endpoint, and once an endpoint has two or more responses, each response has its own delete button.

Each response has these settings:

• Status
  The HTTP status code. Pick from the common codes: 200, 201, 202, 204, 301, 302, 304, 307, 400, 401, 403, 404, 405, 409, 422, 429, 500, 502, 503, 504.
• Type
  JSON, Text, HTML, or XML. Sets the Content-Type header.
• Delay (ms)
  Waits before answering. See below.
• Collection
  JSON only. Lets the caller page, filter, and sort an array. See Paging, filtering, sorting.
• Response Body
  What the endpoint returns. Can include placeholders.
• Response Headers
  Extra headers to send back, such as X-Api-Version. Sent exactly as written; placeholders are not filled in here.

Leave the body empty for responses like 204 No Content. HEAD requests get the status and headers with no body.

Delay

Set a delay to make the endpoint feel like a slow network. It is the easiest way to check loading spinners, timeouts, and retry logic. The maximum is 10,000 ms.

Headers, CORS, and caching

Every response allows calls from any origin, so you can use the mock from localhost or any site without a proxy. Preflight OPTIONS requests are answered for you.

A GET or HEAD response that is the same on every call (no random values, nothing read from headers or the body, no delay, no sequence) and has a status like 200, 204, or 404 is cached. That never shows you stale data, because any edit gives the API a new URL.

HTML responses are served with a strict security policy, so a page you return displays as static markup. Scripts, images, and outside stylesheets in it do not load; inline styles do.

A placeholder is text in double curly braces. When a request comes in, each placeholder is replaced with a value. Use them anywhere in the body.

Values from the request

• {{params.id}}
  Gives you: A path parameter
  Example: /users/42 -> 42
• {{query.page}}
  Gives you: A query string value
  Example: ?page=2 -> 2
• {{headers.authorization}}
  Gives you: A request header (name in any case)
  Example: Bearer abc123
• {{body.user.email}}
  Gives you: A field from a JSON request body. Use dots for nested fields.
  Example: jane@example.com

If the query value, header, or body field is missing, the placeholder becomes an empty string. The same happens to every {{body.*}} placeholder when the request body is not valid JSON. Objects and arrays from the body are inserted as JSON. When a query parameter appears more than once, as in ?tag=a&tag=b, only the last value is used, here and in rules and collection filters.

Generated values

• {{uuid}}
  Gives you: A new random UUID each time it appears
  Example: 3b1f8c2e-...
• {{now}}
  Gives you: The current time as an ISO 8601 string
  Example: 2026-11-02T09:30:00.000Z
• {{timestamp}}
  Gives you: The current time in Unix milliseconds
  Example: 1793611800000
• {{int 1 100}}
  Gives you: A whole number in the range, inclusive
  Example: 57
• {{oneOf 'on' 'off'}}
  Gives you: One of the options, picked at random. Quote each option; quotes let an option contain spaces.
  Example: off
• {{faker.person.fullName}}
  Gives you: Realistic fake data. See Fake data below.
  Example: Maria Lopez

{{now}} and {{timestamp}} have the same value everywhere in one response, so a createdAt and updatedAt set from them will match.

Quotes and types

A placeholder is replaced as plain text, so you decide the JSON type. Put it inside quotes for a string, or leave the quotes off for a number or boolean:

{
  "id": "{{uuid}}",
  "age": {{int 18 75}},
  "active": {{faker.datatype.boolean}},
  "page": {{query.page}}
}

For HTML and XML responses, inserted values are escaped, so a < in a query value shows up as text instead of markup. A placeholder the builder does not recognize, such as a typo, is left in the response exactly as you wrote it, which makes mistakes easy to spot.

Placeholders that start with faker. call Faker.js and return a new value on every request. These are the ones people use most:

• {{faker.person.fullName}}
  John Smith
• {{faker.internet.email}}
  john@example.com
• {{faker.number.int(1,1000)}}
  427
• {{faker.lorem.sentence}}
  Lorem ipsum dolor sit amet.
• {{faker.date.past}}
  2024-03-15T...
• {{faker.commerce.price}}
  29.99
• {{faker.location.city}}
  San Francisco
• {{faker.image.avatar}}
  https://avatars.githubusercontent.com/...

Arguments

• A range for numbers: {{faker.number.int(1,100)}} or {{faker.number.float(0,10)}}.
• A single count or length: {{faker.lorem.words(3)}} or {{faker.string.alphanumeric(8)}}.

Two arguments only work on number.int and number.float. On any other method both are ignored and it uses its default.

Which methods work

Most methods from these Faker modules work, not only the ones listed here: person, internet, number, lorem, image, location, commerce, company, date, phone, finance, datatype, string, animal, color, food, music, science. A method that returns an object is inserted as JSON, so leave it unquoted. Methods that need an options object, such as faker.date.between, are not supported and stay as text.

The same list sits under Faker Reference at the bottom of the endpoint editor. Its Helpers group has the list helpers from the next section. Click any entry to copy it.

To return an array, wrap one item in {{#repeat N}} and {{/repeat}}, and put the block between the square brackets. Each copy gets its own fake data, and the commas between items are added for you.

[
  {{#repeat 5}}
  {
    "id": {{index1}},
    "name": "{{faker.person.fullName}}",
    "role": "{{oneOf 'admin' 'editor' 'viewer'}}"
  }
  {{/repeat}}
]

That returns five users with ids 1 to 5.

• {{#repeat 5}}
  Exactly 5 items
• {{#repeat 5 20}}
  A random number of items between 5 and 20
• {{#repeat query.count}}
  As many items as the caller asks for with ?count=
• {{index}}
  The position inside the block, starting at 0
• {{index1}}
  The position, starting at 1. Handy for ids.

Blocks can be nested, so each item can have its own list. Inside a nested block, {{index}} refers to the innermost one. One response holds at most 1,000 repeated items in total, counting nested blocks.

Click Add Response to give an endpoint a second response. Once it has two or more, you choose how the endpoint picks between them: Sequence (the default) or Conditional.

Sequence: a different response on each call

The endpoint goes through the responses in order (Call #1, Call #2, and so on) and starts again from the first after the last one. Use it to test retries, polling, or a token that expires.

Call #1  ->  500  {"error": "Server busy"}
Call #2  ->  200  {"status": "ok"}
Call #3  ->  500  (back to the first)

Conditional: pick a response by what the request contains

When you switch to Conditional, every response except the last gets rule fields to fill in, and the last one becomes the fallback. Each response with rules can check:

• Query param matches
  Checks: A query string value, such as status
  Example pattern: ^active$
• Header matches
  Checks: A request header. The name can be in any case.
  Example pattern: ^Bearer .+
• Path param matches
  Checks: A :param from the path. Only offered when the path has one.
  Example pattern: ^999$
• Body
  Checks: The raw request body text. Only offered for POST, PUT, and PATCH.
  Example pattern: "role":\s*"admin"

• Responses with rules are checked from the top. The first one whose rules all match is returned.
• If none match, the first response without rules is returned. A response whose rule fields are all left empty counts as having no rules.
• Every rule is a regular expression and matches anywhere in the value. admin also matches superadmin, so use ^admin$ for an exact match.
• A rule on a query param, header, or path param that the request does not have never matches.
• An invalid pattern, a pattern with a repeated group such as (cat|dog)+, or a value over 2,000 characters is compared as plain text instead: the rule only matches if the value contains the pattern exactly as typed. Write ^(cat|dog)$ rather than repeating a group.

Response 1   200  {"token": "{{uuid}}"}
             when body matches  "password":\s*"s3cret"

Response 2   401  {"error": "Invalid credentials"}
             fallback

Tick Collection: paginate, filter, sort on a JSON response whose body is an array. The endpoint then understands the same query parameters as json-server. Pair it with a {{#repeat}} block to get a large list to work with.

• ?_page=2&_limit=10
  Page 2, 10 items per page. Without _limit a page has 10 items. page and limit work too.
• ?_start=20&_end=30
  A slice by position, counting from 0. _limit on its own returns the first N items.
• ?_sort=name&_order=desc
  Sort by a field. The order is asc unless you pass desc.
• ?role=admin
  Only items whose field equals the value exactly
• ?age_gte=18&age_lte=65
  Greater than or equal, less than or equal
• ?role_ne=viewer
  Not equal
• ?name_like=ann
  Contains the text, ignoring case
• ?q=jane
  Search every field of every item
• ?author.name=Jane
  Filter or sort on a nested field with dots

Filters are applied first, then search, then sorting, then paging. Every collection response has an X-Total-Count header with the number of matching items before paging. Paged responses also get a Link header with the first, previous, next, and last page URLs. _limit is capped at 1,000.

The toolbar

• Untitled API
  Click to name your API (up to 40 characters). The name shows on the docs page.
• Base URL
  The live address of your API. Add an endpoint path to it to make a request. Hidden on phone screens.
• Links
  Copies the endpoint, builder, docs, or OpenAPI spec address.
• Size bar
  How much of the 50 KB size budget your API uses. It turns amber, then red, as it fills.
• Share
  Copies a link to the builder with your API loaded. See below.
• Docs
  Opens the interactive docs in a new tab.
• Export
  Downloads the API in another format. See Import and export.
• Clear
  Removes every endpoint from the builder at once.

On screens narrower than a tablet, the endpoint list and the editor are two tabs, Endpoints and Editor. Picking a different endpoint switches to the editor; to reopen the one already selected, tap Editor. On wider screens they sit side by side, and you can drag the divider between them.

Share and short links

Share copies a builder link to your clipboard. A small API, whose packed config is 1,200 characters or fewer, gets the full link. A bigger API is saved on our server instead, and you get a short link that starts with ~, such as /json/mock-api/~Xk3p9QzL2mN8vR4tW7yB1c. The base URL and docs link switch to the short form too.

• A short link stays valid as long as people keep using it. One that goes unused for a long time can expire.
• A full link holds the whole API, so it never expires.
• If saving fails, Share copies the full link instead, so you always get a working link.
• Anyone with the link can open the API in the builder and change it. Their changes make a new URL and never touch yours.

Interactive docs

Docs opens an API reference built from your endpoints: methods, paths, parameters, and example responses. Each endpoint has a Test Request button that sends a real request to the mock and shows the answer, with the sample request body filled in. Send the docs link to whoever builds against the API. The docs page has its own Share button that copies the docs link, and Edit in Builder opens the same API for editing.

The OpenAPI spec for the docs lives at /api/mock-api-docs/CONFIG/openapi.json, so tools that read OpenAPI can load it directly.

If someone gave you a mock URL, even just the endpoint an app calls, you can open the whole API from it. Pick whichever of these is easiest:

• Paste it. On an empty builder, paste the link into Have a mock API URL? and press Enter or the arrow button. Endpoint, docs, and builder links all work.
• Open it in a browser. Visiting the base URL shows a short overview page with Open in Builder, View Docs, and OpenAPI spec links, unless the API has its own GET / endpoint.
• Change the address. Replace /api/mock-api/ with /json/mock-api/ and remove the endpoint path after the config.

Endpoint:  https://webtoolz.dev/api/mock-api/~Xk3p9QzL2mN8vR4tW7yB1c/users
Builder:   https://webtoolz.dev/json/mock-api/~Xk3p9QzL2mN8vR4tW7yB1c
Docs:      https://webtoolz.dev/json/mock-api/docs/~Xk3p9QzL2mN8vR4tW7yB1c

Responses carry the way back too. A request that matches no endpoint gets a 404 whose JSON body lists the builder, docs, and spec links. Responses from a short link or a small API also carry X-Mock-Builder and X-Mock-Docs headers.

Import

Import OpenAPI, below the endpoint list, accepts an OpenAPI 3.x or Swagger 2.0 document in JSON or YAML, or a config you exported from here. Paste it or choose a file. The builder creates an endpoint for each operation, with Faker placeholders matched to field names so the responses look real. Then choose:

• On an empty builder, Import loads them.
• If you already have endpoints, Replace all starts over with the imported ones, and Add to current keeps yours and skips any with a method and path you already have.

A spec with more than 100 operations is cut at 100, and anything the importer had to skip, such as an external reference, is listed before you confirm.

Export

• Config (JSON)
  A backup you can import here later
• OpenAPI spec
  Swagger UI, code generators, and other OpenAPI tools (OpenAPI 3.1)
• Postman collection
  A ready-to-send collection pointed at your mock, with path variables and sample request bodies filled in
• Mockoon environment
  Running the API locally in Mockoon. Sequences, conditional rules, delays, and headers carry over. Placeholders are kept as written, since Mockoon uses its own syntax.
• json-server db.json
  Seed data for json-server. Only GET endpoints that return an array are included, with placeholders filled in. Sequence and conditional responses are left out.

When an export has to leave something out, a note tells you what.

From Template, below the endpoint list, loads a complete example API. If you already have endpoints, the builder asks before replacing them.

• Endpoints per API
  100
• Responses per endpoint
  50
• Response body you write
  100,000 characters
• Path length
  500 characters
• Whole API, compressed
  Aim to stay under 50 KB, the budget the toolbar size bar shows. Past about 70,000 characters the base URL answers 413 Config too large.
• API name
  40 characters
• Delay
  10,000 ms
• Repeated items in one response
  1,000
• Rendered response
  256,000 characters. Longer output is cut off.
• Collection _limit
  1,000

The builder does not stop you at the first four. An API over any of them is rejected when it is called: the base URL answers 400 Invalid config.