HTTPSTATUS Open workspace

01 / Build before the backend

Create an API your team can use before the backend is ready

Describe the endpoints and behavior you need, or import an existing API artifact. HTTPStatus creates realistic mock responses you can inspect, change, and share.

Build a mockRead the mocking guide

AI mock creator

Describe the mock you need. Let AI draft the endpoint.

Turn a plain-language API idea into a starter mock with route, method, status, headers, and response body ready to review.

Open full mock workspace ↗

No signup is needed to draft. Saving and managing mocks happens in the app workspace.

Verified implementation reference

A mock is a matcher, a response, and a live endpoint—not a screenshot of a promise.

This reference describes the request paths and matching behavior implemented by HTTPStatus. Last verified against the repository on 19 July 2026.

Runtime hosthttps://mock.httpstatus.com
Request typesREST and GraphQL
HTTP methodsGET · POST · PUT · PATCH · DELETE · HEAD · OPTIONS
Path matchingEXACT · CONTAINS · WILDCARD · REGEX
VisibilityPublic or workspace-private
Response controlsStatus · headers · body · delay · priority

Smallest runnable example

Create a public endpoint, call it, then inspect the exact response.

The public creation API returns the endpoint URL and a share token. Public mocks created through this route expire after 14 days; saved workspace mocks follow workspace lifecycle settings.

1

Create the mock

curl -X POST https://httpstatus.com/api/public/mocks \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order lookup",
    "method": "GET",
    "urlPattern": "/api/orders/ord_1042",
    "matchType": "EXACT",
    "statusCode": 200,
    "responseHeaders": "{\"Content-Type\":\"application/json\"}",
    "responseBody": "{\"id\":\"ord_1042\",\"status\":\"paid\"}",
    "delayMs": 0,
    "priority": 0
  }'
2

Use the returned endpoint

HTTP/1.1 201 Created
{
  "endpointUrl": "https://mock.httpstatus.com/order-lookup/<publicKey>/api/orders/ord_1042",
  "shareUrl": "/api/public/mocks/<publicKey>",
  "shareToken": "<shareToken>",
  "mock": { "statusCode": 200, "matchType": "EXACT", "isPublic": true }
}
3

Call it like the real dependency

curl "https://mock.httpstatus.com/order-lookup/<publicKey>/api/orders/ord_1042"

HTTP/1.1 200 OK
Content-Type: application/json

{"id":"ord_1042","status":"paid"}

The generated hostname is separate from the management API. Your client calls mock.httpstatus.com; the workspace or public API is where definitions are created and managed.

Request matching

Choose the narrowest matcher that represents the dependency.

The HTTP method must match unless the definition uses *. Path matching is evaluated using the selected mode; invalid regular expressions do not match.

EXACT/api/orders/ord_1042

Matches only the complete path. Best for deterministic examples and contract fixtures.

CONTAINS/api/orders

Matches when the request path contains the configured text.

WILDCARD/api/orders/*

Converts * and ? into path-pattern matching.

REGEX^/api/orders/[a-z0-9_]+$

Uses a compiled regular expression against the complete request path.

When more than one definition can match

Active mocks are evaluated in priority order. Use higher priority for a specific failure or scenario and a lower-priority rule as the general fallback.

Definition schema

Fields that change runtime behavior.

FieldType or valuesRuntime effect
namestringHuman label and part of the readable endpoint slug.
requestTypeREST or GraphQLSelects REST path matching or GraphQL query and operation matching.
methodHTTP method or *Rejects definitions whose method does not match the incoming request.
urlPatternpath stringCompared with the incoming path using matchType.
statusCode100–599Becomes the HTTP response status.
responseHeadersJSON object encoded as a stringHeaders added to the mock response.
responseBodystringReturned as the response payload.
delayMsnon-negative integerDelays the response to reproduce slow dependencies; quick public mocks cap delay at 30 seconds.
priorityintegerControls evaluation order when definitions overlap.
activebooleanInactive definitions are excluded from matching.
isPublicbooleanControls whether the endpoint is public or protected by workspace API-key access.

Access and lifecycle

Mock authentication is independent from management authentication.

Public endpoint

No runtime API key

A public mock can be called by anyone with its endpoint URL. Do not include secrets, personal data, production tokens, or confidential payloads in its definition.

curl "https://mock.httpstatus.com/<slug>/<publicKey>/path"
Private endpoint

Workspace-aware API key

A protected mock accepts an API key only when the key belongs to the same workspace as the mock.

curl -H "X-API-Key: <workspace_api_key>" \
  "https://mock.httpstatus.com/<slug>/<publicKey>/path"
Accepted private-mock credentials

The runtime checks the apiKey query parameter, X-API-Key, Authorization: ApiKey <key>, or a supported sk_live_ bearer credential. Prefer the header forms because URLs are commonly logged.

Troubleshooting

Concrete failures and what they mean.

ErrorMeaningResolution
400 · Invalid HTTP status code. Must be between 100 and 599.The quick-response generator received a missing or unsupported status.Send an integer from 100 through 599.
400 · Headers JSON is too large.Serialized headers exceeded the quick generator’s 50,000-character limit.Remove unnecessary headers and keep payload data in the body.
401 · API key requiredA private endpoint was called without a supported credential.Send the workspace API key in X-API-Key.
401 · Invalid or inactive API key.The supplied key cannot be resolved or has been disabled.Rotate or reactivate the key in its workspace.
401 · API key does not belong to the same workspaceThe credential is valid but its workspace does not own the mock.Use a key issued by the mock’s workspace.
404 · Public mock not foundThe key is unknown, inactive, private, expired, or its path does not match.Check the complete returned endpoint URL, active state, visibility, expiry, and matcher.
Mock is private. Set isPublic=true to generate a public endpoint URL.A public short link was requested for a private definition.Publish deliberately or keep it private and use workspace API-key access.

Production-use checklist

  • Model success, validation, authorization, rate-limit, and upstream-failure responses.
  • Use exact matching by default; widen it only when the client behavior requires it.
  • Keep public fixtures synthetic and free of credentials or customer data.
  • Give exceptional scenarios higher priority than a general fallback.
  • Record the mock definition with the test or contract that depends on it.
  • Replace mocks with controlled integration tests before treating an upstream dependency as proven.

Automation and MCP

Create the same definition through a tool call.

The HTTPStatus MCP server exposes create_mock, update_mock, delete_mock, and list_mocks. OAuth or an MCP personal token authenticates the tool; a private mock’s runtime API key remains separate.

{
  "name": "create_mock",
  "arguments": {
    "name": "Rate limit response",
    "urlPattern": "/api/search",
    "method": "GET",
    "statusCode": 429,
    "responseHeaders": { "Retry-After": "30", "Content-Type": "application/json" },
    "responseBody": { "error": "rate_limited", "retryAfterSeconds": 30 },
    "isPublic": false,
    "priority": 100
  }
}
Read the MCP protocol guide

Continue the path

Mocking guideDesign mocks that reveal integration risk.API testingTurn mock behavior into repeatable checks.Contract testingCompare the mock against the documented API.WorkbenchImport cURL, OpenAPI, Postman, or JSON to bootstrap mocks.

Next move

Start with one concrete API problem.

Keep the first step small. Move into a workspace when the result deserves to be saved, repeated, or shared.

Build a mockTalk to a human