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.