Reference

Mock Files (HCL)

Every field accepted in .hcl mock files. For the guided introduction, start at File Mocks.

mock block

mock "METHOD /path/{param}" {
  # fields
}

Methods: GET, POST, PUT, DELETE, PATCH, or * for any method. Path segments in braces ({param}) are parameters exposed as {{request.params.<name>}}.

Field	Type	Default	Description
`status`	number (200 to 599)	`201` for POST, `200` otherwise	Response status. Templates can override it per request with `setStatus`.
`body`	string	empty	Response body, Bigodon template, rendered per request.
`headers`	block	empty	Response headers as `Name = "value"` pairs.
`format`	string	unset	Sets Content-Type from a short name: `json`, `html`, `text`, `xml`, `javascript`, `css`. Mutually exclusive with an explicit Content-Type header.
`delay`	number (0 to 300000)	none	Milliseconds to wait before responding. Applies to proxied responses too.
`enabled`	boolean	`true`	Disable the mock without deleting it.
`name`	string	file path	Label shown in the UI.
`labels`	array of strings	`[]`	Tags for filtering in the UI.
`host`	string	unset	Scope the mock to a host block by slug; it then only matches requests with that host's `Host` header.
`parse`	boolean	`true`	`false` skips request body parsing (the body is streamed raw). Use for large uploads or non-JSON payloads; `request.body` is unavailable in the template.

Multi-line bodies (heredocs)

# Strips leading indentation (preferred)
body = <<-EOF
  { "name": "{{request.params.name}}" }
EOF

# Preserves indentation exactly
body = <<EOF
{ "name": "{{request.params.name}}" }
EOF

In regular quoted strings, escaping literal braces requires a double backslash (\\{{) because HCL consumes one level; in heredocs a single backslash (\{{) is enough.

host block

host "slug" {
  name        = "Billing Service"
  source      = "billing.local"
  destination = "https://demo-billing.mockoapp.net"
}

Field	Required	Description
`source`	yes	Hostname matched against the request's `Host` header.
`destination`	no	`http://` or `https://` URL. When set, unmatched requests on this host proxy there automatically. Also the target of `{{proxy 'slug'}}`.
`name`	no	Label shown in the UI.

The slug (the block's string label) is limited to 12 characters: letters, digits, - and _.

data block

data "settings" {
  base_url = "https://api.example.com"   # flat value

  environment {                          # named sub-block
    name = "staging"
  }
}

Flat values are read directly: {{data.settings.base_url}}.
Named sub-blocks are always arrays, even when defined once: iterate with forEach or index with {{pick (itemAt data.settings.environment 0) 'name'}}.
Data blocks with the same name merge across all loaded files.

Match priority

Exact paths beat parameterized paths (/cats/george beats /cats/{name}).
Specific methods beat the * wildcard.
Deployed (UI-created) mocks beat file mocks on the same method and path.
Within equal specificity, the first declaration in the file wins.
Unmatched requests return 404, unless a proxy target or a host destination applies.

Worked examples are on How Matching Works.

File layout

Every .hcl file under the mocks folder is loaded and merged; nested folders are organizational only.
Hidden files and folders (starting with .) are ignored.
With --watch, changes to any loaded file reload the whole set.