# DotMock complete agent context > Generated from DotMock's typed documentation and the current billing catalog response. Documentation last verified 2026-10-02. ## Operating model DotMock surrounds a real backend with controlled dependency behavior. A request is matched against a native protocol contract, may read or mutate explicitly configured state, and returns a typed response, fault, event sequence, or stream. Draft changes can be validated and simulated before publication. Management credentials authorize DotMock configuration and automation. Mock-runtime credentials model the contract expected by the system under test. Do not copy a management key into mock content or runtime examples. ## Capability matrix ### REST runtime — Available OpenAPI-backed matching, rendering, state actions, faults, proxying, and response hooks are connected. ### Realtime text and JSON — Available SSE and UTF-8 WebSocket scenarios, replay, proxying, traffic, and metering are connected. ### Binary WebSocket payloads — Limited The realtime mock and proxy handlers explicitly reject binary frames. Binary application messages are rejected with WebSocket close code 1003. ### GraphQL — Available Schema validation, query and mutation matching, subscription sequences, variables, aliases, errors, and APQ are implemented. ### gRPC — Available Descriptor import, four RPC modes, reflection, health, state, traffic, testing, and proxy settings are implemented. ### SOAP — Available WSDL and XSD import, SOAP 1.1/1.2 routing, XPath, faults, state, traffic, testing, and proxying are implemented. ### Webhook delivery — Available Event rendering, signing, live delivery, listeners, inspection, retry, and response hooks are implemented. ### State management and snapshots — Available Typed resources, atomic actions, live entries, snapshots, reset, and restore are implemented. ### Publication and rollback — Available Draft validation, publication revisions, diff, simulation, and rollback are implemented. ### CLI — Available Management, definitions, state, realtime, gRPC, SOAP, webhook, and generic dry-run commands are registered. ### MCP — Available Scoped, policy-classified tools cover current API, protocol, state, publication, and observability workflows. ### LLM fixtures, provider routes, and streaming — Available Fixture management and provider-shaped HTTP, SSE, and WebSocket runtimes are implemented. ### LLM CI helpers for the hosted mock — Preview The helpers apply config, scope traffic with X-Dotmock-Session, reset sequences, and read the journal through the hosted API. The GitHub Action, @dotmock/cli/testing, and pytest-dotmock ship with @dotmock/cli 0.3.1. ### LLM record and replay — Preview The LLM runtime forwards unmatched requests to SSRF-checked https upstreams, records responses, and replays them by request hash. Hosted settings accept proxy, record, replay, and none fallbacks; recordings can be promoted to fixtures. ### Generic CLI LLM dry-run — Available The tester routes LLM dry-runs through the mock runtime with X-DotMock-Dry-Run and an isolated X-Dotmock-Session, and returns the matched fixture and a first-match trace. ## Documentation catalog ## DotMock documentation Choose a task, understand the runtime boundaries, and build a mock from verified product behavior. - URL: https://dotmock.com/docs - Status: Available - Last verified: 2026-07-24 - Constraint: Documentation describes shipped behavior and calls out gated or constrained paths separately. - Sections: Build the first mock; Choose a native protocol; Add behavior; Connect the CLI or an agent; Capability matrix and boundaries ## Build a stateful users API Create a REST mock, store users, return them by ID, and prove the missing-user branch. - URL: https://dotmock.com/docs/quickstart - Status: Available - Last verified: 2026-07-24 - Constraint: Management commands require a DotMock credential; calls to $MOCK_URL use only credentials configured for the mock runtime. - Sections: Create a REST workspace; Add the users-by-id state resource; Create and store a user; Read the user and model the 404; Merge a partial update; Prove the behavior safely ## How DotMock works Follow a definition from authoring through matching, state, rendering, publication, and delivery. - URL: https://dotmock.com/docs/concepts/how-it-works - Status: Available - Last verified: 2026-07-24 - Constraint: Dry-runs disable persistent state writes, webhook delivery, proxying, and callouts. - Sections: A workspace owns one mock surface; Configuration and runtime data are separate; Every request follows one order; Templates preserve JSON types; Preview safely, then exercise the live URL; Use the same system from every tool ## APIs and endpoints Model REST methods, paths, schemas, responses, faults, state actions, and response hooks. - URL: https://dotmock.com/docs/concepts/apis-endpoints - Status: Available - Last verified: 2026-07-24 - Constraint: Runtime behavior is limited to methods and response behavior represented by the active definition. - Sections: Start with method, path, and intent; Reuse models instead of copying shapes; Keep dynamic responses typed; Put failure cases beside success; Add state, faults, and hooks intentionally; Prove both the response and the side effects ## Request matching Select deterministic behavior from operation, request data, time, and state. - URL: https://dotmock.com/docs/concepts/request-matching - Status: Available - Last verified: 2026-07-24 - Constraint: Conditions are evaluated in their configured order; the first matching enabled branch wins. - Sections: Match the operation before the branch; Read request data with bounded scopes; Use state to represent what the system knows; Keep branches specific and the fallback obvious; Inspect the winner instead of guessing ## Templates and expressions Render typed values from request scopes, deterministic helpers, and shared state. - URL: https://dotmock.com/docs/reference/templates - Status: Available - Last verified: 2026-07-24 - Constraint: Helpers are scoped to the active protocol runtime; unsupported helper names fail validation rather than executing arbitrary code. - Sections: Exact and embedded expressions behave differently; REST request helpers; GraphQL request helpers; gRPC request helpers; SOAP request helpers; Conditions use one visible expression language; Read state with dynamic keys and fallbacks; Use atomic mutation helpers; Know the runtime boundary ## Realtime SSE and WebSockets Author OpenAPI SSE streams and AsyncAPI WebSocket channels with scenarios, replay, proxying, and traffic timelines. - URL: https://dotmock.com/docs/guides/realtime - Status: Limited - Last verified: 2026-07-24 - Boundary: UTF-8 text and JSON workflows are available. Binary WebSocket application messages are rejected with close code 1003. - Constraint: Binary WebSocket application payloads are not supported. - Constraint: GraphQL subscriptions and LLM streams use their protocol-specific runtimes. - Sections: Keep each transport in its native contract; Use deterministic connection scenarios; Connect browser-native clients safely; Resume and replay the exact connection; Inspect bounded mock and proxy sessions ## GraphQL Mock schema-native queries, mutations, variables, aliases, errors, subscriptions, and persisted queries. - URL: https://dotmock.com/docs/guides/graphql - Status: Available - Last verified: 2026-07-24 - Constraint: GraphQL dry-runs validate the operation against the workspace schema and do not persist side effects. - Sections: Define the schema first; Configure a query with request data; Use variables and headers for scenarios; Reuse persistent state across operations; Test subscriptions as an event sequence; Dry-run the native operation ## gRPC Import protobuf contracts and mock unary or streaming RPCs with reflection, state, traffic, and proxying. - URL: https://dotmock.com/docs/guides/grpc - Status: Available - Last verified: 2026-07-24 - Constraint: Live tests and managed upstream credentials remain explicit approval or trusted-UI boundaries. - Sections: Compile the contract; Author descriptor-valid transcripts; Use the normal condition language; Prove dry and live behavior; Connect standard clients; Proxy with managed TLS or mTLS ## SOAP Import WSDL and XSD contracts, route SOAP 1.1 or 1.2, return faults, use state, and proxy upstreams. - URL: https://dotmock.com/docs/guides/soap - Status: Available - Last verified: 2026-07-24 - Constraint: Live tests can contact a configured runtime and remain approval-aware; dry-runs do not proxy. - Sections: Import the service contract; Route SOAP 1.1 and 1.2 natively; Use XPath in ordinary conditions; Return native XML and faults; Compare safe and live behavior; Proxy and promote deliberately ## LLM APIs Serve deterministic OpenAI-, Anthropic-, Gemini-, Bedrock-, Azure-, Cohere-, and Ollama-shaped responses from fixtures. - URL: https://dotmock.com/docs/features/llm-mocking - Status: Available - Last verified: 2026-09-25 - Constraint: `dotmock test --kind llm --message ...` and MCP `send_llm_test_request` dry-run through the hosted runtime in an isolated session and report the matched fixture. - Sections: Create an LLM workspace; Change the base URL, not the client behavior; Fixtures define the behavior; Return the outcome your app must handle; Test with the built-in conversation panel; Keep a small real-provider suite ## LLM mocking quickstart Create an LLM mock, point the OpenAI, Anthropic, Gemini, Vercel AI SDK, LangChain, or LlamaIndex client at it, and add the first fixture. - URL: https://dotmock.com/docs/guides/llm-quickstart - Status: Available - Last verified: 2026-09-25 - Constraint: SDK API keys pointed at the mock are placeholders; never use a DotMock management credential as an SDK key. - Sections: Create an LLM mock and copy the base URL; Send a request with curl; Point the SDK you already use at the mock; Add the first fixture; Keep the fixtures in your repository ## LLM providers and endpoints Every provider route, base URL, streaming envelope, reasoning field, and error shape the LLM mock serves. - URL: https://dotmock.com/docs/reference/llm-providers - Status: Available - Last verified: 2026-09-25 - Constraint: Unmatched requests return 404 no_fixture_matched unless a VCR fallback is configured. - Constraint: WebSocket fixtures replay scripted events and do not run chaos, sequences, templates, workflows, or the journal. - Sections: Served routes; Base URL per SDK; Streaming format per provider; Request normalization; Reasoning and structured outputs by provider; Errors, headers, and unmatched requests ## LLM fixtures reference Match fields, structured conditions, priority, sequences and sessions, templates, reasoning, structured outputs, and errors. - URL: https://dotmock.com/docs/features/llm-fixtures - Status: Available - Last verified: 2026-09-25 - Constraint: Fixtures use AND matching across configured fields; enabled fixtures are evaluated by ascending priority and the first match wins. - Constraint: An unknown template helper leaves the whole string unprocessed. - Sections: Fixture structure; Match fields; Structured conditions; Priority and first match; Sequences, sessions, and reset; Content, usage, and provider errors; Templates and placeholders; Reasoning output; Structured outputs; Sequence behavior with shared state ## Agent tool-call workflows Mock a full agent tool round trip, parallel tool calls, and tool-result branches with one workflow fixture. - URL: https://dotmock.com/docs/guides/llm-tool-workflows - Status: Available - Last verified: 2026-09-25 - Constraint: Tool placeholders resolve only in a workflow's final response. - Sections: How the two phases work; A complete single-tool example; Drive it from the real client; Parallel tool calls; Branch on tool results and turns; Assert the loop in tests ## LLM streaming physics Control chunk size, time to first token, token rate, jitter, per-chunk delays, truncation, and WebSocket events. - URL: https://dotmock.com/docs/features/llm-streaming - Status: Available - Last verified: 2026-09-25 - Constraint: Timing is deterministic only when the fixture fixes its delays and X-Dotmock-Seed pins jitter. - Sections: When a response streams; Streaming fields; How each delay is chosen; Truncated and broken streams; Describe WebSocket events directly ## LLM chaos and failure testing Inject drops, malformed stream frames, mid-stream disconnects, and 429 rate limits per API, fixture, or request, reproducibly. - URL: https://dotmock.com/docs/guides/llm-chaos - Status: Available - Last verified: 2026-09-25 - Constraint: Chaos is probabilistic unless the request sends X-Dotmock-Seed or a rate of 0 or 1. - Constraint: Hosted API settings currently accept dropRate, malformedRate, and disconnectRate; use fixture chaos or request headers for rate limits. - Sections: Failure actions; Configure at three levels; Make chaos reproducible with X-Dotmock-Seed; Use deterministic errors for assertions; Scope and limits ## LLM record and replay (VCR) Forward unmatched requests to real providers, record and replay responses, and promote recordings into fixtures. - URL: https://dotmock.com/docs/features/llm-vcr - Status: Preview - Last verified: 2026-09-25 - Boundary: VCR record, replay, and recording promotion are in preview. Hosted API settings accept the fallback types proxy, record, replay, and none. - Constraint: Upstreams must be public https URLs; private, loopback, link-local, and internal service hosts are rejected. - Constraint: Recordings are kept for 7 days, up to 200 per API. - Sections: Configure upstreams; Record, replay, and off; Promote recordings into fixtures; Credentials, redaction, and network safety ## LLM request journal and assertions See which fixture answered each LLM request from the dashboard, CLI, or MCP, and assert it in tests. - URL: https://dotmock.com/docs/features/llm-journal - Status: Available - Last verified: 2026-09-25 - Constraint: Hosted journals keep the latest 1,000 entries per API for one hour; credentials are redacted. - Sections: What an entry records; Read the journal from any surface; Assert fixture matches in tests; Retention and redaction ## Testing LLM apps in CI Test LLM apps in CI against a hosted DotMock mock: API key secret, config-as-code, per-run sessions, sequence resets, journal assertions, the GitHub Action, and Vitest and pytest helpers. - URL: https://dotmock.com/docs/guides/llm-ci - Status: Preview - Last verified: 2026-09-26 - Boundary: The GitHub Action, @dotmock/cli/testing, and pytest-dotmock ship with @dotmock/cli 0.3.1 and are in preview. The mock itself is the hosted DotMock runtime. - Constraint: The mock runs only in DotMock's cloud; CI jobs need network access to it and a DOTMOCK_API_KEY secret. - Constraint: @dotmock/cli/testing is ESM-only. - Sections: Store the API key as a CI secret; Keep the fixtures in the repository; Isolate each run with a session; Use the GitHub Action; Assert fixtures from Vitest or Jest; Assert fixtures from pytest ## LLM mocks with coding agents Connect Claude Code, Cursor, Codex, or VS Code to the MCP server and run the create, run, inspect, reset loop. - URL: https://dotmock.com/docs/guides/llm-coding-agents - Status: Available - Last verified: 2026-09-25 - Constraint: Deleting fixtures and changing runtime settings require explicit approval; the management credential stays in the MCP client. - Sections: Connect your client; LLM tools; The LLM mock loop; Agents that use the CLI; Approval boundaries ## Webhooks Render, sign, deliver, inspect, retry, and connect webhook events to REST response hooks. - URL: https://dotmock.com/docs/guides/webhook-workflows - Status: Available - Last verified: 2026-07-24 - Constraint: Render and dry-run paths never deliver. Delivery attempts and retries are observable separately from the selected REST response. - Sections: Create an event definition; Render before delivery; Connect a local listener; Trigger and inspect a delivery; Fire an event after a REST response; Exercise retries and idempotency ## Protocol coverage Compare verified authoring, testing, runtime, state, traffic, and automation boundaries by protocol. - URL: https://dotmock.com/docs/reference/protocols - Status: Available - Last verified: 2026-07-24 - Constraint: The matrix distinguishes shipped protocol behavior from Limited and Planned paths. - Sections: REST; Realtime SSE and WebSockets; GraphQL; gRPC; SOAP; LLM providers; Webhooks; What shipped workspaces share ## Stateful mocking Build CRUD, counters, queues, carts, sessions, collections, TTLs, snapshots, and state machines. - URL: https://dotmock.com/docs/guides/stateful-mocking - Status: Available - Last verified: 2026-07-24 - Constraint: Restoring or resetting live state is destructive and requires explicit authorization. - Sections: Choose the resource by behavior; Use the narrowest useful scope; Understand the atomic execution order; Use proven state patterns; Manage live values without surprises; Preview the exact diff ## Conditional responses Model success, validation, missing data, rate limits, faults, and upstream errors as explicit branches. - URL: https://dotmock.com/docs/features/response-rules - Status: Available - Last verified: 2026-07-24 - Constraint: Transport faults and application responses are distinct behaviors and should be configured separately. - Sections: A condition selects a full response; Use conditions for domain outcomes; Return the same error shape your client expects; Do not use an application response to fake a broken connection; Prove one branch at a time ## Faults and proxying Mock selected behavior, proxy unmatched traffic, and make latency or upstream failures explicit. - URL: https://dotmock.com/docs/features/proxy-mode - Status: Available - Last verified: 2026-07-24 - Constraint: Dry-runs never contact the upstream. Live proxying requires an explicitly configured trusted target. - Sections: Understand the routing decision; Set one trusted upstream; Know what is forwarded; Make proxy failure explicit in tests; Dry-run never contacts the upstream ## Testing and dry-runs Prove winners, response bodies, state diffs, sequences, and failures without mutating live state. - URL: https://dotmock.com/docs/guides/testing - Status: Available - Last verified: 2026-07-24 - Constraint: LLM dry-runs (dotmock test --kind llm, MCP send_llm_test_request) go through the hosted runtime in an isolated session; VCR-enabled APIs may still proxy unmatched dry-run requests upstream. - Sections: Know what a dry-run guarantees; Fix seed, clock, and state; Cover the contract, not only 200; Assert protocol-native details; Run the application against the scenario; Inspect near misses before broadening a matcher ## DotMock CLI Create, configure, test, inspect, publish, rollback, and deliver mocks from a terminal or CI. - URL: https://dotmock.com/docs/guides/cli - Status: Available - Last verified: 2026-10-02 - Constraint: Destructive commands require --yes in CI and other non-interactive shells. - Sections: Install, authenticate, and verify scope; Discover before creating; Create from a contract or prompt; Configure complete endpoint behavior; Run deterministic dry-runs; Automate protobuf and streaming mocks; Import and exercise SOAP contracts; Receive and inspect webhooks; Keep publish and rollback explicit ## MCP and coding agents Give coding agents scoped tools for inspection, draft authoring, simulation, publication, and protocol workflows. - URL: https://dotmock.com/docs/features/mcp-integration - Status: Available - Last verified: 2026-10-02 - Constraint: Secret-bearing connection management stays on trusted UI or direct REST surfaces; destructive operations require approval. - Sections: Connect the MCP server securely; Inspect before authoring; Mutate the shared draft with one valid payload; Simulate before publication; Keep destructive actions approval-aware ## Traffic capture Inspect protocol-aware requests and promote selected traffic into editable behavior. - URL: https://dotmock.com/docs/features/traffic-capture - Status: Available - Last verified: 2026-07-24 - Constraint: Traffic promotion creates editable behavior from a user-selected capture; it does not make arbitrary captures live automatically. - Sections: Capture requests sent to the mock; Read the request as structured data; Connect the winner to the rendered result; Use protocol-aware inspection; Promote a useful request carefully ## OpenAPI import Create and review a REST workspace from an OpenAPI or Swagger source document. - URL: https://dotmock.com/docs/features/import-openapi - Status: Available - Last verified: 2026-07-24 - Constraint: Imported contracts still require review and explicit behavior for important success and failure journeys. - Sections: Use a complete, valid source document; Create the workspace from OpenAPI; Review the contract before adding behavior; Prove the important journeys ## Authentication Keep management credentials separate from credentials and headers expected by the mock runtime. - URL: https://dotmock.com/docs/features/authentication - Status: Available - Last verified: 2026-07-24 - Constraint: A management credential authorizes DotMock actions; it must not be treated as a simulated provider credential. - Sections: Know which system is authenticating; Require a team API key on the mock; Model the authentication contract your client expects; Keep credentials out of mock content ## Team collaboration Share workspaces, drafts, state resources, traffic, and automation through team-scoped roles. - URL: https://dotmock.com/docs/features/collaboration - Status: Available - Last verified: 2026-07-24 - Constraint: Membership, billing, and sensitive settings require the relevant team role and remain outside ordinary API authoring. - Sections: APIs belong to a team workspace; Assign the narrowest useful role; Treat the draft as shared state; Share state only when the workflow needs it; Leave a reproducible handoff ## Contact DotMock Send the DotMock team a product, documentation, evaluation, or technical question. - URL: https://dotmock.com/docs/contact - Status: Available - Last verified: 2026-07-24 - Constraint: The form confirms only whether the public endpoint accepted the message; no response-time promise is implied. - Sections: Send a message; What to include ## LLM mocking quick reference Guides: https://dotmock.com/docs/guides/llm-quickstart, https://dotmock.com/docs/features/llm-fixtures, https://dotmock.com/docs/guides/llm-ci ### Base URLs - OpenAI-compatible SDKs (OpenAI, Vercel AI SDK, LangChain, LlamaIndex): `$MOCK_URL/v1` - Anthropic, Gemini (google-genai), Azure OpenAI, Bedrock endpoint_url, Ollama, Cohere: `$MOCK_URL` - The mock runs only in DotMock's cloud; `dotmock llm connect ` prints its hosted base URLs - SDK API keys are placeholders (any non-empty value). Never use a DotMock management credential as an SDK key. ### Routes - POST /v1/chat/completions, /v1/responses, /v1/embeddings; GET /v1/models - POST /v1/messages, /v1/messages/count_tokens (Anthropic) - POST /v1beta/models/{model}:generateContent and :streamGenerateContent (Gemini) - POST /model/{id}/converse, /converse-stream, /invoke, /invoke-with-response-stream (Bedrock, AWS event-stream) - POST /openai/deployments/{deployment}/chat/completions (Azure), /api/chat and /api/generate (Ollama, NDJSON), /v2/chat (Cohere) - WebSocket upgrades on /v1/responses and /v1/chat replay scripted fixture events - Unmatched requests return 404 `no_fixture_matched` unless a VCR fallback is configured ### Fixture shape - `{ name, priority, enabled, protocol, match, response | workflow | ws, streaming, latency, chaos, stateActions }`; lower priority first, first match wins, match fields are ANDed - match: userMessage, systemPrompt, inputText (substring or /regex/), model (exact or glob), toolName, toolCallId, hasToolResult, responseFormat, temperature, provider, endpoint, turnIndex, context, sequenceIndex, conditions - conditions: `{ field, operator, value }`; operators contains, equals, startswith, endswith, regex, glob, is, exists, >, >=, <, <=, window (request.time); fields include `$.`, `context.`, `random` - response: content, reasoning, toolCalls[{id,name,arguments,result}], finishReason, usage{promptTokens,completionTokens,reasoningTokens}, error{status,type,message} - workflow: `run.toolCalls` returned first; `response` served once a matching tool result arrives; placeholders {{tool.result}}, {{tool..result}}, {{tool..args.}}, {{userMessage}} - streaming: chunkSize (default 20), ttftMs, tps, latencyMs, jitter (fraction), interChunkDelaysMs, totalDurationMs, replaySpeed, truncateAfterChunks - chaos: dropRate, rateLimitRate, malformedRate, disconnectRate, disconnectAfterChunks, retryAfterSeconds ### Request headers - `X-Dotmock-Session`: isolates sequence counters per test (default `default`) - `X-Dotmock-Seed`: integer seed for chaos, jitter, random conditions, IDs, and faker helpers - `X-Dotmock-Chaos-Drop|RateLimit|Malformed|Disconnect` (0-1), `X-Dotmock-Chaos-Disconnect-After`, `X-Dotmock-Chaos-Retry-After` - Responses include `x-dotmock-fixture-id` and `x-dotmock-fixture-name` ### Automation - CLI (authenticated with `DOTMOCK_API_KEY` or `dotmock login`): `dotmock init --llm`, `dotmock config apply`, `dotmock llm journal|reset|recordings|promote|vcr|connect [--session ]` - CI: GitHub Action `mockitoHQ/dotmock-cli/action@v1` (input `api-key`; exports OPENAI_BASE_URL, ANTHROPIC_BASE_URL, DOTMOCK_URL, DOTMOCK_SESSION) - Tests: `@dotmock/cli/testing` (connectDotmock, resetDotmock, getJournal, expectFixtureMatched) and `pytest-dotmock` (`dotmock`, `dotmock_api` fixtures) against the hosted mock with `DOTMOCK_API_KEY` and `DOTMOCK_API` - MCP: create_llm_fixture, get_llm_connection_info, get_llm_journal, reset_llm_sequences, list_llm_recordings, promote_llm_recording - Management API: GET|DELETE /mock-apis/{apiId}/llm-fixtures/journal, POST /mock-apis/{apiId}/llm-fixtures/reset-sequences # How DotMock works > DotMock surrounds a real backend with controlled dependencies. It does not replace the backend. ## 01. Create or import the contract Start from OpenAPI, GraphQL, WSDL, Protobuf, or a focused workspace. DotMock keeps protocol-specific structure instead of flattening everything into generic HTTP. ## 02. Model behavior, not only responses Add conditions, persistent state, latency, failures, streams, tool calls, and outbound events so the dependency behaves like the system your code must survive. ## 03. Point the development environment at DotMock Swap the third-party base URL or client target in development and test configuration. Keep the application flow and client code intact. ## 04. Exercise, inspect, and reset Run the real flow, inspect matched traffic and state changes, verify deliveries, then reset the environment for a reproducible next run. ## Governed agent execution Coding agents can connect through CLI or MCP. DotMock keeps material changes evidence-based and approval-gated. 1. **Inspect:** Read the active contract, state, traffic, and capability boundaries before changing anything. 2. **Draft:** Prepare the smallest workspace change without publishing it immediately. 3. **Validate:** Run validation, simulation, or a dry run and show the expected response and state diff. 4. **Approve:** Require explicit approval for publication, rollback, deletion, reset, or other sensitive actions. 5. **Verify:** Report the resulting route, revision, traffic, delivery, or state evidence. ## Common controlled runs ### Recover from an upstream outage Stage latency, timeouts, retries, and a controlled recovery without waiting for the real provider to fail. ### Complete a stateful checkout Move a cart through payment and fulfillment state while emitting the same webhooks the backend consumes. ### Test an LLM tool loop Return a deterministic tool call, accept the tool result, then stream the final provider-shaped response. ### Prove authentication failures Exercise expired credentials, missing scopes, rate limits, and recovery paths against a stable contract. ## Related resources - [Protocols and interfaces](https://dotmock.com/protocols.md) - [Concept guide](https://dotmock.com/docs/concepts/how-it-works.md) - [CLI guide](https://dotmock.com/docs/guides/cli.md) - [MCP integration](https://dotmock.com/docs/features/mcp-integration.md) Canonical HTML: https://dotmock.com/how-it-works # DotMock protocols and interfaces > DotMock preserves the interface an application already speaks while giving the development environment control over its data, state, timing, errors, streams, and outbound events. ## REST Model payment, identity, shipping, CRM, and other HTTP dependencies with the paths, methods, schemas, state, latency, and failures your client expects. - OpenAPI import and contract-shaped endpoints - Conditional responses, persistent state, and proxy mode - Traffic inspection and deterministic error paths - Guide: https://dotmock.com/docs/quickstart ## GraphQL Keep GraphQL operations native while controlling resolver data, partial errors, variables, mutations, and subscription events. - Schema-aware queries and mutations - GraphQL error envelopes and response data - Subscription sequences for realtime tests - Guide: https://dotmock.com/docs/guides/graphql ## SOAP Exercise enterprise integrations against their real XML shape, operation names, namespaces, and typed SOAP faults. - WSDL and XSD contract workflows - SOAP envelope and operation matching - Protocol-native fault responses - Guide: https://dotmock.com/docs/guides/soap ## gRPC Test Protobuf services with metadata, typed messages, status codes, and unary or streaming behavior without a live upstream. - Service and method contracts - Metadata and gRPC status behavior - Unary and streaming test paths - Guide: https://dotmock.com/docs/guides/grpc ## Realtime Reproduce connection lifecycles and ordered message sequences, including delays, disconnects, and recovery behavior. - WebSocket and server-sent event flows - Timed sequences and connection state - Disconnect and retry scenarios - Guide: https://dotmock.com/docs/guides/realtime ## LLM APIs Return provider-compatible chat, response, streaming, usage, tool-call, and failure payloads without spending against a model provider. - Deterministic fixtures and tool calls - Streaming, latency, and malformed output - Usage and provider-shaped error responses - Guide: https://dotmock.com/docs/features/llm-mocking ## Webhooks Trigger signed outbound events, inspect attempts, and verify retry, delay, and failure handling as part of the same scenario. - Signed event payloads - Delay, retry, and failure policies - Outbound-attempt inspection - Guide: https://dotmock.com/docs/guides/webhook-workflows ## Related resources - [How DotMock works](https://dotmock.com/how-it-works.md) - [Protocol capability boundaries](https://dotmock.com/docs/reference/protocols.md) - [Pricing](https://dotmock.com/pricing.md) Canonical HTML: https://dotmock.com/protocols # About DotMock > Deterministic systems must exist before prompt and context optimization can mean anything. DotMock is a hosted mock server for REST, GraphQL, SOAP, gRPC, realtime, webhook, and LLM provider APIs. Coding agents and developers point an application at it instead of a real dependency, then run success, failure, and retry paths without touching production. Agent-driven development makes software loops faster and more autonomous. It also makes every unstable dependency, irreversible side effect, and missing trace more expensive. DotMock gives agents a controlled environment in which they can integrate, fail, retry, recover, and produce evidence. ## DotMock at a glance - **What it is:** DotMock is a hosted mock server for the APIs a backend depends on. It is operated by Olio LLC. (https://dotmock.com/docs/concepts/how-it-works) - **Interfaces:** 7 interface types: REST (OpenAPI), GraphQL, SOAP 1.1 and 1.2 (WSDL/XSD), gRPC (protobuf, unary and streaming), realtime SSE and WebSocket, LLM provider APIs, and webhooks. (https://dotmock.com/docs/reference/protocols) - **LLM providers:** 7 LLM provider API shapes from one mock: OpenAI (Chat Completions, Responses, embeddings), Anthropic Messages, Google Gemini, AWS Bedrock, Azure OpenAI, Ollama, and Cohere. (https://dotmock.com/docs/reference/llm-providers) - **Streaming and failures:** LLM responses stream over SSE with a default chunk size of 20 characters, configurable time to first token and tokens per second, and injectable drops, malformed frames, disconnects, and 429 rate limits. (https://dotmock.com/docs/features/llm-streaming) - **Testing in CI:** CI jobs test against the hosted mock with a DotMock API key secret: fixtures apply from the repository, and each run gets its own X-Dotmock-Session for isolated sequences and journal assertions (preview in @dotmock/cli 0.3.1). (https://dotmock.com/docs/guides/llm-ci) - **Automation:** Agents manage mocks through the DotMock CLI or the MCP server at https://mcp.dotmock.com/mcp, authenticated with a team-scoped API key. (https://dotmock.com/docs/features/mcp-integration) - **Pricing:** Free ($0 a month) includes $1 of monthly usage for one workspace; paid plans draw every live interaction from one prepaid USD balance, and live runs pause at zero instead of billing overage. (https://dotmock.com/pricing) ## Principles - **Contracts before improvisation:** Model the interface and its behavior before asking a model to guess what the world looks like. - **Safe loops over impressive demos:** A reproducible failure-and-recovery path matters more than a polished happy path. - **Evidence over confidence:** Traffic, state changes, deliveries, drafts, and approvals should be visible and attributable. - **Native behavior over generic mocks:** REST, GraphQL, SOAP, gRPC, realtime, LLM APIs, and webhooks retain their own runtime semantics. Canonical HTML: https://dotmock.com/about # DotMock pricing > Retrieved from the active DotMock billing catalog. The HTML pricing page at https://dotmock.com/pricing is canonical. ## Free - Description: For manually building and running one mock workspace. - Monthly price: $0 USD per month - Annual price: $0 USD per year - Monthly usage balance: $1 - Active workspaces: 1 - Collaborators: 0 - Realtime concurrency: 5 - Self-service: No - $1 monthly usage included - One active workspace and no collaborators - Manual authoring and isolated dry runs - REST, GraphQL, SOAP, gRPC, LLM API, realtime, and webhook mocks - 25 outbound message-equivalents/second with a burst of 100 - No Dot copilot ## Developer - Description: For builders running agent loops against controlled dependencies. - Monthly price: $12 USD per month - Annual price: $120 USD per year - Monthly usage balance: $12 - Active workspaces: 3 - Collaborators: 0 - Realtime concurrency: 20 - Self-service: Yes - $12 monthly usage included - Three active workspaces and no collaborators - Dot and provider-backed authoring are charged at provider cost × 5 - REST, realtime, GraphQL, SOAP, gRPC, LLM API, and webhook mocks - State, failures, retries, traffic, and audit history - 20 concurrent realtime connections ## Team - Description: For teams sharing contracts, scenarios, approvals, and audit history. - Monthly price: $49 USD per month - Annual price: $490 USD per year - Monthly usage balance: $49 - Active workspaces: 20 - Collaborators: Unlimited - Realtime concurrency: 100 - Self-service: Yes - $49 monthly usage included - 20 active workspaces and unlimited collaborators - Shared Dot usage is charged at provider cost × 5 - Shared mock workspaces and deterministic scenarios - Team approvals, traffic inspection, and audit history - 100 concurrent realtime connections ## Enterprise - Description: For organizations evaluating custom controls, scale, and support. - Monthly price: Contact-led - Annual price: Contact-led - Monthly usage balance: Custom - Active workspaces: Custom - Collaborators: Unlimited - Realtime concurrency: Custom - Self-service: No - Custom usage balance, active workspaces, and concurrency - Unlimited collaborators - Security and procurement review - Migration and rollout planning - Contact-led pricing ## Usage rates - Standard interaction: $0.10 per 1,000 - LLM fixture: $0.10 per 1M token-equivalents, rounded per response to started 1K blocks - Realtime: $0.10 per 1,000 opens, $0.01 per 1,000 minutes, and $0.001 per 1,000 messages - Webhook: $0.10 per 1,000 triggers plus $0.10 per 1,000 outbound attempts - Proxy: $0.20 per 1,000 interactions - Dot and provider-backed authoring: provider-reported cost multiplied by 5 ## Reloads - Preset and custom prepaid amounts start at $10 USD - Purchased balance expires after 12 months - Included and purchased balance use the same retail rates - There are no postpaid overage invoices; live usage pauses when no balance remains - Reloads require an active paid subscription ## Free - 1 active workspace - $1 monthly runtime usage balance - No collaborators; workspace sharing requires Team - Manual authoring, public execution, and isolated dry runs are available - Provider-backed Dot authoring is not included Pricing and entitlements can change. Re-read this document or the canonical pricing page before making a purchasing recommendation. # DotMock auth.md > Authentication guidance for agents and MCP clients connecting to DotMock. ## Audience This document is for coding agents, MCP clients, CI jobs, and developers operating inside an existing DotMock workspace. ## Supported method - Method: Team-scoped API key - Provisioning: A signed-in workspace member creates the key in https://dotmock.com/settings/team/api-keys - Transport: Send the key in the `x-api-key` header - MCP endpoint: https://mcp.dotmock.com/mcp - Unattended public registration: Not supported - OAuth authorization server: Not available ## MCP client configuration ```json { "mcpServers": { "dotmock": { "type": "http", "url": "https://mcp.dotmock.com/mcp", "headers": { "x-api-key": "${input:dotmock-api-key}" } } } } ``` ## Credential boundaries - The team API key is a management credential. Keep it in the MCP client's secure input or secret store. - Never place a management credential in an OpenAPI example, mock response, fixture, captured payload, or request to `$MOCK_URL`. - Runtime authentication configured for a mock is separate from management authentication. - Tool visibility and execution are restricted by the key's team, scopes, permissions, plan, and allowed-tool policy. ## Safe execution - Inspect the workspace before authoring. - Prefer validation, simulation, and dry-run tools before live or persistent actions. - Publication, rollback, deletion, state reset or restore, traffic promotion, and live protocol tests require explicit approval in their tool schemas. Documentation: https://dotmock.com/docs/features/mcp-integration