Docs
How to give an endpoint a dynamic path, issue an API key, drive the platform from your coding agent, read your request logs, and what the free plan allows.
Your mocks answer on https://api.ghostmock.com. Every example below already points at it.
{server}/m/{apiId}/{apiPrefix?}/{endpointPath}
The API id is generated for you, and the prefix segment only appears when the API has one.
Path parameters
Write a segment as :id and it matches any value in that position — the way a real router behaves.
- users/:id
- Prefix a segment with a colon to make it dynamic: it then matches any value in that position. Every other segment still has to match exactly.
- :id :userId :_internal
- Valid names: a colon, then a letter or underscore, then letters, digits or underscores.
- :user-id :user.id :1st
- Rejected. Hyphens, dots and a leading digit are fine in a static segment but not in a parameter name.
- orders/:orderId/items/:itemId
- A parameter covers exactly one segment, and you can use as many as you like in the same path. There are no wildcards, catch-alls or optional segments.
- Slashes are stripped
- Type /users and it is stored — and redisplayed — as users. Leading, trailing and doubled slashes are removed when you save.
- Avoid overlapping routes
- Defining both users/me and users/:id is ambiguous — either one may answer. Give the specific route a distinct shape, such as users/me/profile.
# Saved once, as users/:id
curl https://api.ghostmock.com/m/9f2c7a/api/v1/users/42
curl https://api.ghostmock.com/m/9f2c7a/api/v1/users/1000
# Both reach that endpoint and return the same saved body.The value is not passed through
API keys
Credentials for programmatic access. Your mock URLs are public and never need one — only the MCP server does.
What a key looks like
sk_live_<12 hex chars>_<secret>
- Created in API keys
- Give the key a name you will recognise later — the tool or machine that will use it — and pick an expiration.
- Expiry is mandatory
- Every key expires. The options are 30, 90 or 365 days, defaulting to 90, and 365 days is the longest lifetime allowed.
- Shown exactly once
- Only a hash of the secret is stored, so the full key is displayed once at creation and can never be recovered. Copy it then; afterwards the list shows only its first characters.
- Revoking is immediate and final
- A revoked key stops working straight away and cannot be restored. Create a replacement instead.
- Active, Expired, Revoked
- The status column tells you which keys still work. Last used updates shortly after a key is used.
- Only for the MCP server
- Keys authenticate requests to /mcp and nothing else. Calling your mock endpoints never requires one — those URLs are public by design.
Treat a key like a password
Never put real data in a mock
Connect your coding agent
The platform ships an MCP server, so an agent can create, list and search your mocks without leaving the editor.
The endpoint
POST https://api.ghostmock.com/mcp
- The endpoint speaks MCP over Streamable HTTP and is stateless — there is no session to keep alive.
- It only answers MCP protocol messages, so opening the URL in a browser will not show you anything useful.
- Authentication is the Authorization: Bearer header. There is no alternative header and no query-string form.
Claude Code
Register it from the CLI, which stores the server for you.
claude mcp add --transport http ghostmock \
https://api.ghostmock.com/mcp \
--header "Authorization: Bearer sk_live_a1b2c3d4e5f6_your-secret-here"opencode
Add the server to your opencode.json, then restart opencode.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"ghostmock": {
"type": "remote",
"url": "https://api.ghostmock.com/mcp",
"enabled": true,
"headers": {
"Authorization": "Bearer sk_live_a1b2c3d4e5f6_your-secret-here"
}
}
}
}Codex
Create .codex/config.toml in your project root, or add this block to the existing file. Replace the example key with your API key, keeping the Bearer prefix and the space after it.
[mcp_servers.ghostmock]
url = "https://api.ghostmock.com/mcp"
http_headers = { Authorization = "Bearer sk_live_a1b2c3d4e5f6_your-secret-here" }Open the project as trusted in Codex, then restart Codex to load the configuration. Use /mcp to check the server status and ask Codex to call hello on ghostmock to verify the connection. This configuration stores the key directly in the file; keep it out of Git.
If you previously registered this server globally with an environment variable, remove bearer_token_env_var from its [mcp_servers.ghostmock] block in ~/.codex/config.toml so Codex no longer tries to read that variable.
.mcp.json
Use this JSON example with clients that support the mcpServers configuration format. The file location and supported fields depend on your client: Claude Code reads .mcp.json in the project root, while Cursor uses .cursor/mcp.json.
{
"mcpServers": {
"ghostmock": {
"type": "http",
"url": "https://api.ghostmock.com/mcp",
"headers": {
"Authorization": "Bearer sk_live_a1b2c3d4e5f6_your-secret-here"
}
}
}
}Replace the example key with your API key, keeping the Bearer prefix and the space after it. This example stores the key directly in the file; keep it out of Git. Restart your client after saving.
The tools your agent gets
- hello
- Health check. Call it first — a successful reply confirms the URL and the key are both right.
- listApis
- Lists every mock API on your account.
- searchApis
- Finds APIs by partial name, so an agent can turn a name you spoke into the id the other tools need.
- createApi
- Creates a mock API, optionally with a prefix and description.
- listEndpoints
- Lists the endpoints of one API.
- searchEndpoints
- Finds endpoints by partial name across all of your APIs, returning the parent API for each match.
- createEndpoint
- Adds an endpoint to an API, with its method, path, status code and response body.
- getEndpointCurl
- Returns a ready-to-run curl command for an endpoint, with the full public URL already filled in.
See Tutorials for four worked examples that put createApi and createEndpoint to use.
Dynamic endpoints come back literal
If it will not connect
- 401 {"error":"Missing API key"}
- No Authorization header reached the server.
- 401 {"error":"Invalid API key"}
- The key is unknown, malformed, revoked or past its expiry. The message is deliberately the same for all four.
Request logs
Every call your mocks receive, including the ones that matched nothing.
What each row tells you
- Time
- How long ago the request arrived. Hover it for the exact UTC timestamp.
- Method and Path
- The verb and the path as the caller actually sent it — concrete values, not the :id template.
- Endpoint
- The id of the endpoint that answered, shortened. Empty when nothing matched.
- Status and Outcome
- The status code served, and why: OK, Not found (404) or Method not allowed (405).
- Client
- The caller's IP and, where available, their country and city. The eye icon opens the full geolocation payload.
Outcomes
- OK · 2xx
- Not found · 404
- Method not allowed · 405
- The last 100 per API
- The logs show the most recent 100 requests per mock API, newest first. There is no date-based retention — an entry stays visible until newer traffic pushes it out.
- Repeated misses collapse
- A 404 or 405 for a path already in the list refreshes that row's timestamp instead of adding another, so one noisy consumer cannot flood the view. There is no per-path hit counter.
- No live updates
- The page is rendered when you open it. Reload it to see requests that arrived since.
- What it covers
- Requests that reached one of your mock endpoints. Anything the platform turns away before that point is not included, and neither is MCP or dashboard traffic.
- You are recording other people's data
- The IP and approximate location belong to whoever called your mock. If you wire one into a page real users load, you become responsible for that personal data — and deleting the API is the only way to purge it.
- Deleting an API clears its logs
- Removing a mock API discards its entries, and that cannot be undone.
404s are the useful ones
The free plan, in full
One plan, no card, no upgrade prompt. These are the limits the server enforces.
- 75
- requests per day
- 2,250
- requests per 30-day cycle
- 10
- APIs
- 100
- endpoints per API
- 256 KiB
- per response body
- Charged to the owner
- Requests count against whoever owns the mock API, not against whoever calls it. Treat a mock URL as something you are paying for: it travels in shared curl commands and screenshots, so if one leaks somewhere public, delete the API and recreate it.
- Only successes count
- A response that actually came from one of your endpoints is what draws down the quota.
- UTC daily reset, personal 30-day cycle
- The daily counter resets at midnight UTC. Your cycle allowance resets every 30 days from registration or the payment that activated your plan.
- Short-term burst limit
- A separate burst limit protects the platform, independent of your plan quota. It sits well above anything a normal client does; trip it and you get a 429, so back off briefly and retry.
Every mock response reports your usage
- X-RateLimit-Limit-Day
- Your daily allowance.
- X-RateLimit-Remaining-Day
- What is left of it right now.
- X-RateLimit-Limit-Cycle
- Your allowance for the current 30-day cycle.
- X-RateLimit-Remaining-Cycle
- What is left of it right now.
- Retry-After
- Added only to a 429, as the number of seconds until the exhausted window resets.
When a window is exhausted
HTTP/1.1 429 Too Many Requests
retry-after: 41328
{
"error": "Rate limit exceeded",
"window": "day"
}The editor cleans some values silently
What a mock cannot do