# DotMock complete agent context

> Generated from DotMock's typed documentation and the current billing catalog response. Documentation last verified 2026-07-24.

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

### Generic CLI LLM dry-run — Planned
The tester rejects LLM generic dry-runs with the conformance gate message.
The backend adapter remains gated until template conformance is complete.

## 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-, Cohere-, and Ollama-shaped responses from fixtures.

- URL: https://dotmock.com/docs/features/llm-mocking
- Status: Available
- Last verified: 2026-07-24
- Constraint: The generic CLI `dotmock test --kind llm` path remains planned until template conformance is complete.
- 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

## LLM fixtures
Match normalized requests to ordered content, tool, JSON, error, and workflow fixtures.

- URL: https://dotmock.com/docs/features/llm-fixtures
- Status: Available
- Last verified: 2026-07-24
- Constraint: Fixtures use AND matching across configured fields and are evaluated in their configured order.
- Sections: Match normalized request fields; Return content or a provider error; Model a complete tool workflow; Sequence behavior with shared state; Control timing and reliability

## LLM streaming
Test provider-shaped SSE events, token timing, truncation, malformed chunks, disconnects, and WebSocket events.

- URL: https://dotmock.com/docs/features/llm-streaming
- Status: Available
- Last verified: 2026-07-24
- Constraint: Timing controls are deterministic only when the scenario fixes the relevant latency, rate, and jitter values.
- Sections: Choose the protocol your client actually uses; Stream provider-shaped SSE events; Make timing part of the scenario; Describe WebSocket events directly; Exercise incomplete and invalid streams

## 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: Generic LLM CLI dry-runs are Planned; use provider routes and the LLM workspace tester for current LLM verification.
- 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-07-29
- Constraint: Generic `dotmock test --kind llm` is Planned even though fixture management and live provider routes are available.
- 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-07-24
- 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

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

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.

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