What happens if the slug is already taken?

POST /api/mocks answers 409 with the error code slug_taken and creates nothing. The slug stays unavailable while the mock holding it is alive and becomes available again the moment that mock is deleted or expires. The same code is returned for names that cannot be used for other reasons, so read it simply as: choose a different slug.

Does a custom slug make the mock public?

Not any more than before, but a readable slug is easier to guess than a random one, so anyone who guesses the URL can call it. Keep secrets out of the response. The request log stays private by default: it opens only with the admin token, unless you created the mock with logs_public .

Can I change the slug later?

No. The slug is set when the mock is created, and updating the mock with PUT ignores it. To move to another address, create a new mock with the new slug, point your callers at it and delete the old one.

Stable mock URL with a custom slug

Pick the slug yourself so the mock URL survives every delete and re-create: set it once in your .env, CI and Postman, and stop chasing new addresses.

A random mock URL is perfect for a throwaway test and a nuisance for anything that has to remember it. Recreate the mock and the address changes, so the value in your .env file, your CI secrets and your shared Postman environment goes stale. A custom slug lets you choose the address once: pass slug when you create the mock, through the API, the CLI or the web form, and https://quickmock.dev/m/my-app-payments-dev keeps working across deletes and re-creates, for as long as nobody else claims the name.

Why does a random mock URL get in the way?

Every mock created without a slug gets a random 12-character one, and that is exactly right for a throwaway test. It is wrong the moment the URL is written down somewhere. Delete the mock and create it again, and you get a different slug, so every place that remembered the old address now points at nothing: the .env file on a colleague's laptop, the secret in your CI settings, the environment in a shared Postman collection, the base URL in a partner's sandbox configuration.

A custom slug turns the address into something you choose once. https://quickmock.dev/m/my-app-payments-dev can be pasted into all of those places and left alone. The mock behind it can still be deleted, replaced with a different response, or allowed to expire and be recreated; as long as you create it with the same slug, the URL your callers use never changes.

It is also simply easier to live with. A readable name in a log line, a stack trace or a failing pipeline tells you which mock is involved without a lookup.

How do you create a mock with your own slug?

Pass slug when you create the mock. The API takes it as one more JSON field:

curl -X POST https://quickmock.dev/api/mocks \
  -H 'Content-Type: application/json' \
  -d '{"slug":"my-app-payments-dev","method":"GET","response_status":200}'

The CLI has a flag for it, and the web form has a custom slug field next to the path suffix:

quickmock create -slug my-app-payments-dev -s 200 -b '{"status":"ok"}'

A slug is 4 to 48 characters: lowercase letters, digits and dashes, starting and ending with a letter or a digit. Leading and trailing spaces are trimmed and capital letters are lowercased, so My-App-Dev becomes my-app-dev. Leave the field out, or send it empty, and you get a random slug as before. A slug that breaks the format is rejected with 422 validation_failed and nothing is created.

If the name cannot be used, the response is 409 slug_taken. It is the same answer whether another live mock holds the slug or the name is unavailable for some other reason, so pick a different one and try again.

How long does the URL stay yours?

A mock with a custom slug lives like any other mock. It expires after the ttl_seconds you set, or after the server default if you set none, and it can never live longer than 30 days from the moment it was created. Until then the URL keeps answering.

To keep it going, extend it with the admin token you received at creation:

curl -X POST https://quickmock.dev/api/mocks/my-app-payments-dev/extend \
  -H "Authorization: Bearer $ADMIN_TOKEN"

That moves the expiry forward, but never past the 30-day ceiling. Once the ceiling is reached the call returns 409 ttl_cap_reached and the mock expires on schedule.

A slug is released as soon as its mock is gone. Delete the mock with DELETE /api/mocks/<slug>, or let it expire, and the very next create request can claim the same slug again, with a different method, status or body if you like. That is how you rotate a stable URL: the address stays, the mock behind it is new, and it comes with a fresh admin token.

What usually goes wrong?

Putting secrets in the response. A readable slug is easy to guess, and anyone who guesses it can call the URL. Treat the response body as public: no real keys, tokens or personal data. The request log is a different matter and stays private by default, readable only with the admin token unless you created the mock with logs_public.
Choosing a generic name. First come, first served. Names like test, demo or api are very likely taken already. Prefix the slug with your team and app, for example acme-checkout-staging.
Assuming the slug is reserved for you. It belongs to a mock only while that mock is alive. Once it expires, anyone can create a mock with the same slug, so extend the mock before the deadline and keep the admin token somewhere you can find it.
Expecting to rename it. The slug is fixed at creation, and updating the mock with PUT never changes it. For a different address, create a new mock and delete the old one.

When to use this

Random slugs change on every re-create, so any config that stored the URL goes stale. A custom slug of 4 to 48 characters gives the mock a fixed, readable address you can hard-code into environments, CI secrets and teammates' setups.

Create the mock

curl -X POST https://quickmock.dev/api/mocks \
  -H 'Content-Type: application/json' \
  -d '{
  "slug": "my-app-payments-dev",
  "method": "GET",
  "response_status": 200,
  "content_type": "application/json",
  "response_body": "{\"status\":\"ok\"}"
}'

Call it

curl https://quickmock.dev/m/<slug>

What you get

GET /m/my-app-payments-dev -> 200 {"status":"ok"}
second create with the same slug -> 409 slug_taken
(until the first mock is deleted or expires)

FAQ

What happens if the slug is already taken?: POST /api/mocks answers 409 with the error code slug_taken and creates nothing. The slug stays unavailable while the mock holding it is alive and becomes available again the moment that mock is deleted or expires. The same code is returned for names that cannot be used for other reasons, so read it simply as: choose a different slug.
Does a custom slug make the mock public?: Not any more than before, but a readable slug is easier to guess than a random one, so anyone who guesses the URL can call it. Keep secrets out of the response. The request log stays private by default: it opens only with the admin token, unless you created the mock with logs_public.
Can I change the slug later?: No. The slug is set when the mock is created, and updating the mock with PUT ignores it. To move to another address, create a new mock with the new slug, point your callers at it and delete the old one.

Build your own

Create a mock

Related guides

← All guides

Last updated: 2026-10-20