Stateful Mode

Stateful mode turns Mimikos into a CRUD mock server. Resources you create with POST are stored in memory and returned by subsequent GET, PUT/PATCH, and DELETE requests.

mimikos start --mode stateful petstore.yaml

The lifecycle

# 1. Create a pet
curl -s -X POST http://localhost:8080/pets \
  -H "Content-Type: application/json" \
  -d '{"name": "Buddy"}'
# → 201 {"id": "abc-123", "name": "Buddy", "tag": "..."}

# 2. Fetch by ID (uses the returned ID)
curl http://localhost:8080/pets/abc-123
# → 200 {"id": "abc-123", "name": "Buddy", "tag": "..."}

# 3. List all pets
curl http://localhost:8080/pets
# → 200 [{"id": "abc-123", "name": "Buddy", ...}]

# 4. Update
curl -X PATCH http://localhost:8080/pets/abc-123 \
  -H "Content-Type: application/json" \
  -d '{"name": "Buddy Jr."}'
# → 200 {"id": "abc-123", "name": "Buddy Jr.", "tag": "..."}

# 5. Delete
curl -X DELETE http://localhost:8080/pets/abc-123
# → 204

# 6. Fetch after delete
curl http://localhost:8080/pets/abc-123
# → 404

How it works

Mimikos classifies each endpoint and maps HTTP methods to CRUD operations:

Operation	What happens
POST (create)	Generates a response from the schema, merges in your request body fields, stores the result
GET item (fetch)	Returns the stored resource by ID, or 404
GET collection (list)	Returns all stored resources of that type (empty array until first POST)
PUT/PATCH (update)	Shallow-merges your request body into the stored resource, returns the result
DELETE	Removes the resource, returns 204 (or the spec-defined success code)

Endpoints classified as generic fall through to deterministic generation — they aren’t part of a CRUD lifecycle.

Resource identity

Mimikos infers which field is the resource ID using a 6-strategy algorithm:

1. Exact body field matching the path parameter name
2. Suffix stripping (e.g., path param petId → body field pet or id)
3. ID field hint from the spec’s schema structure
4. Body id field fallback
5. Path parameter value
6. Deterministic UUID generation

This covers common patterns: Notion (id), Asana (gid), Twilio (sid), Stripe (customer → body id).

Wrapper-aware responses

Real-world APIs often wrap responses in envelope objects. Mimikos handles this automatically:

// Asana-style wrapped response
{
  "data": {
    "gid": "12345",
    "name": "My Task"
  }
}

// Stripe-style list envelope
{
  "data": [...],
  "has_more": false
}

• Single-object wrappers are unwrapped before storage and re-wrapped on read
• List envelopes are generated from the schema with stored resources injected into the array slot

Nested resource isolation

Resources are scoped by their parent path. Creating a task under project 1 doesn’t leak into project 2:

# Create tasks under different projects
curl -X POST http://localhost:8080/projects/1/tasks \
  -H "Content-Type: application/json" -d '{"name": "Task A"}'

curl -X POST http://localhost:8080/projects/2/tasks \
  -H "Content-Type: application/json" -d '{"name": "Task B"}'

# List only returns tasks for that project
curl http://localhost:8080/projects/1/tasks
# → [{"name": "Task A"}]  (Task B is not here)

Capacity and eviction

Resources are stored in memory with LRU (least recently used) eviction:

mimikos start --mode stateful --max-resources 500 petstore.yaml

Flag	Default	Description
--max-resources	10000	Max stored resources across all types

When capacity is reached, the least recently accessed resource is evicted. Restarting the server clears all state.

Note

The X-Mimikos-Status header works in stateful mode too — it bypasses stateful logic entirely and returns a deterministic response for the requested status code. No state mutation occurs.

Strict mode

Strict mode applies to stateful mode the same way it does to deterministic mode:

mimikos start --mode stateful --strict petstore.yaml

Response validation: If a generated response fails schema validation, Mimikos returns a 500 error instead of sending the invalid response with a warning.

Request validation on degraded schemas: If a request schema failed to compile at startup, body-bearing methods (POST, PUT, PATCH) return 500 immediately. Without strict mode, Mimikos skips request validation and processes the request anyway — which means resources could be created or updated with invalid data.

Strict mode is useful when you want confidence that every resource stored in the mock server conforms to your spec.

Deterministic mode vs. stateful mode

	Deterministic (default)	Stateful
GET item	Always returns generated data	404 until POST creates it
GET list	Always returns generated array	Empty until POST creates resources
POST	Returns generated response	Creates and stores a resource
Responses	Same request = same response	Depends on prior interactions
Use case	Snapshot tests, UI development	Integration tests, CRUD workflows

Seeding with AI agents

Populating a stateful mock server with realistic test data can be tedious — reading schemas, constructing valid request bodies, maintaining dependency order between parent and child resources. Mimikos provides an AI agent skill that automates this.

The mimikos-seed skill teaches AI coding assistants (Claude Code, Cursor, and similar tools) to read your OpenAPI spec, construct valid requests, and populate a running Mimikos instance — turning a manual multi-step process into a single command.

The skill uses MCP tool calls as its primary transport — the agent calls manage_state(action: "create", ...) directly instead of constructing curl commands. If MCP isn’t configured, it falls back to HTTP.

What the skill does:

1. Reads your OpenAPI spec to discover create endpoints and their request schemas
2. Determines dependency order (parent resources before children)
3. Constructs valid JSON request bodies with realistic values
4. Creates resources via manage_state MCP tool calls (or POST requests as fallback)
5. Extracts generated IDs from responses for use in child resources
6. Optionally updates resources with specific values via PATCH/PUT
7. Verifies the seeded state via GET/LIST endpoints

Getting the skill

Download the skill files from the Mimikos repository:

• SKILL.md — main skill instructions (required)
• examples.md — concrete seeding examples (recommended)

Place the skill file in your AI tool’s configuration directory:

Tool	Location
Claude Code	.claude/commands/mimikos-seed.md
Cursor	.cursor/rules/mimikos-seed.mdc

Then ask your agent to “seed the Mimikos server with test data” or “populate the mock API with sample resources.” See the skill’s README for full setup instructions and usage examples.

For MCP server setup, see the MCP Server page.