Skip to content

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.
terminal
# 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

A parameter decides whether a request matches; it never reaches the response. There is no templating, so /users/1 and /users/999 return exactly the same body you saved. If you need different payloads, create a separate endpoint for each concrete path. The value you actually sent is visible in the request logs.

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

A key is account-wide: anyone holding it can read and create mock APIs across your whole account, and any tool added later inherits the same reach. Keep it out of commits, screenshots and shared configuration files — if a key reaches a repository, revoke it and issue a new one rather than rewriting history.

Never put real data in a mock

Mock endpoints are unauthenticated and readable by anyone who has the URL, and whatever you save is served back verbatim. Keep production payloads, customer personal data, real tokens or API keys, internal hostnames and database ids out of them — use obviously fake values instead.

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.

terminal
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.

opencode.json
{
  "$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.

.codex/config.toml
[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.

.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

For an endpoint saved as users/:id, getEndpointCurl returns a URL still containing :id. Substitute a real value before running it — although, because :id matches any segment, sending it unchanged also returns the mock.

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

An unmatched route is a consumer telling you what it expected to find. Open the logs after wiring up a frontend and the 404 rows show what was asked for and did not exist — usually the endpoints still left to build.

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

response
HTTP/1.1 429 Too Many Requests
retry-after: 41328

{
  "error": "Rate limit exceeded",
  "window": "day"
}

The editor cleans some values silently

Rather than rejecting a response it cannot serve, the platform stores a corrected version — so these come back changed the next time you open the endpoint. Status codes outside 200–599 become 200; bodies are truncated at 256 KiB; you may keep at most 25 response headers; and 204, 205 and 304 always serve an empty body. Session, CORS and browser-security headers are dropped, along with the framing headers the runtime owns; your Content-Type is kept.

What a mock cannot do

Because the platform owns those headers, a mock cannot set cookies or browser-security policy — so it is not the right tool for exercising auth-cookie flows, CSP or framing behaviour. It is built for the shape of a response: status, headers you control, and body.