Mock Endpoints¶
4 endpoints for creating, serving, inspecting, and deleting HTTP mocks.
| Method | Endpoint | Purpose |
|---|---|---|
POST |
/v1/mocks |
Create a mock endpoint |
GET |
/v1/mocks/{mock_id} |
Get mock metadata and hit count |
DELETE |
/v1/mocks/{mock_id} |
Delete a mock endpoint |
ANY |
/v1/mock/{mock_id} |
Public endpoint that serves the configured response |
REST API Examples¶
Create a mock endpoint¶
A mock is not path- or method-scoped: you configure what to return, and the serving URL answers every method.
curl -X POST "https://webhook.toolkitapi.io/v1/mocks" \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "users-list",
"status_code": 200,
"content_type": "application/json",
"body": "{\"users\": []}",
"ttl_seconds": 86400
}'
{
"status": "ok",
"mock": {
"mock_id": "mk_9f2c1a7b",
"name": "users-list",
"status_code": 200,
"content_type": "application/json",
"delay_ms": 0,
"has_custom_headers": false,
"has_body": true,
"created_at": "2026-11-04T05:00:00+00:00",
"expires_at": "2026-11-05T05:00:00+00:00",
"hit_count": 0,
"endpoint_url": "/v1/mock/mk_9f2c1a7b"
}
}
const resp = await fetch("https://webhook.toolkitapi.io/v1/mocks", {
method: "POST",
headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
body: JSON.stringify({
name: "users-list",
status_code: 200,
content_type: "application/json",
body: JSON.stringify({ users: [] }),
ttl_seconds: 86400,
}),
});
const data = await resp.json();
const mockUrl = `https://webhook.toolkitapi.io${data.mock.endpoint_url}`;
console.log(`Mock URL: ${mockUrl}`);
Python SDK Examples¶
Create a basic mock¶
from toolkitapi import Webhook
with Webhook(api_key="tk_...") as wh:
created = wh.create_mock(
name="payments-accepted",
status_code=202,
content_type="application/json",
body='{"accepted": true}',
ttl_seconds=3600,
)
mock_id = created["mock"]["mock_id"]
endpoint = created["mock"]["endpoint_url"]
print(mock_id)
print(f"https://webhook.toolkitapi.io{endpoint}")
Create a mock with custom headers and delay¶
from toolkitapi import Webhook
with Webhook(api_key="tk_...") as wh:
created = wh.create_mock(
status_code=429,
headers={
"Retry-After": "120",
"X-RateLimit-Policy": "test",
},
body='{"error":"rate_limited"}',
content_type="application/json",
delay_ms=800,
)
print(created["mock"]["endpoint_url"])
Hit a mock endpoint¶
The serving URL is public and accepts any HTTP method.
curl -i -X POST "https://webhook.toolkitapi.io/v1/mock/{mock_id}" \
-H "Content-Type: application/json" \
-d '{"hello":"world"}'
Inspect mock metadata and usage¶
from toolkitapi import Webhook
with Webhook(api_key="tk_...") as wh:
info = wh.get_mock("<mock_id>")
mock = info["mock"]
print(mock["status_code"], mock["content_type"])
print(mock["hit_count"])
print(mock["expires_at"])
Delete a mock¶
from toolkitapi import Webhook
with Webhook(api_key="tk_...") as wh:
result = wh.delete_mock("<mock_id>")
print(result["message"])
Request Parameters¶
POST /v1/mocks¶
| Parameter | Type | Description |
|---|---|---|
name |
string | Optional friendly name, max 128 chars |
status_code |
integer | HTTP status to return, 100 to 599 |
headers |
object | Additional response headers |
body |
string | Response body (a string, not an object — serialize JSON yourself) |
content_type |
string | Response content type, default application/json |
delay_ms |
integer | Artificial delay in ms, 0 to 30000 |
ttl_seconds |
integer | Lifetime in seconds, 60 to 172800. Omit for the service default |
Response Fields¶
Mock metadata¶
| Field | Type | Description |
|---|---|---|
mock.mock_id |
string | Mock identifier |
mock.name |
string | Optional mock name |
mock.status_code |
integer | Configured response status |
mock.content_type |
string | Configured content type |
mock.delay_ms |
integer | Configured delay |
mock.has_custom_headers |
boolean | Whether custom headers are set |
mock.has_body |
boolean | Whether a body is set |
mock.created_at |
string | ISO timestamp |
mock.expires_at |
string | ISO timestamp |
mock.hit_count |
integer | Number of times served |
mock.endpoint_url |
string | Relative serving path (/v1/mock/{mock_id}) |
Behavior Notes¶
| Area | Detail |
|---|---|
| Auth | Create/read/delete endpoints require API key auth |
| Storage | Mocks live in the service's in-memory store. Treat them as disposable; a restart drops them before ttl_seconds elapses |
| Public serving | /v1/mock/{mock_id} does not require auth |
| Methods | Serving endpoint accepts GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS |
| Response marker | Serving response adds X-Mock-Id header |
Tip
Use separate mocks for happy-path and failure scenarios, then switch target URLs in your integration tests. This keeps test behavior deterministic and avoids brittle conditional logic inside one mock definition.