Core Concepts

Workspaces

A workspace is the top-level container for a project. It holds all your schemas and mock configs, and it has its own usage quota.

Every workspace belongs to one owner and has exactly one namespace — a short, immutable slug generated when the workspace is created.

---

Namespaces

A namespace is the unique routing prefix for all mock endpoints in a workspace. It looks like sunny-fox-4a2b and never changes after creation.

All mock requests are routed through:

https://mock.mockra.io/{namespace}/{your-api-path}

Because namespaces are immutable, any URL you share or embed in a test script will stay valid permanently.

---

Schemas

A schema is an OpenAPI specification (version 3.x or Swagger 2.0) that you upload to Mockra. Uploading a schema does two things:

1. Parses every endpoint defined in the spec
2. Creates a mock config for each endpoint with an auto-generated default response

A workspace can have multiple schemas. Each schema tracks all endpoints defined in its spec.

---

Mock Configs

A mock config is the response definition for a single endpoint. It contains:

Field	Description
status_code	HTTP status code to return (e.g. 200, 404)
body	JSON or string response body
headers	Custom response headers
latency_ms	Simulated delay in milliseconds (Pro+)

When a request hits mock.mockra.io, Mockra looks up the matching mock config and returns the configured response. Changes to a mock config take effect immediately — the response cache is updated in real time.

---

State Configs

A state config turns a static mock endpoint into a stateful sequence. Instead of always returning the same response, the endpoint cycles through a list of steps in order.

This is useful for simulating multi-step workflows like OAuth authorization, inventory depletion, or paginated responses.

See Stateful Mocks for the full guide.

---

How requests are served

Mockra runs on Cloudflare Workers at the edge globally. The request path is:

1. Request arrives at mock.mockra.io/{namespace}/{path}
2. Mockra looks up the matching config in its edge cache (KV)
3. The configured response is returned — typically in single-digit milliseconds
4. If the config isn't cached, Mockra queries the database, returns the response, and repopulates the cache

This means mock endpoints behave like a real API — they're always available, globally fast, and don't require any running server on your side.

---

Pricing tiers

Your workspace's tier controls which features are available and how many requests you can make per month.

Tier	Requests/mo	Key features
Free	5,000	5 endpoints, 2 schemas
Starter ($20)	100,000	50 endpoints, stateful mocks
Pro ($75)	1,000,000	Latency simulation, API keys, variable interpolation, ephemeral namespaces, drift detection
Enterprise	Custom	SSO, SLA, custom runtime hostname

Feature gates are enforced when you save a mock config — not at request time. The mock runtime itself does not check your tier on every request.

---

Quota enforcement

Each workspace has a monthly request count. When you exceed your tier's limit, Mockra returns 429 Too Many Requests for all subsequent mock calls until the quota resets at the start of the next calendar month.

You can view your current usage and upgrade your plan from the Billing section in the dashboard.