Full reference

Complete schema documentation for every bolla concept.

Request definition

A request definition is any file ending in .bolla.yaml. bolla recursively scans your collection directory for them.

id: string          # unique within collection (required)
name: string        # display name
method: GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS
url: string         # supports {{variables}}

headers:
  X-My-Header: value

query:
  param_name: value

auth:               # see Authentication section

body:               # see Body section

assertions:         # see Assertions section

examples:           # used by mock server
  - name: success
    status: 200
    headers:
      Content-Type: application/json
    body: '{"id": "123"}'

Body

body:
  type: json          # json | raw | form
  content:            # for type: json — a YAML map serialized to JSON
    key: value
  # or for type: raw:
  raw: '{"manual":"json"}'
  content_type: application/json   # overrides default Content-Type

Authentication

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

# API key example
auth:
  type: api_key
  header: X-API-Key
  value: "{{API_KEY}}"

Assertions

Assertions run after every request. A failed assertion marks the run as failed in CI mode.

Variables

Use {"{{name}}"} anywhere in url, headers, body, auth. Variables are resolved from the active environment at request time.

# staging.env.yaml
id: staging
name: Staging
vars:
  base_url: https://api-staging.example.com
  TOKEN: ""           # overridden by env var BOLLA_VAR_TOKEN at runtime

Protocols

Load & scenarios Core

A scenario file (*.scenario.yaml) defines a multi-step load test.

id: smoke
name: Smoke test

load:
  type: ramp            # ramp | constant | spike
  start_concurrency: 5
  end_concurrency: 50
  duration_s: 60

steps:
  - request_id: create-user
    extract:
      USER_ID: "$.id"         # JSONPath extraction into a variable
  - request_id: get-user
    vars:
      id: "{{USER_ID}}"
    think_time_ms: 500        # pause between steps (simulates real user)

gates:
  p50_ms:    { max: 100 }
  p95_ms:    { max: 300 }
  p99_ms:    { max: 800 }
  error_pct: { max: 0.5 }
  rps:       { min: 100 }

Mock server Optional

bolla --mock --collection ./my-api --mock-port 3078

Serves your collection as an HTTP mock. Route matching uses method + url path from each request definition.

Example selection: by default the first example matching the request is returned. Override per-request with the header X-Bolla-Example: <name>.

Auto-generated responses: if no example matches, bolla generates realistic fake data based on field names. Fields named id, uuid, email, phone, name, price, created_at etc. receive appropriate fake values.

CI / CD gates Optional

bolla --ci --scenario smoke --env staging

Runs headless, prints a structured pass/fail summary, and exits 0 on pass or 1 on any gate failure.

Output files in .bolla/runs/<run-id>/:

• junit.xml — for GitHub Actions, GitLab CI, Jenkins
• result.json — full metrics JSON for custom dashboards

OAuth2 Optional

Define flows in .bolla/oauth2.yaml:

flows:
  - id: my-service
    grant_type: client_credentials     # or authorization_code, device_code
    token_url: https://auth.example.com/token
    client_id: "{{OAUTH_CLIENT_ID}}"
    client_secret: "{{OAUTH_CLIENT_SECRET}}"
    scopes: [read, write]

Reference a flow from any request: auth: { type: oauth2, flow_id: my-service }.

Tokens are cached in .bolla/tokens/ encrypted with AES-256-GCM. Expired tokens are refreshed automatically.

Presets available for: Google, GitHub, Microsoft (Azure AD), Okta, Auth0.

OpenAPI contracts Optional

# Import a spec and generate a collection
bolla --import-spec ./openapi.yaml --output ./my-api/

# Detect drift between spec and live responses
bolla --drift --spec ./openapi.yaml --env staging

Supported formats: OpenAPI 3.0, OpenAPI 3.1, Swagger 2.0. Import creates one .bolla.yaml per operation with auto-generated assertions for required fields and response schema.

History & reports Optional

All runs are stored in .bolla/history.db (SQLite). Browse and filter via the UI or REST API.

Run-to-run comparison: GET /api/load-runs/compare?a=<id>&b=<id> returns delta percentages for all metrics, with improved: true/false per metric.

Polish bundle Optional

A collection of productivity extras:

• Code snippets — export any request as cURL, Python (requests), JavaScript (fetch), or Go (net/http) via GET /api/polish/snippet?id=<req-id>&lang=python
• cURL import — paste a cURL command and get a .bolla.yaml back: POST /api/polish/import/curl
• HAR import — import a browser HAR file into a collection: POST /api/polish/import/har
• Security linter — scan a request for hardcoded secrets, missing auth, insecure URLs: GET /api/polish/lint?id=<req-id>
• HTML docs — generate self-contained HTML documentation for your collection: GET /api/polish/docs
• Dashboard stats — aggregate pass rate, avg latency, top failing requests: GET /api/polish/dashboard

AI assist Optional

Powered by Claude. You supply your own Anthropic API key — it never touches disk and is never sent anywhere except api.anthropic.com.

# Set key via env var (recommended for CI)
export ANTHROPIC_API_KEY=sk-ant-...

# Or set it in the UI: Settings → AI assist → API key

REST API

When running bolla --server, all capabilities are accessible via a local REST API on port 3077.

Core

Load

CLI flags