Skip to content
🎭 mimikos

Getting Started

Mimikos reads your OpenAPI spec and serves realistic, deterministic mock responses. No configuration files. No mock definitions. No maintenance when your API evolves.

Install

Section titled “Install”
Terminal window
go install github.com/mimikos-io/mimikos/cmd/mimikos@latest

Requires Go 1.25+.

Verify the installation:

Terminal window
mimikos --version

Your first mock server

Section titled “Your first mock server”

Point Mimikos at any OpenAPI spec:

Terminal window
mimikos start petstore.yaml
🎭 mimikos v0.4.0
Spec: Petstore (OpenAPI 3.1.0)
Operations: 5 endpoints classified


  METHOD  PATH                            BEHAVIOR  CONFIDENCE
  GET     /pets                           → list       high
  POST    /pets                           → create     high
  GET     /pets/{petId}                   → fetch      high
  DELETE  /pets/{petId}                   → delete     high
  PATCH   /pets/{petId}                   → update     high


Listening on :8080 (deterministic mode, strict=false)

Now make requests:

Terminal window
# Fetch a pet
curl http://localhost:8080/pets/42


# List all pets
curl http://localhost:8080/pets


# Create a pet
curl -X POST http://localhost:8080/pets \
  -H "Content-Type: application/json" \
  -d '{"name": "Buddy"}'

Every response is schema-valid and deterministic — the same request always returns the same response.

The mental model: spec is law

Section titled “The mental model: spec is law”

Mimikos mocks your API contract, not your business logic.

  • Endpoints are classified automatically from the spec’s HTTP methods, paths, and response schemas — list, fetch, create, update, delete
  • Responses are generated from the spec’s schemas — valid types, constraints satisfied, realistic field values
  • example values you define in the spec are used directly — property-level and media-type-level examples become mock responses without any additional configuration
  • When the spec changes, responses update automatically — no mock files to sync

You don’t configure behavior. The spec defines it. The example values most specs already include? Those are your mock data. No separate config files to create and maintain, no drift between your API contract and your mocks.

This means Mimikos won’t simulate business logic (auth, rate limiting, conditional workflows). It faithfully serves what the spec describes. See What Mimikos Doesn’t Do for deliberate boundaries.

Explore the full feature set

Section titled “Explore the full feature set”

The examples above use a simple spec. For a comprehensive evaluation of what Mimikos can do, download the PetShop Pro spec — a single 27-endpoint spec that exercises every Mimikos feature: nested resources, wrapper-aware responses, example precedence, polymorphism, error schemas, and stateful patterns.

Terminal window
curl -o petshop.yaml https://raw.githubusercontent.com/mimikos-io/mimikos/main/testdata/specs/petshop.yaml
Terminal window
mimikos start petshop.yaml

Explore it in both modes:

Terminal window
# Deterministic — see example values, semantic mapping, format-aware generation
curl http://localhost:8080/pets/42
curl http://localhost:8080/store/inventory
curl -H "X-Mimikos-Status: 404" http://localhost:8080/pets/42


# Stateful — full CRUD lifecycle
mimikos start --mode stateful petshop.yaml
curl -X POST http://localhost:8080/pets \
  -H "Content-Type: application/json" \
  -d '{"name": "Buddy", "status": "available"}'
curl http://localhost:8080/pets

See the petshop spec documentation for the full feature coverage matrix.

Using Mimikos with AI agents

Section titled “Using Mimikos with AI agents”

Mimikos includes a built-in MCP server that lets AI coding assistants (Claude Code, Cursor, VS Code Copilot) start mock servers, query endpoints, and manage resources through tool calls — no terminal switching required.

Terminal window
claude mcp add mimikos -- mimikos mcp

Once configured, your agent can start a server, create resources, and verify state without you writing a single curl command. See the MCP Server page for full setup and tool reference.

What’s next?

Section titled “What’s next?”