The .bru Format

Every request in Vegha is stored as a single .bru file. The format is plain text, human-readable, and designed to be reviewed and diffed in version control.

Why plain text

A .bru file is just text, so it works naturally with git. When you change a header or a body field, the diff shows exactly what changed — one line, in context — instead of an opaque blob. This makes pull request review meaningful and merge conflicts tractable. One request per file also means two people editing different requests never conflict.

Anatomy of a file

A .bru file is made of named blocks. Each block describes one aspect of the request: its metadata, the verb and URL, headers, body, authorization, variables, assertions, tests, and documentation.

A GET request

meta {
  name: Get user
  type: http
  seq: 1
}

get {
  url: {{baseUrl}}/users/42
  auth: bearer
}

headers {
  Accept: application/json
}

auth:bearer {
  token: {{authToken}}
}

assert {
  res.status: eq 200
}

A POST request

meta {
  name: Create user
  type: http
  seq: 2
}

post {
  url: {{baseUrl}}/users
  body: json
  auth: none
}

headers {
  Content-Type: application/json
}

body:json {
  {
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  }
}

vars:pre-request {
  requestId: {{$guid}}
}

tests {
  test("status is 201", function () {
    expect(res.status).to.equal(201);
  });
}

docs {
  Creates a new user record and returns the created resource.
}

Common blocks

Block	Purpose
`meta`	Name, request type, and sequence order.
`get` / `post` / `put` / …	The HTTP verb, URL, and which body and auth modes are active.
`headers`	Request headers as key/value pairs.
`body:json` / `body:xml` / `body:form-urlencoded`	The request body, typed by block name.
`auth:bearer` / `auth:basic` / …	Authorization details for the selected method.
`vars`	Pre-request and post-response variables.
`assert`	Declarative response assertions.
`tests`	Scripted test cases.
`docs`	Free-form Markdown documentation.

Environments are .bru files too

Environments use the same format. Each environment is a .bru file holding variable definitions, so your environment configuration is just as diffable and reviewable as your requests. See Environments for details.