Skip to content

Provider Config Reference

A provider is a YAML file in config/providers/. It maps an incoming request path to a response template and controls status, errors, and streaming. The bundled providers are embedded in the binary; you override or extend them via --config-dir (Overriding bundled defaults).

Schema

name: "my-provider"                  # unique identifier
matcher: "^/v1/my/endpoint$"         # regex matched against the request path
response_template: "my/template.j2"  # Tera template for 2xx responses
error_template: "my/error.j2"        # Tera template for 4xx/5xx responses
status_code: "200"                   # static, or a Tera expression
priority: 10                         # higher wins when multiple matchers hit
response_headers:                    # extra headers; values are Tera templates
  x-request-id: "req_{{ uuid }}"
  retry-after: "{% if status_code == 429 %}2{% endif %}"   # empty -> not sent

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" }

Fields

matcher

A regex tested against the request path. The first provider (by priority, then load order) whose matcher hits serves the request.

priority

Integer, default 0. Higher matches first. Use this to make a specific provider win over a broad catch-all.

response_template

Path (relative to config/templates/) of the Tera template rendered for successful (2xx) responses. See Templating.

error_template

Rendered instead of response_template whenever the resolved HTTP status is ≥ 400 — whether the status came from chaos injection, X-Mock-Status, ?chaos_status=, or a status_code expression. This is how every failure path produces a provider-shaped error envelope. The template has a status_code variable in scope so it can self-describe per status.

status_code

Controls the HTTP status. Accepts:

  • A static string — "400".
  • A Tera expression — "{{ path_segments | last }}".
  • A Tera statement — "{% if json.max_tokens %}200{% else %}400{% endif %}".

Both {{ … }} and {% … %} forms are rendered. This is how the bundled Anthropic provider enforces the max_tokens requirement.

response_headers

Extra headers on every response from this provider: normal, streaming and error. Each value is a Tera template rendered with the request context plus status_code, so headers can depend on the outcome. A value that renders empty is not sent. A content-type entry overrides the default. The bundled OpenAI and Anthropic providers use this to send request ids, rate-limit headers, and retry-after on 429/503.

methods

HTTP methods the provider answers, e.g. ["GET", "DELETE"]. Default: ["POST"]. Templates can branch on the method variable.

body_encoding

base64: the rendered body is base64 and is decoded before sending, for binary responses such as audio or video. Pair it with a content-type in response_headers.

scenarios

{dir, key}: replay scripted responses from <config-dir>/scenarios/<dir>/, picked by the X-Vidai-Scenario header or the rendered key. See Scenario playback.

Request bodies

Templates see the request body as json. JSON bodies are passed through; multipart/form-data becomes an object of its fields, with file parts as {"filename", "content_type", "size"} (multipart sends numbers as strings, so use | int). An empty or non-JSON body is {}.

stream

Present (and enabled: true) to make the provider stream. lifecycle defines on_start / on_chunk / on_stop templates. frame_format: raw hands full SSE framing to the templates (needed for typed-event providers like the Responses API and Anthropic). See Writing templates and Streaming.

encoding: aws-event-stream sends the binary AWS event stream that Bedrock uses instead of SSE. Templates write events in the same event: / data: form as raw SSE, and one template may emit several events. aws_payload picks the Bedrock flavour:

aws_payload Wire shape Used by
bytes (default) every event is :event-type chunk with payload {"bytes": "<base64 of the data JSON>"}; event: lines are ignored InvokeModelWithResponseStream
json :event-type is the template's event: name; payload is the data JSON as written ConverseStream

Chaos & error injection summary

Trigger Where
?chaos_status=<code> URL query — per-URL, no header forwarding needed
X-Mock-Status: <code> request header — per-request
X-Vidai-Chaos-Drop: <pct> request header — probabilistic
status_code Tera expression provider config — per request field

All route through error_template. Full detail: Chaos & error injection.

mock-server.toml (global)

Provider YAMLs control per-endpoint behaviour. Global runtime settings (host, port, latency, chaos defaults) live in mock-server.toml — see the CLI & headers reference.