### Quick Start with Simple Echo Example

Source: https://github.com/vidaiuk/vidaimock/blob/main/examples/README.md

This command demonstrates how to use the simple echo example by sending a POST request to the /examples/echo endpoint.

```bash
curl -X POST http://localhost:3000/examples/echo -d '{"messages": [{"content": "Hello!"}]}'
```

--------------------------------

### Quick Start Docker Compose Setup

Source: https://github.com/vidaiuk/vidaimock/blob/main/docker/README.md

Download the docker-compose.yml file, start the VidaiMock service, and verify its health.

```bash
# 1. Get the compose file (one-time, anywhere you want to run the mock)
curl -O https://raw.githubusercontent.com/vidaiUK/VidaiMock/main/docker/docker-compose.yml

# 2. Run it
docker compose up -d

# 3. Confirm
curl http://localhost:8100/health      # {"status":"ok"}
```

--------------------------------

### Start Vidaimock with Latency

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Example command to start Vidaimock with simulated latency.

```bash
./vidaimock --latency 500 --mode realistic
```

--------------------------------

### Install Dependencies and Serve Documentation

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/README.md

Installs project dependencies and provides commands for live preview or static site building of the MkDocs documentation.

```bash
# one-time (already installed on the maintainer's machine):
python3 -m pip install -r requirements.txt

# live preview at http://127.0.0.1:8001 (auto-reloads on edit):
./serve.sh

# one-shot static build into ./site (gitignored):
./serve.sh build
```

--------------------------------

### Environment Variable Example

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/cli-reference.md

Example of setting the port using an environment variable.

```bash
VIDAIMOCK_PORT=3000
```

--------------------------------

### Install VidaiMock with Docker Compose

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/installation.md

Recommended method for installation using Docker Compose. Downloads the compose file, starts the service, and verifies health.

```bash
curl -O https://raw.githubusercontent.com/vidaiUK/VidaiMock/main/docker/docker-compose.yml
docker compose up -d
curl http://localhost:8100/health    # {"status":"ok"}
```

--------------------------------

### CLI Flag Example

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/cli-reference.md

Example of setting the port using a CLI flag.

```bash
./vidaimock --port 3000
```

--------------------------------

### Start VidaiMock with Static Binary and Run Tests

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/recipes/ci-cd.md

This snippet demonstrates running VidaiMock using its static binary, suitable for environments where Docker is not available. It includes starting the binary, waiting for liveness, running tests, and tearing down.

```bash
# 1. Start the mock in the background
./vidaimock --port 8100 &
MOCK_PID=$!

# 2. Wait for liveness
until curl -sf http://localhost:8100/health >/dev/null; do sleep 0.1; done

# 3. Run tests as above
pytest

# 4. Tear down
kill $MOCK_PID
```

--------------------------------

### Vidaimock Configuration File Example

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/cli-reference.md

An example TOML configuration file for vidaimock, demonstrating settings for host, port, logging, latency, and chaos injection.

```toml
host = "0.0.0.0"
port = 8100
log_level = "info"

[latency]
mode = "realistic"   # token-by-token pacing
base_ms = 150        # TTFT before first token
jitter_pct = 0.2     # ±20% timing variance

[chaos]
enabled = false
drop_pct = 0.01        # 1% of requests fail (provider-shaped 500)
malformed_pct = 0.005  # 0.5% return deliberately broken JSON
trickle_ms = 0         # per-chunk delay during streaming
disconnect_pct = 0.05  # 5% of streams sever mid-generation
```

--------------------------------

### Start VidaiMock with Docker and Run Tests

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/recipes/ci-cd.md

This snippet shows the recommended Docker-based approach for running VidaiMock in CI. It includes starting the mock, waiting for it to be ready, configuring the environment, running tests, and tearing down the mock.

```bash
# 1. Start the mock in the background, pinned by digest
docker run -d --name vidaimock -p 8100:8100 \
  ghcr.io/vidaiuk/vidaimock:latest@sha256:<pin-to-digest>

# 2. Wait for liveness
until curl -sf http://localhost:8100/health >/dev/null; do sleep 0.1; done

# 3. Point your app's provider base URL at the mock
export OPENAI_BASE_URL=http://localhost:8100/v1
export ANTHROPIC_BASE_URL=http://localhost:8100

# 4. Run your test suite
pytest

# 5. Tear down
docker rm -f vidaimock
```

--------------------------------

### Start VidaiMock with Latency and Realistic Mode

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/quickstart.md

Starts VidaiMock with a specified latency and enables realistic mode for more accurate simulation.

```bash
# realistic mode adds TTFT + token pacing
./vidaimock --latency 500 --mode realistic
```

--------------------------------

### Example: OpenAI Chat Completion

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Make a request to the chat completions endpoint to get a response from a model like GPT-4. Ensure the mock is running on port 8100.

```bash
# OpenAI chat completion
curl http://localhost:8100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [{"role": "user", "content": "Hi"}]}'
```

--------------------------------

### Start VidaiMock Server

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/quickstart.md

Launch the VidaiMock server. It listens on http://localhost:8100 by default. No API key is required.

```bash
./vidaimock          # listens on http://localhost:8100 by default
```

--------------------------------

### Download and Run VidaiMock on Linux (x64)

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/installation.md

Installs VidaiMock by downloading and extracting a prebuilt binary for Linux on x64 architecture.

```bash
curl -LO https://github.com/vidaiUK/VidaiMock/releases/latest/download/vidaimock-linux-x64.tar.gz
tar -xzf vidaimock-linux-x64.tar.gz && cd vidaimock
./vidaimock
```

--------------------------------

### Example: Reasoning Models with Usage Reporting

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Use reasoning models and observe the 'reasoning_tokens' field in the usage report. This is useful for analyzing model performance.

```bash
# Reasoning models — returns reasoning_tokens in usage
curl http://localhost:8100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "o4-mini", "messages": [{"role": "user", "content": "2+2"}]}'
```

--------------------------------

### Reasoning Model Request

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/quickstart.md

Example request to a reasoning model (e.g., o4-mini) that returns token accounting.

```bash
curl http://localhost:8100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "o4-mini", "messages": [{"role": "user", "content": "2+2"}]}'
```

--------------------------------

### Gemini Embed Content

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Example for embedding content with Gemini.

```bash
curl http://localhost:8100/v1beta/models/gemini-embedding-001:embedContent \
  -H "Content-Type: application/json" -d '{"content": {"parts": [{"text": "Hello"}]}}'
```

--------------------------------

### Download and Run VidaiMock on Linux (ARM64)

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/installation.md

Installs VidaiMock by downloading and extracting a prebuilt binary for Linux on ARM64 architecture.

```bash
curl -LO https://github.com/vidaiUK/VidaiMock/releases/latest/download/vidaimock-linux-arm64.tar.gz
tar -xzf vidaimock-linux-arm64.tar.gz && cd vidaimock
./vidaimock
```

--------------------------------

### Example: Tool Calling with OpenAI API

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Demonstrates how to use the tool calling feature by providing tool definitions in the request. The mock will auto-detect and respond with tool_calls.

```bash
# Tool calling — auto-detects tools and returns tool_calls response
curl http://localhost:8100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Weather?"}], "tools": [{"type": "function", "function": {"name": "get_weather", "parameters": {}}}]}'
```

--------------------------------

### Running Vidaimock and Testing Template

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/configuration/templates.md

Bash commands to start the Vidaimock server with a custom configuration directory and then test the configured provider with a curl request.

```bash
./vidaimock --config-dir ./my-config &
curl http://localhost:8100/acme/generate -H 'Content-Type: application/json' \
  -d '{"model":"acme-1","input":"hello"}'
```

--------------------------------

### Gemini Count Tokens

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Example for counting tokens with Gemini.

```bash
curl http://localhost:8100/v1beta/models/gemini-2.5-flash:countTokens \
  -H "Content-Type: application/json" -d '{"contents": [{"role": "user", "parts": [{"text": "Hello"}]}]}'
```

--------------------------------

### Chaos Mode with URL Query

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Example using a URL query parameter to simulate chaos status.

```bash
curl "http://localhost:8100/v1/chat/completions?chaos_status=503" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [{"role": "user", "content": "Hi"}]}'
```

--------------------------------

### Example: OpenAI Responses API (Streaming)

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Initiate a streaming request to the OpenAI Responses API for real-time, chunked responses. Use the '-N' flag for unbuffered output.

```bash
# OpenAI Responses API (streaming with typed SSE events)
curl -N http://localhost:8100/v1/responses \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "input": "Say hello", "stream": true}'
```

--------------------------------

### Download and Run VidaiMock on Windows (x64)

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/installation.md

Installs VidaiMock by downloading and extracting a prebuilt zip archive for Windows on x64 architecture.

```powershell
Invoke-WebRequest -Uri https://github.com/vidaiUK/VidaiMock/releases/latest/download/vidaimock-windows-x64.zip -OutFile vidaimock-windows-x64.zip
Expand-Archive vidaimock-windows-x64.zip -DestinationPath .
cd vidaimock
.\vidaimock.exe
```

--------------------------------

### Gemini - Other Endpoints

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/quickstart.md

Examples for Gemini embedContent, countTokens, and model listing.

```bash
# embedContent / countTokens / model listing
curl http://localhost:8100/v1beta/models/gemini-embedding-001:embedContent \
  -H "Content-Type: application/json" -d '{"content": {"parts": [{"text": "Hello"}]}}'
curl http://localhost:8100/v1beta/models/gemini-2.5-flash:countTokens \
  -H "Content-Type: application/json" -d '{"contents": [{"role": "user", "parts": [{"text": "Hello"}]}]}'
curl http://localhost:8100/v1beta/models
```

--------------------------------

### Download and Run VidaiMock on macOS (Intel)

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/installation.md

Installs VidaiMock by downloading and extracting a prebuilt binary for macOS on Intel processors.

```bash
curl -LO https://github.com/vidaiUK/VidaiMock/releases/latest/download/vidaimock-macos-x64.tar.gz
tar -xzf vidaimock-macos-x64.tar.gz && cd vidaimock
./vidaimock
```

--------------------------------

### Agentic Tool Loop Simulation

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Example simulating an agentic tool loop by sending a tool result back.

```bash
curl http://localhost:8100/v1/chat/completions \
  -H "Content-Type: application/json" -d '{
    "model": "gpt-4o",
    "tools": [{"type": "function", "function": {"name": "get_weather", "parameters": {}}}],
    "messages": [
      {"role": "user", "content": "Weather in London?"},
      {"role": "assistant", "tool_calls": [{"id":"c1","type":"function","function":{"name":"get_weather","arguments":"{}"}}}},
      {"role": "tool", "tool_call_id": "c1", "content": "15°C cloudy"}
    ]
  }'
```

--------------------------------

### Download and Run VidaiMock on macOS (Apple Silicon)

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/installation.md

Installs VidaiMock by downloading and extracting a prebuilt binary for macOS on Apple Silicon.

```bash
curl -LO https://github.com/vidaiUK/VidaiMock/releases/latest/download/vidaimock-macos-arm64.tar.gz
tar -xzf vidaimock-macos-arm64.tar.gz && cd vidaimock
./vidaimock
```

--------------------------------

### Agentic Workflow Testing with OpenAI

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Demonstrates a full OpenAI round trip for agentic workflow testing using VidaiMock. This example requires no API key and incurs no cost. The first turn shows the mock returning a tool_call, and the second turn shows it returning plain-text synthesis after a tool result is provided in the history.

```bash
# Turn 1: user asks a question; mock returns a tool_call (because tools are defined).
curl -s http://localhost:8100/v1/chat/completions -H 'Content-Type: application/json' \
  -d '{"model":"gpt-4o","tools":[{"type":"function","function":{"name":"get_weather","parameters":{}}}]},
       "messages":[{"role":"user","content":"Weather in London?"}]}'
# -> finish_reason: "tool_calls", message.tool_calls: [...]
```

```bash
# Turn 2: same tools, now with a role:tool result in history.
# Mock detects the tool result, returns plain-text synthesis instead of looping.
curl -s http://localhost:8100/v1/chat/completions -H 'Content-Type: application/json' \
  -d '{"model":"gpt-4o","tools":[{"type":"function","function":{"name":"get_weather","parameters":{}}}]},
       "messages":[
         {"role":"user","content":"Weather in London?"},
         {"role":"assistant","tool_calls":[{"id":"c1","type":"function","function":{"name":"get_weather","arguments":"{}"}}}},
         {"role":"tool","tool_call_id":"c1","content":"15°C cloudy"}
       ]}'
# -> finish_reason: "stop", message.content: "Based on the tool results..."
```

--------------------------------

### Using a CSV Template with Vidaimock

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/reference/templates-catalogue.md

Demonstrates how to copy a CSV template, configure a provider to use it, and start Vidaimock to serve CSV data. This is useful for testing RAG ingestion with CSV files.

```bash
mkdir -p my-config/templates my-config/providers
cp examples/templates/16_data.csv.j2 my-config/templates/
cat > my-config/providers/csv.yaml <<'EOF'
name: "csv-export"
matcher: "^/export/data$"
response_template: "16_data.csv.j2"
EOF

./vidaimock --config-dir ./my-config --content-type text/csv &
curl http://localhost:8100/export/data
```

--------------------------------

### Latency and Chaos - Realistic Mode

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/quickstart.md

Start the server in realistic mode to add latency (TTFT and token pacing).

```APIDOC
## Server Start with Latency

### Description
Start the VidaiMock server with realistic latency simulation, which adds Time To First Byte (TTFT) and token pacing.

### Command
```bash
./vidaimock --latency 500 --mode realistic
```

### Options
- **--latency** (integer) - The base latency in milliseconds to add to requests.
- **--mode** (string) - The simulation mode. Set to `realistic` for TTFT and token pacing.
```

--------------------------------

### Run VidaiMock with Docker Compose

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/index.md

This snippet demonstrates how to set up and run VidaiMock using Docker Compose. It includes fetching the configuration, starting the service, and making a sample request to the chat completions endpoint.

```bash
curl -O https://raw.githubusercontent.com/vidaiUK/VidaiMock/main/docker/docker-compose.yml
docker compose up -d

# No API key needed — VidaiMock ignores Authorization on mock routes.
curl -N http://localhost:8100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "stream": true, "messages": [{"role": "user", "content": "Hello!"}]}'
```

--------------------------------

### Gemini Tool Calling

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Example of Gemini tool calling, which returns a functionCall.

```bash
curl http://localhost:8100/v1beta/models/gemini-2.5-flash:generateContent \
  -H "Content-Type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "Weather?"}]}], "tools": [{"functionDeclarations": [{"name": "get_weather", "parameters": {"type": "OBJECT", "properties": {"city": {"type": "STRING"}}}}}]}'
```

--------------------------------

### Example: Streaming Chat Completions with Usage Reporting

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Request streaming chat completions and include usage statistics in the stream. This allows monitoring token usage during a conversation.

```bash
# Streaming with usage reporting
curl -N http://localhost:8100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "stream": true, "stream_options": {"include_usage": true}, "messages": [{"role": "user", "content": "Hi"}]}'
```

--------------------------------

### Anthropic Tool Calling

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Example of Anthropic tool calling, which returns a tool_use block.

```bash
curl http://localhost:8100/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-haiku-4-5-20251001", "max_tokens": 500, "messages": [{"role": "user", "content": "Weather in London?"}], "tools": [{"name": "get_weather", "description": "Get weather", "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}}}]}'
```

--------------------------------

### GitHub Actions Workflow for VidaiMock (Static Binary)

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/recipes/ci-cd.md

A GitHub Actions workflow sketch for integrating VidaiMock using its static binary. It shows downloading the binary, starting it, and running tests.

```yaml
- name: Start VidaiMock
  run: |
    curl -LO https://github.com/vidaiUK/VidaiMock/releases/latest/download/vidaimock-linux-x64.tar.gz
    tar -xzf vidaimock-linux-x64.tar.gz
    ./vidaimock/vidaimock --port 8100 &
    until curl -sf http://localhost:8100/health; do sleep 0.1; done

- name: Run tests
  env:
    OPENAI_BASE_URL: http://localhost:8100/v1
  run: pytest -q
```

--------------------------------

### Install VidaiMock with Docker One-liner

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/installation.md

Quick evaluation using a single Docker run command. This method is for temporary use and does not support overrides or isolated mode.

```bash
docker run --rm -p 8100:8100 ghcr.io/vidaiuk/vidaimock:latest
```

--------------------------------

### SOAP/XML Content Type Example

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/recipes/cookbook.md

Mock legacy enterprise systems by serving responses in SOAP/XML format. This template demonstrates a basic SOAP envelope structure with dynamic ID generation.

```jinja2
<?xml version="1.0"?>
<soap:Envelope>
  <soap:Body>
    <Response><Id>{{ uuid() }}</Id><Status>OK</Status></Response>
  </soap:Body>
</soap:Envelope>
```

--------------------------------

### CSV Content Type Example

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/recipes/cookbook.md

Serve data in CSV format, useful for testing RAG ingestion or data processing pipelines. Includes dynamic generation of IDs and timestamps.

```jinja2
id,name,role,created_at
{{ uuid() }},Alice,Admin,{{ iso_timestamp() }}
{{ uuid() }},Bob,User,{{ iso_timestamp() }}
```

--------------------------------

### GitHub Actions Workflow for VidaiMock (Docker)

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/recipes/ci-cd.md

A GitHub Actions workflow sketch demonstrating how to integrate VidaiMock using Docker. It covers starting the mock, running tests with environment variables set, and stopping the mock.

```yaml
- name: Start VidaiMock
  run: |
    docker run -d --name vidaimock -p 8100:8100 \
      ghcr.io/vidaiuk/vidaimock:latest@sha256:<pin-to-digest>
    until curl -sf http://localhost:8100/health >/dev/null; do sleep 0.1; done

- name: Run tests
  env:
    OPENAI_BASE_URL: http://localhost:8100/v1
    ANTHROPIC_BASE_URL: http://localhost:8100
  run: pytest -q

- name: Stop mock
  if: always()
  run: docker rm -f vidaimock
```

--------------------------------

### Docker Compose Setup and Usage

Source: https://github.com/vidaiuk/vidaimock/blob/main/CHANGELOG.md

Use Docker Compose for setting up VidaiMock, with an option to mount local overrides for customization. The `VIDAIMOCK_ISOLATED` environment variable can be used to restrict the surface area.

```bash
curl -O https://raw.githubusercontent.com/vidaiuk/vidaimock/main/docker/docker-compose.yml \
  && docker compose up
```

--------------------------------

### VidaiMock Project Structure

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/reference/architecture.md

Outlines the directory layout of the VidaiMock project, including source code, configuration files, and examples.

```text
src/
  main.rs        # startup, config load, server boot
  server.rs      # Axum router, middleware, route registration
  handlers.rs    # request handlers, status resolution, streaming engine
  provider.rs    # registry, Tera setup, helper functions
  replacer.rs    # Tera context construction
  aws_event_stream.rs  # Bedrock binary event-stream encoding
config/
  providers/     # bundled provider YAMLs (embedded at compile time)
  templates/     # bundled Tera templates (embedded at compile time)
examples/        # 20+ advanced example templates (shipped in releases)
```

--------------------------------

### Configure VidaiMock with a Custom Configuration Directory

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/recipes/ci-cd.md

This command starts VidaiMock with a custom configuration directory, allowing you to override bundled defaults and provide specific test fixtures.

```bash
./vidaimock --config-dir ./tests/mock-fixtures --port 8100 &
```

--------------------------------

### OpenAI Tool Call Request

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/tool-calling.md

Example cURL request to trigger a tool call for OpenAI. Ensure the tool name matches your declaration.

```bash
curl http://localhost:8100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o",
       "messages": [{"role": "user", "content": "Weather?"}],
       "tools": [{"type": "function",
                  "function": {"name": "get_weather", "parameters": {}}}]}'
```

--------------------------------

### VidaiMock Provider Configuration Example

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

This YAML defines a provider with regex path matching, response and error templates, status code, and streaming configuration. It demonstrates how to configure endpoint matching and response generation.

```yaml
name: "my-provider"
matcher: "^/v1/my/endpoint$"         # Regex path match
response_template: "my/template.j2"  # Tera template path (HTTP 2xx responses)
error_template: "my/error.j2"        # Tera template path (HTTP 4xx / 5xx responses)
status_code: "200"                   # HTTP status — static or Tera expression
priority: 10                         # Higher matches first
stream:
  enabled: true
  frame_format: raw                  # "raw" = template controls SSE framing
  lifecycle:
    on_start:
      template_path: "my/stream_start.j2"
    on_chunk:
      template_path: "my/stream_delta.j2"
    on_stop:
      template_path: "my/stream_stop.j2"
```

--------------------------------

### Pin VidaiMock Version with Docker Compose

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/recipes/docker-compose.md

Set the VIDAIMOCK_VERSION environment variable in a .env file to a specific version tag and then start the service.

```bash
echo "VIDAIMOCK_VERSION=0.2.9" > .env
docker compose up -d
```

--------------------------------

### OpenAI Tool Call Response

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/tool-calling.md

Example JSON response from VidaiMock for an OpenAI tool call. It includes the tool ID, type, name, and arguments.

```json
{"choices":[{"message":{"role":"assistant","content":null,
  "tool_calls":[{"id":"call_mock_...","type":"function",
    "function":{"name":"get_weather","arguments":"{}"}}]}},
  "finish_reason":"tool_calls"}]}
```

--------------------------------

### Streaming Template with Raw Frame Format

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/configuration/templates.md

An example of an 'on_stop' streaming template using 'raw' frame format to emit multiple Server-Sent Events (SSE), including a finish chunk, an optional usage chunk, and a final '[DONE]' marker.

```jinja2
data: {"choices":[{"delta":{},"finish_reason":"stop"}]}

{% if json.stream_options.include_usage %}
data: {"choices":[],"usage":{"total_tokens":42}}

{% endif %}
data: [DONE]
```

--------------------------------

### Custom Template Logic for Agentic Loops

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/agentic-testing.md

Example Jinja2 template logic demonstrating how to use the `has_tool_result` helper to control the agent's response based on the presence of tool results in the message history.

```jinja2
{% if json.tools and has_tool_result(messages=json.messages, provider="openai") %}
  {# loop-terminating: emit plain text #}
{% elif json.tools %}
  {# emit a tool call #}
{% else %}
  {# default text #}
{% endif %}
```

--------------------------------

### Moderations Request

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/providers/openai.md

Example of a curl request to the moderations endpoint.

```bash
curl http://localhost:8100/v1/moderations -H "Content-Type: application/json" \
  -d '{"model": "omni-moderation-latest", "input": "Hello"}'
```

--------------------------------

### Embeddings Request

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/providers/openai.md

Example of a curl request to the embeddings endpoint.

```bash
curl http://localhost:8100/v1/embeddings -H "Content-Type: application/json" \
  -d '{"model": "text-embedding-3-small", "input": "Hello"}'
```

--------------------------------

### Anthropic Messages API

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Example for interacting with the Anthropic Messages API.

```bash
curl http://localhost:8100/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-haiku-4-5-20251001", "max_tokens": 200, "messages": [{"role": "user", "content": "Hi"}]}'
```

--------------------------------

### Build VidaiMock from Source

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Clone the repository, build the release binary using Cargo, and then run the executable. This is for development or custom builds.

```bash
git clone https://github.com/vidaiUK/VidaiMock.git
cd VidaiMock && cargo build --release
./target/release/vidaimock
```

--------------------------------

### Health Check Endpoint

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/cli-reference.md

Example of the response from the /health built-in path.

```json
{"status":"ok"}
```

--------------------------------

### Image Generation Request

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/providers/openai.md

Example of a curl request to the image generation endpoint.

```bash
curl http://localhost:8100/v1/images/generations -H "Content-Type: application/json" \
  -d '{"model": "dall-e-2", "prompt": "a red circle", "n": 1}'
```

--------------------------------

### OpenAI Responses API (non-streaming)

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/quickstart.md

Get a non-streaming response from the Responses API.

```APIDOC
## POST /v1/responses (non-streaming)

### Description
Get a non-streaming response from the Responses API.

### Method
POST

### Endpoint
/v1/responses

### Request Body
- **model** (string) - Required - The model to use.
- **input** (string) - Required - The input prompt.
- **max_output_tokens** (integer) - Optional - The maximum number of output tokens.

### Request Example
```json
{
  "model": "gpt-4o-mini",
  "input": "Say hello",
  "max_output_tokens": 50
}
```

### Response
#### Success Response (200)
- **output** (string) - The generated response.

#### Response Example
```json
{
  "output": "Hello there!"
}
```
```

--------------------------------

### Download and Extract VidaiMock Binary for Linux (x64)

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Download the binary for Linux on x64 architecture, extract it, and navigate to the created directory. This is for direct execution.

```bash
# Linux x64
curl -LO https://github.com/vidaiUK/VidaiMock/releases/latest/download/vidaimock-linux-x64.tar.gz
tar -xzf vidaimock-linux-x64.tar.gz && cd vidaimock
```

--------------------------------

### Responses API Request (Non-streaming)

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/providers/openai.md

Example of a non-streaming curl request to the Responses API.

```bash
curl http://localhost:8100/v1/responses -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "input": "Say hello", "max_output_tokens": 50}'
```

--------------------------------

### Chat Completions Request

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/providers/openai.md

Example of a basic curl request to the chat completions endpoint.

```bash
curl http://localhost:8100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [{"role": "user", "content": "Hi"}]}'
```

--------------------------------

### Download and Extract VidaiMock Binary for Linux (ARM64)

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Download the binary for Linux on ARM64 architecture, extract it, and navigate to the created directory. This is for direct execution.

```bash
# Linux ARM64
curl -LO https://github.com/vidaiUK/VidaiMock/releases/latest/download/vidaimock-linux-arm64.tar.gz
tar -xzf vidaimock-linux-arm64.tar.gz && cd vidaimock
```

--------------------------------

### Reasoning models

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/quickstart.md

Use models matching 'o1'/'o3'/'o4' to get reasoning token accounting.

```APIDOC
## POST /v1/chat/completions (reasoning models)

### Description
Use models matching 'o1'/'o3'/'o4' to get reasoning token accounting.

### Method
POST

### Endpoint
/v1/chat/completions

### Request Body
- **model** (string) - Required - The model to use (e.g., "o4-mini").
- **messages** (array) - Required - An array of message objects representing the conversation history.
  - **role** (string) - Required - The role of the message sender.
  - **content** (string) - Required - The content of the message.

### Request Example
```json
{
  "model": "o4-mini",
  "messages": [{"role": "user", "content": "2+2"}]
}
```

### Response
#### Success Response (200)
- **choices** (array) - An array of chat completion choices.
  - **message** (object) - The message content and role.
    - **role** (string) - The role of the message sender.
    - **content** (string) - The content of the message.
  - **usage** (object) - Token usage information.
    - **prompt_tokens** (integer) - The number of prompt tokens.
    - **completion_tokens** (integer) - The number of completion tokens.
    - **total_tokens** (integer) - The total number of tokens.

#### Response Example
```json
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "4"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 1,
    "total_tokens": 11
  }
}
```
```

--------------------------------

### Anthropic Streaming Messages

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Example for streaming messages from the Anthropic API, including all event types.

```bash
curl -N http://localhost:8100/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-haiku-4-5-20251001", "max_tokens": 200, "stream": true, "messages": [{"role": "user", "content": "Count to 5"}]}'
```

--------------------------------

### Verify Loaded Providers and Templates

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/configuration/overriding.md

Access the /status endpoint and use jq to inspect the loaded providers and templates, confirming the runtime mode and configuration.

```bash
curl -s http://localhost:8100/status | jq .
```

--------------------------------

### Download and Extract VidaiMock Binary for Windows (x64)

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Download the zip archive for Windows x64, extract it, and navigate to the created directory. This is for direct execution.

```powershell
# Windows x64 (PowerShell)
Invoke-WebRequest -Uri https://github.com/vidaiUK/VidaiMock/releases/latest/download/vidaimock-windows-x64.zip -OutFile vidaimock-windows-x64.zip
Expand-Archive vidaimock-windows-x64.zip -DestinationPath .
cd vidaimock

./vidaimock
```

--------------------------------

### VidaiMock Initial Release Configuration

Source: https://github.com/vidaiuk/vidaimock/blob/main/CHANGELOG.md

Configure VidaiMock with custom response files using the `--response-file` flag.

```bash
vidaimock --response-file ./my-custom-response.json
```

--------------------------------

### Streaming Chat Completions Request

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/providers/openai.md

Example of a curl request for streaming chat completions, including usage information.

```bash
curl -N http://localhost:8100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "stream": true,
       "stream_options": {"include_usage": true},
       "messages": [{"role": "user", "content": "Hi"}]}'
```

--------------------------------

### OpenAI Responses API (streaming)

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/quickstart.md

Get a streaming response from the Responses API using Server-Sent Events (SSE).

```APIDOC
## POST /v1/responses (streaming)

### Description
Get a streaming response from the Responses API using Server-Sent Events (SSE). The response will contain typed SSE events like `response.output_text.delta`.

### Method
POST

### Endpoint
/v1/responses

### Request Body
- **model** (string) - Required - The model to use.
- **input** (string) - Required - The input prompt.
- **stream** (boolean) - Required - Set to `true` to enable streaming.
- **max_output_tokens** (integer) - Optional - The maximum number of output tokens.

### Request Example
```json
{
  "model": "gpt-4o-mini",
  "input": "Say hello",
  "stream": true
}
```

### Response
#### Success Response (200)
- Server-Sent Events (SSE) stream containing response deltas.

#### Response Example (SSE format)
```
data: {"output_text": {"delta": "Hello"}}

data: {"output_text": {"delta": " "}}

data: {"output_text": {"delta": "there!"}}

data: [DONE]
```
```

--------------------------------

### Force Chaos Drop Error

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Example to force packet drops for chaos error testing using X-Vidai-Chaos-Drop header.

```bash
curl -H "X-Vidai-Chaos-Drop: 100" http://localhost:8100/v1/chat/completions \
  -H "Content-Type: application/json" -d '{"model": "gpt-4", "messages": [{"role": "user", "content": "Hi"}]}'
```

--------------------------------

### Responses API Request (Streaming)

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/providers/openai.md

Example of a streaming curl request to the Responses API, producing typed SSE events.

```bash
curl -N http://localhost:8100/v1/responses -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "input": "Say hello", "stream": true}'
```

--------------------------------

### Download and Extract VidaiMock Binary for macOS (Intel)

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Download the binary for macOS on Intel processors, extract it, and navigate to the created directory. This is for direct execution.

```bash
# macOS Intel
curl -LO https://github.com/vidaiUK/VidaiMock/releases/latest/download/vidaimock-macos-x64.tar.gz
tar -xzf vidaimock-macos-x64.tar.gz && cd vidaimock
```

--------------------------------

### VidaiMock Smoke Check

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/installation.md

Performs a basic verification of the VidaiMock installation by checking its version and making a health check request.

```bash
./vidaimock --version
curl -s http://localhost:8100/health      # {"status":"ok"} once running
```

--------------------------------

### Anthropic Tool Call Request

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/tool-calling.md

Example cURL request for Anthropic to invoke a tool. The response will contain a 'tool_use' content block.

```bash
curl http://localhost:8100/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"model": "claude", "max_tokens": 200,
       "messages": [{"role": "user", "content": "Weather?"}],
       "tools": [{"name": "get_weather", "description": "x",
                  "input_schema": {"type": "object"}}]}'
```

--------------------------------

### Download and Extract VidaiMock Binary for macOS (Apple Silicon)

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

Download the binary for macOS on Apple Silicon, extract it, and navigate to the created directory. This is for direct execution.

```bash
# macOS Apple Silicon
curl -LO https://github.com/vidaiUK/VidaiMock/releases/latest/download/vidaimock-macos-arm64.tar.gz
tar -xzf vidaimock-macos-arm64.tar.gz && cd vidaimock
```

--------------------------------

### Run VidaiMock with Binary (macOS Apple Silicon)

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/index.md

This snippet shows how to download, extract, and run the VidaiMock binary directly on macOS Apple Silicon. It also includes a sample curl command to test the chat completions endpoint.

```bash
curl -LO https://github.com/vidaiUK/VidaiMock/releases/latest/download/vidaimock-macos-arm64.tar.gz
tar -xzf vidaimock-macos-arm64.tar.gz && cd vidaimock
./vidaimock

# In another terminal — note: no API key needed
curl -N http://localhost:8100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "stream": true, "messages": [{"role": "user", "content": "Hello!"}]}'
```

--------------------------------

### Configure Fallback Endpoints for Resilience Testing

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/recipes/ci-cd.md

Demonstrates how to configure primary and fallback endpoints to test retry and circuit-breaker logic. This involves setting up a primary endpoint and a fallback endpoint that can be configured to fail.

```text
primary  endpoint: http://localhost:8100/v1?chaos_status=500
fallback endpoint: http://localhost:8100/v1
```

--------------------------------

### Clone VidaiMock Repository

Source: https://github.com/vidaiuk/vidaimock/blob/main/CONTRIBUTING.md

Clone the VidaiMock repository and navigate into the project directory. This is the initial step for setting up your development environment.

```bash
git clone https://github.com/vidaiUK/VidaiMock.git
cd vidaimock
```

--------------------------------

### Probabilistic Request Failure Injection

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/quickstart.md

Injects probabilistic failures (100% chance in this example) into requests, returning provider-shaped 500 JSON errors.

```bash
# probabilistic failure injection per request (returns provider-shaped 500 JSON)
curl -H "X-Vidai-Chaos-Drop: 100" http://localhost:8100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [{"role": "user", "content": "Hi"}]}'
```

--------------------------------

### Gemini Tool Call Request

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/tool-calling.md

Example cURL request for Gemini to generate content with a tool declaration. The response will include a functionCall part.

```bash
curl http://localhost:8100/v1beta/models/gemini-2.5-flash:generateContent \
  -H "Content-Type: application/json" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "Weather?"}]}],
       "tools": [{"functionDeclarations": [{"name": "get_weather",
                  "parameters": {"type": "OBJECT"}}]}]}'
```

--------------------------------

### Run VidaiMock with Docker Compose

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

This snippet shows how to set up and run VidaiMock using Docker Compose. It includes testing the chat completions endpoint with streaming enabled.

```bash
curl -O https://raw.githubusercontent.com/vidaiUK/VidaiMock/main/docker/docker-compose.yml
docker compose up -d

# Test it!
curl -N http://localhost:8100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "stream": true, "messages": [{"role": "user", "content": "Hello!"}]}'
```

--------------------------------

### Add New Endpoint

Source: https://github.com/vidaiuk/vidaimock/blob/main/README.md

To introduce a new endpoint, add any YAML file to the 'providers/' directory. Ensure it has a unique 'matcher' field. Providers with higher 'priority' values will be matched before those with lower values.

```yaml
providers/
```

--------------------------------

### List Models with Gemini

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/providers/gemini.md

Use this command to retrieve a list of available models from the Gemini API.

```bash
curl http://localhost:8100/v1beta/models
```

--------------------------------

### Verifying VidaiMock Docker Image Signatures

Source: https://github.com/vidaiuk/vidaimock/blob/main/CHANGELOG.md

Verify the cosign signatures for VidaiMock Docker images using the Vidai release key.

```bash
cosign verify --key https://vidai.uk/.well-known/cosign.pub ghcr.io/vidaiuk/vidaimock:0.2.8
```

--------------------------------

### Build VidaiMock from Source

Source: https://github.com/vidaiuk/vidaimock/blob/main/mkdocs/docs/getting-started/installation.md

Builds VidaiMock from source using Cargo, requiring a recent Rust toolchain. The compiled binary includes embedded configuration.

```bash
git clone https://github.com/vidaiUK/VidaiMock.git
cd VidaiMock
cargo build --release
./target/release/vidaimock
```