API Reference

Before your App code runs, Bruno injects a global window.bru into the guest page. All interaction with Bruno happens through bru.ctx.

Your App
    │
  bru.ctx
    │
  Bruno

Instead of using fetch() directly, your App calls bru.ctx.submitRequest() or bru.ctx.runRequest(). Bruno then interpolates variables, runs pre/post scripts, executes assertions and tests, records the timeline, and updates the response pane — exactly as if you pressed Send.

bru.ctx data arrives asynchronously after page load. Reading bru.ctx.http.response, bru.ctx.variables.resolved, or any other state field at the top level or inside DOMContentLoaded returns null or empty values.Always do the first render inside bru.ctx.onInit. React to later changes via the on*Change callbacks.

Shared surface

These fields and methods are available in both request-level and collection-level Apps.

Field	Type	Description
`bru.ctx.theme`	`{ name, mode, config }`	`mode` is `'light'` \| `'dark'`, also mirrored as a `light` / `dark` class on `document.body`. `config` is the full resolved theme object (colors, tokens, etc.).
`bru.ctx.variables.resolved`	`Record<string, any>`	Merged, read-only snapshot of all variables: global env → active env → collection vars → runtime vars (later keys win).
`bru.ctx.variables.runtime.set(name, value)`	`function`	Persists a runtime variable on the active collection for the session. Same scope as `bru.setVar` in scripts.
`bru.ctx.log(...args)`	`function`	Logs to the App’s own console and forwards to Bruno’s host console as `[app] …`.
`bru.ctx.onInit`	`(bru) => void`	Assigned by your code. Called once when the initial state arrives. The argument is `bru` (not `ctx`) — access state via `bru.ctx.*` inside the callback.
`bru.ctx.onThemeChange`	`(theme) => void`	Assigned by your code. Called when the theme changes.
`bru.ctx.onVariablesChange`	`(variables) => void`	Assigned by your code. Called when any merged variable changes.

Reading theme

// Check light/dark
const isDark = bru.ctx.theme.mode === 'dark';

// Read a specific token
const primaryColor = bru.ctx.theme.config.colors.primary;

// Or use the body class added automatically
document.body.classList.contains('dark'); // true in dark mode

Reading variables

bru.ctx.onInit = () => {
  const baseUrl = bru.ctx.variables.resolved['baseUrl'];
  console.log('Base URL:', baseUrl);
};

Setting a runtime variable

bru.ctx.variables.runtime.set('token', loginRes.data.token);
// Now {{token}} resolves in all subsequent requests

Request-level App

These fields are only available on request-level Apps. They do not exist on collection Apps.

Field	Type	Description
`bru.ctx.http.response`	`Response \| null`	The latest response for this request, from any source (Send button, runner, or the App itself).
`bru.ctx.http.onResponseChange`	`(response) => void`	Assigned by your code. Fired whenever a new response arrives.
`bru.ctx.assertions`	`Assertion[]`	Results of the latest assertion run for this request.
`bru.ctx.tests`	`Test[]`	Results of the latest test run for this request.
`bru.ctx.onAssertionsChange`	`(assertions) => void`	Assigned by your code. Fired when assertion results update.
`bru.ctx.onTestsChange`	`(tests) => void`	Assigned by your code. Fired when test results update.
`bru.ctx.submitRequest(options?)`	`(options?) => Promise<Response>`	Sends the parent request through the full Bruno pipeline. See Overrides.

Sending the parent request

// Simple send
const res = await bru.ctx.submitRequest();
console.log(res.status, res.data);

// Send with runtime variable overrides
const res = await bru.ctx.submitRequest({
  runtimeVariables: { userId: '42' }
});

The request must reference {{userId}} in its URL, body, params, or headers. Bruno interpolates the variable — it does not search-and-replace literal strings.

Reacting to responses

bru.ctx.onInit = () => {
  if (bru.ctx.http.response) render(bru.ctx.http.response);
};

bru.ctx.http.onResponseChange = (res) => render(res);

Reading test results

bru.ctx.onTestsChange = (tests) => {
  tests.forEach(t => console.log(t.status, t.description));
  // t.status is 'pass' or 'fail'
};

Collection-level App

These fields are only available on collection-level Apps. They do not exist on request Apps.

Field	Type	Description
`bru.ctx.collection`	`{ name, pathname } \| null`	Metadata for the collection the App belongs to.
`bru.ctx.onCollectionChange`	`(collection) => void`	Assigned by your code. Fired when collection metadata changes.
`bru.ctx.listRequests()`	`() => Promise<RequestSummary[]>`	Returns every HTTP/GraphQL/gRPC/WebSocket request in the collection. Folder Apps also see the whole collection, not just their folder.
`bru.ctx.runRequest(pathname, options?)`	`(pathname, options?) => Promise<Response>`	Runs any listed request by its pathname. See Overrides.

Listing requests

bru.ctx.onInit = async () => {
  const requests = await bru.ctx.listRequests();
  requests.forEach(r => console.log(r.method, r.name, r.pathname));
};

Running a specific request

const requests = await bru.ctx.listRequests();
const loginReq = requests.find(r => r.name === 'Login');

const res = await bru.ctx.runRequest(loginReq.pathname, {
  runtimeVariables: { email: 'user@example.com', password: 'secret' }
});

Types

Response

type Response = {
  status:     number | null,
  statusText: string | null,
  data:       any,                      // parsed JSON body, or raw string
  headers:    Record<string, string> | null,
  duration:   number | null,            // milliseconds
  size:       number | null             // bytes
}

RequestSummary

type RequestSummary = {
  uid:      string,
  name:     string,
  pathname: string,   // absolute filesystem path — stable unless the file is moved
  type:     string,   // 'http' | 'graphql' | 'grpc' | 'ws'
  method:   string,   // 'GET' | 'POST' | … (empty for non-HTTP types)
  url:      string
}

Assertion

type Assertion = {
  uid:         string,
  name:        string,
  description: string,
  status:      'pass' | 'fail',
  error?:      string
}

Test

type Test = {
  uid:         string,
  description: string,
  status:      'pass' | 'fail',
  error?:      string
}

Overrides

Both submitRequest and runRequest accept an optional options object:

{
  runtimeVariables: {
    key: 'value',
    // …
  }
}

How overrides work:

Values are injected as ephemeral runtime variables for that single send only.
They take precedence over all other variable scopes (global env, active env, collection vars, persistent runtime vars).
The request must reference them using {{name}} syntax — Bruno interpolates the variable at runtime. Hard-coded literal strings in the request body are not matched or replaced.
Overrides do not persist. To persist a value across requests, use bru.ctx.variables.runtime.set(name, value).

Notes & gotchas

bru.ctx.theme is an object, not a string. Use bru.ctx.theme.mode for the light/dark switch. The mode is also mirrored as a light / dark class on document.body. onInit receives bru, not ctx. The callback signature is (bru) => void. Access all state as bru.ctx.* inside it.

// Correct
bru.ctx.onInit = (bru) => {
  console.log(bru.ctx.variables.resolved);
};

// Also works (bru is the same global)
bru.ctx.onInit = () => {
  console.log(bru.ctx.variables.resolved);
};

Overrides are nested under runtimeVariables. Flat top-level keys on the options object are ignored.

// Correct
bru.ctx.submitRequest({ runtimeVariables: { id: '1' } });

// Wrong — id is silently ignored
bru.ctx.submitRequest({ id: '1' });

Pathnames are absolute filesystem paths. listRequests returns paths like /Users/me/collections/myapi/users/get-user.bru. They are stable as long as the file is not moved or renamed. No bru.ctx.http or bru.ctx.submitRequest on collection Apps. Those fields are request-level only. Accessing them on a collection App returns undefined. No bru.ctx.listRequests or bru.ctx.runRequest on request Apps. Those methods are collection-level only. Variable precedence. bru.ctx.variables.runtime.set and runtimeVariables overrides both write to the runtime scope, which sits at the top of Bruno’s precedence chain: global env → active env → collection vars → runtime vars.

Getting Started

Core Features

API Tools

Developer Tools

License Management

Advanced Guides

Shared surface

Reading theme

Reading variables

Setting a runtime variable

Request-level App

Sending the parent request

Reacting to responses

Reading test results

Collection-level App

Listing requests

Running a specific request

Types

Response

RequestSummary

Assertion

Test

Overrides

Notes & gotchas

​Shared surface

​Reading theme

​Reading variables

​Setting a runtime variable

​Request-level App

​Sending the parent request

​Reacting to responses

​Reading test results

​Collection-level App

​Listing requests

​Running a specific request

​Types

​Response

​RequestSummary

​Assertion

​Test

​Overrides

​Notes & gotchas

Shared surface

Reading theme

Reading variables

Setting a runtime variable

Request-level App

Sending the parent request

Reacting to responses

Reading test results

Collection-level App

Listing requests

Running a specific request

Types

Response

RequestSummary

Assertion

Test

Overrides

Notes & gotchas