Do I need an account or API key to use the MockBolt API?

No. Creating a mock requires no auth at all. For managing a mock — update, delete, logs — your secret_token acts as the credential, with no signup or API key needed.

How do I authenticate API calls to manage my mock?

Include the secret_token you received at creation time in the URL path: /api/v1/manage/{secret_token}. That UUID is your ownership proof and is cryptographically unguessable.

Can I use the MockBolt API in CI/CD pipelines?

Yes. Create a mock at the start of your test run, run your tests against the public URL, then delete it when done. All three operations are single curl commands.

Can I simulate errors or return different status codes?

Yes. Set status_code to any valid HTTP status, and use error_rate_pct to randomly return error responses to a percentage of callers — useful for resilience testing.

Can I return different responses based on the request?

Yes, using conditional_rules. Up to 5 rules per mock; each matches a query parameter or header to an exact value and returns a different JSON payload and optional status code. First match wins.

How do I return a different response for each value of one query parameter?

Set param_switch_key to the parameter name and param_switch_map to a value-to-response object, up to 25 entries. If the param is missing, or its value is not in the map, the default json_payload is returned. Matching is exact and case-sensitive, and conditional_rules are evaluated first if both are configured.

Can the same mock cycle through multiple responses?

Yes — set round_robin_payloads to an array of up to 5 payloads. Each request gets the next one in sequence and wraps around. Useful for testing pagination, retry logic, or loading-then-loaded states.

Can I see what body my client sent in the response?

Yes — set echo_request_body to true. The response is wrapped to include both the body you sent and the mock payload, making it easy to debug what your client is actually sending.

How long does a free mock last?

7 days from creation. Mocks that keep receiving traffic, meaning 10 or more hits per 7-day window, are auto-renewed in 7-day increments up to a hard 90-day cap. Pay $2 once to make a mock permanent.

Can I use any HTTP client — Postman, Insomnia, HTTPie?

Yes. The API is plain REST and JSON, so any HTTP client works. A Postman collection is available to download.

Is CORS enabled on the API endpoints?

Yes. All MockBolt API endpoints and mock public URLs return open CORS headers, so you can call them from browser code too.

MockBolt API Reference

Create, update, and delete mock endpoints programmatically from curl, Postman, or any HTTP client — no API key required. Full REST reference with copy-paste curl examples for every endpoint, plus request-log retrieval and a downloadable Postman collection.

Endpoints

No API key is required. Creating a mock returns a secret_token — save it, as it is your credential for every subsequent call.

POST /api/v1/mocks — Create a mock. Returns public_id, secret_token, public_url, manage_url, and expires_at.
POST /api/v1/mocks/batch — Create up to 50 mocks in one call, used by the OpenAPI import flow.
GET /api/v1/manage/{secret_token} — Fetch a mock's current configuration and hit count.
PUT /api/v1/manage/{secret_token} — Update any field of an existing mock.
GET /api/v1/manage/{secret_token}/logs — Read recent request logs, including headers, body, IP, and timing.
DELETE /api/v1/manage/{secret_token} — Delete a mock immediately.

Configuration options

Field	Type	Description
json_payload	object \| array	The JSON body returned to callers. Supports dynamic variables for uuid, timestamp, randomInt, and name.
status_code	integer	HTTP status code to return, 100 to 599, default 200.
allowed_methods	string[]	HTTP methods this endpoint responds to: GET, POST, PUT, PATCH, DELETE.
headers	object	Custom response headers.
response_delay_ms	integer	Simulated latency before responding, 0 to 10000 ms.
error_rate_pct	integer	Percentage of requests that return a simulated error, 0 to 100.
allowed_ips	string[]	IP allowlist. An empty array allows all; otherwise only listed IPs, with 403 for others.
conditional_rules	object[]	Up to 5 rules returning different payloads based on a query param or header. First match wins.
round_robin_payloads	any[]	Up to 5 payloads cycled in order across successive requests.
echo_request_body	boolean	Wraps the response to include the incoming request body, useful for debugging what a client sends.
param_switch_key	string \| null	Name of a single query parameter to switch on. Empty or null disables the switch.
param_switch_map	object	Up to 25 entries mapping a param value to its response. Unmatched values fall back to json_payload.

Frequently asked questions

Do I need an account or API key to use the MockBolt API?: No. Creating a mock requires no auth at all. For managing a mock — update, delete, logs — your secret_token acts as the credential, with no signup or API key needed.
How do I authenticate API calls to manage my mock?: Include the secret_token you received at creation time in the URL path: /api/v1/manage/{secret_token}. That UUID is your ownership proof and is cryptographically unguessable.
Can I use the MockBolt API in CI/CD pipelines?: Yes. Create a mock at the start of your test run, run your tests against the public URL, then delete it when done. All three operations are single curl commands.
Can I simulate errors or return different status codes?: Yes. Set status_code to any valid HTTP status, and use error_rate_pct to randomly return error responses to a percentage of callers — useful for resilience testing.
Can I return different responses based on the request?: Yes, using conditional_rules. Up to 5 rules per mock; each matches a query parameter or header to an exact value and returns a different JSON payload and optional status code. First match wins.
How do I return a different response for each value of one query parameter?: Set param_switch_key to the parameter name and param_switch_map to a value-to-response object, up to 25 entries. If the param is missing, or its value is not in the map, the default json_payload is returned. Matching is exact and case-sensitive, and conditional_rules are evaluated first if both are configured.
Can the same mock cycle through multiple responses?: Yes — set round_robin_payloads to an array of up to 5 payloads. Each request gets the next one in sequence and wraps around. Useful for testing pagination, retry logic, or loading-then-loaded states.
Can I see what body my client sent in the response?: Yes — set echo_request_body to true. The response is wrapped to include both the body you sent and the mock payload, making it easy to debug what your client is actually sending.
How long does a free mock last?: 7 days from creation. Mocks that keep receiving traffic, meaning 10 or more hits per 7-day window, are auto-renewed in 7-day increments up to a hard 90-day cap. Pay $2 once to make a mock permanent.
Can I use any HTTP client — Postman, Insomnia, HTTPie?: Yes. The API is plain REST and JSON, so any HTTP client works. A Postman collection is available to download.
Is CORS enabled on the API endpoints?: Yes. All MockBolt API endpoints and mock public URLs return open CORS headers, so you can call them from browser code too.