> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usebruno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# YAML Structure Reference

This page documents the structure of OpenCollection YAML files used in Bruno.

## Top-Level Structure

A Bruno YAML request file contains the following top-level sections:

```yaml theme={null}
info:        # Request metadata (name, type, seq, tags)
http:        # HTTP request configuration
runtime:     # Scripts and assertions
settings:    # Request settings
docs:        # Request documentation
```

## info

Store metadata about your request.

```yaml theme={null}
info:
  name: Get Users
  type: http
  seq: 1
  tags:
    - smoke
    - regression
```

| Field | Type | Description |
| - | - | - |
| `name` | string | The display name of the request |
| `type` | string | The request type (`http` for HTTP requests, `folder` for folders) |
| `seq` | number | Sequence number that determines sort position in the UI |
| `tags` | array | Optional tags for filtering requests during collection runs |

## http

The HTTP request configuration.

```yaml theme={null}
http:
  method: post
  url: https://api.example.com/users
  params:
    query: [...]
    path: [...]
  headers: [...]
  body:
    type: json
    data: "..."
  auth:
    type: basic
    basic:
      username: admin
      password: secret
```

### http.method

The HTTP method. Supported values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`, `HEAD`, `TRACE`, `CONNECT` (uppercase).

### http.params

Parameters as an array of objects with a `type` field to distinguish query vs path parameters.

```yaml theme={null}
params:
  - name: filter
    value: active
    type: query
    description: Filter results by status
  - name: limit
    value: "10"
    type: query
    description: Maximum number of results to return
  - name: id
    value: "123"
    type: path
```

| Field | Type | Description |
| - | - | - |
| `name` | string | The parameter name |
| `value` | string | The parameter value |
| `type` | string | Either `query` or `path` |
| `disabled` | boolean | Whether the parameter is disabled (optional) |
| `description` | string | Human-readable description of the parameter's purpose (optional) |

### http.headers

Request headers as an array of objects.

```yaml theme={null}
headers:
  - name: Content-Type
    value: application/json
    description: Tells the server the format of the request body
  - name: Authorization
    value: Bearer {{token}}
    description: Bearer token obtained after login
    disabled: true
```

| Field | Type | Description |
| - | - | - |
| `name` | string | The header name |
| `value` | string | The header value |
| `disabled` | boolean | Whether the header is disabled (optional) |
| `description` | string | Human-readable description of the header's purpose (optional) |

### http.body

The request body configuration.

```yaml theme={null}
body:
  type: json
  data: |-
    {
      "name": "John Doe"
    }
```

| Body Type | Description |
| - | - |
| `json` | JSON body |
| `text` | Plain text body |
| `xml` | XML body |
| `form-urlencoded` | Form URL-encoded data |
| `multipart-form` | Multipart form data |
| `graphql` | GraphQL query |

### http.auth

Authentication configuration. Credentials are specified directly under the `auth` object. Use `inherit` to inherit authentication from the parent folder or collection.

```yaml theme={null}
# Inherit from parent
auth: inherit

# Bearer token
auth:
  type: bearer
  token: "{{token}}"

# Basic authentication
auth:
  type: basic
  username: admin
  password: secret

# API Key
auth:
  type: apikey
  key: x-api-key
  value: "{{api-key}}"
  placement: header

# OAuth 1.0
auth:
  type: oauth1
  consumerKey: "{{consumer_key}}"
  consumerSecret: "{{consumer_secret}}"
  accessToken: "{{access_token}}"
  accessTokenSecret: "{{token_secret}}"
  signatureMethod: HMAC-SHA1
  version: "1.0"
  placement: header
  includeBodyHash: false
```

Supported auth types: `none`, `inherit`, `basic`, `bearer`, `apikey`, `digest`, `oauth1`, `oauth2`, `awsv4`, `ntlm`, `wsse`.

## runtime

The runtime section contains scripts and assertions that execute during the request lifecycle.

### runtime.scripts

JavaScript code to run at different points in the request lifecycle.

```yaml theme={null}
runtime:
  scripts:
    - type: before-request
      code: |-
        // Runs before the request
        console.log('before-request');
        req.setHeader("X-Timestamp", Date.now());
    - type: after-response
      code: |-
        // Runs after the response
        console.log('after-response');
        bru.setVar("token", res.body.token);
    - type: tests
      code: |-
        test("should return 200", function() {
          expect(res.status).to.equal(200);
        });
```

| Script Type | Description |
| - | - |
| `before-request` | Runs before the request is sent |
| `after-response` | Runs after the response is received |
| `tests` | Test assertions using the Chai assertion library |

### runtime.assertions

Declarative assertions without writing JavaScript code.

```yaml theme={null}
runtime:
  assertions:
    - expression: res.status
      operator: eq
      value: "200"
    - expression: res.body.name
      operator: isString
```

| Field | Type | Description |
| - | - | - |
| `expression` | string | The value to evaluate (e.g., `res.status`, `res.body.name`) |
| `operator` | string | The comparison operator (`eq`, `neq`, `isString`, `isNumber`, etc.) |
| `value` | string | The expected value (for comparison operators) |

## settings

Request-level settings.

```yaml theme={null}
settings:
  encodeUrl: true
  timeout: 0
  followRedirects: true
  maxRedirects: 5
```

| Field | Type | Description |
| - | - | - |
| `encodeUrl` | boolean | Whether to URL-encode the request URL |
| `timeout` | number | Request timeout in milliseconds (0 = no timeout) |
| `followRedirects` | boolean | Whether to follow HTTP redirects |
| `maxRedirects` | number | Maximum number of redirects to follow |

## docs

Request-level documentation in Markdown format.

```yaml theme={null}
docs: |-
  # User Creation API

  This endpoint creates a new user in the system.

  ## Required Fields
  - name: User's full name
  - email: User's email address
```