Kulcare Docs
DeveloperCare plans

Bruno (.bru) File Generation Guide

Purpose: This guide provides complete specifications for generating Bruno API collection files (.bru) that Claude (or any AI) can use to automatically create API documentation from code.

Table of Contents

  1. Overview
  2. File Structure
  3. Component Specifications
  4. Complete Examples
  5. Generation Rules
  6. AI Generation Template

Overview

What is Bruno?

  • Modern, open-source API client (alternative to Postman)
  • Uses plain-text .bru files stored in filesystem
  • Git-friendly, version-controllable format
  • Collections organized as folders

File Types:

  1. Request files (*.bru) - HTTP requests with method, URL, body, auth
  2. Folder files (folder.bru) - Folder metadata and inheritance
  3. Environment files (environments/*.bru) - Variables and configurations

File Structure

Directory Structure

kulcare-apis/
├── environments/
│   ├── local.bru
│   └── staging.bru
├── Auth/
│   ├── folder.bru
│   ├── Sign up.bru
│   └── Sign in.bru
├── Users/
│   ├── folder.bru
│   ├── Profile.bru
│   └── Update.bru
└── Reference/
    ├── folder.bru
    └── Drugs/
        ├── folder.bru
        └── list drugs.bru

Naming Conventions

  • Request files: PascalCase (e.g., Sign up.bru, List drugs.bru)
  • Folder files: Must be named folder.bru
  • Environment files: {environment-name}.bru (e.g., local.bru, staging.bru)

Component Specifications

1. Meta Section (REQUIRED)

Every .bru file must start with a meta section.

meta {
  name: Human Readable Name
  type: http
  seq: 1
}

Fields:

  • name: Display name (can have spaces, any case)
  • type: Always http for requests
  • seq: Sequence number (order in collection, integer)

2. HTTP Method Block (REQUIRED)

Format: {method} { ... } where method is lowercase

Supported Methods:

  • get - GET requests
  • post - POST requests
  • put - PUT requests
  • patch - PATCH requests
  • delete - DELETE requests

GET Request (No Body)

get {
  url: {{url}}/api/endpoint
  body: none
  auth: inherit
}

POST Request (JSON Body)

post {
  url: {{url}}/api/endpoint
  body: json
  auth: bearer
}

PUT/PATCH Request

put {
  url: {{url}}/api/endpoint/{{id}}
  body: json
  auth: bearer
}

Fields:

  • url: Full URL with {{variable}} substitutions
  • body: none | json | formdata | multipart | graphql
  • auth: inherit | bearer | basic | none

3. Authentication Block (OPTIONAL)

Bearer Token

auth:bearer {
  token: eyJhbGciOiJIUzI1NiJ9...
}

Basic Auth

auth:basic {
  username: user@example.com
  password: password123
}

Inherit from Folder

auth {
  mode: inherit
}

Use inherit when authentication is managed at folder level.

4. Request Body (OPTIONAL)

JSON Body

body:json {
  {
    "user": {
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe"
    }
  }
}

Rules:

  • Must be valid JSON
  • Use double quotes for keys and string values
  • Use {{variables}} for dynamic values
  • Format with proper indentation (2 spaces)

Form Data

body:formdata {
  user[email]: user@example.com
  user[password]: secret123
}

5. Query Parameters

Include directly in URL:

get {
  url: {{url}}/api/drugs?page=1&per_page=20&search=aspirin
  body: none
  auth: none
}

Or use variables:

get {
  url: {{url}}/api/drugs?page={{page}}&per_page={{per_page}}
  body: none
  auth: none
}

6. Headers

Headers are typically auto-generated, but can be specified:

headers {
  Content-Type: application/json
  Accept: application/json
  X-Custom-Header: value
}

7. Settings (OPTIONAL)

settings {
  encodeUrl: true
  timeout: 0
}

Fields:

  • encodeUrl: URL encode the request URL (true/false)
  • timeout: Request timeout in milliseconds (0 = no timeout)

8. Example Section (OPTIONAL)

For documentation and mock responses:

example {
  name: Success response

  request: {
    url: {{url}}/api/endpoint
    method: POST
    mode: json
    body:json: {
      {
        "param": "value"
      }
    }
  }

  response: {
    status: {
      code: 200
      text: OK
    }

    headers: {
      content-type: application/json
    }

    body: {
      type: json
      content: '''
        {
          "success": true,
          "data": {
            "id": "123",
            "name": "Example"
          }
        }
      '''
    }
  }
}

Multi-line content uses triple single quotes: '''

9. Folder Metadata (folder.bru)

meta {
  name: Folder Name
  seq: 1
}

auth {
  mode: inherit
}

Purpose:

  • Define folder display name
  • Set default authentication for all requests in folder
  • Organize collection hierarchy

10. Environment Variables

vars {
  url: http://localhost:3000
  access_token: {{access_token}}
  api_version: v1
}

Usage:

  • Reference with {{variable_name}} in request URLs
  • Manage different environments (local, staging, production)
  • Store sensitive data separately from requests

Complete Examples

Example 1: Simple GET Request (No Auth)

File: Reference/Countries.bru

meta {
  name: Countries
  type: http
  seq: 1
}

get {
  url: {{url}}/reference/countries
  body: none
  auth: none
}

settings {
  encodeUrl: true
  timeout: 0
}

Example 2: POST Request with JSON Body (No Auth)

File: Auth/Sign up.bru

meta {
  name: Sign up
  type: http
  seq: 1
}

post {
  url: {{url}}/identity/registrations
  body: json
  auth: inherit
}

body:json {
  {
    "user": {
      "email": "user@example.com",
      "phone_country_code": "91",
      "phone_number": "9888873165",
      "password": "SecurePass123",
      "first_name": "John",
      "last_name": "Doe",
      "timezone": "Asia/Kolkata",
      "preferred_language": "en",
      "signed_up_as": "practitioner"
    }
  }
}

settings {
  encodeUrl: true
  timeout: 0
}

example {
  name: Sign up success

  request: {
    url: {{url}}/identity/registrations
    method: POST
    mode: json
    body:json: {
      {
        "user": {
          "email": "user@example.com",
          "password": "SecurePass123",
          "first_name": "John",
          "last_name": "Doe"
        }
      }
    }
  }

  response: {
    status: {
      code: 200
      text: OK
    }

    body: {
      type: json
      content: '''
        {"success":true,"data":{"id":"123","createdAt":"2026-01-06T12:39:58Z","updatedAt":"2026-01-06T12:39:58Z","email":"user@example.com","firstName":"John","lastName":"Doe","fullName":"John Doe"}}
      '''
    }
  }
}

Example 3: GET Request with Bearer Auth

File: Users/Profile.bru

meta {
  name: Profile
  type: http
  seq: 3
}

get {
  url: {{url}}/identity/users/profile
  body: none
  auth: bearer
}

auth:bearer {
  token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiMDE5Yjk3OWQtN2E4Ny03MGU1LTgzMjctMjUxOWRjNmQ5ZjU4IiwiZXhwIjoxNzY3ODY4MzIxfQ.fq6JApvHqulJLKMFT97NPBEhk38thAU4skpUd9YJSIc
}

settings {
  encodeUrl: true
  timeout: 0
}

Example 4: PUT Request with Auth

File: Users/Update.bru

meta {
  name: Update
  type: http
  seq: 4
}

put {
  url: {{url}}/identity/users/{{user_id}}
  body: json
  auth: bearer
}

auth:bearer {
  token: {{access_token}}
}

body:json {
  {
    "user": {
      "first_name": "John",
      "middle_name": "M",
      "last_name": "Doe",
      "timezone": "Asia/Kolkata",
      "preferred_language": "en"
    }
  }
}

settings {
  encodeUrl: true
  timeout: 0
}

Example 5: GET with Query Parameters

File: Reference/Drugs/list drugs.bru

meta {
  name: List drugs
  type: http
  seq: 1
}

get {
  url: {{url}}/reference/drugs?page={{page}}&per_page={{per_page}}&search={{search}}
  body: none
  auth: none
}

settings {
  encodeUrl: true
  timeout: 0
}

Example 6: Folder Configuration

File: Auth/folder.bru

meta {
  name: Auth
  seq: 1
}

auth {
  mode: inherit
}

Example 7: Environment Configuration

File: environments/local.bru

vars {
  url: http://localhost:3000
  access_token: your_token_here
  page: 1
  per_page: 20
}

File: environments/staging.bru

vars {
  url: https://staging-api.kulcare.com
  access_token: your_staging_token
  page: 1
  per_page: 50
}

Generation Rules

Must-Follow Rules

  1. File Names:

    • Request files: PascalCase with spaces (e.g., Sign up.bru)
    • Folder files: Exactly folder.bru
    • Environment files: {name}.bru (lowercase)

  2. Meta Section:

    • Must be first section in every file
    • name field required
    • type: http for request files
    • Omit type for folder files

  3. HTTP Methods:

    • Use lowercase: get, post, put, patch, delete
    • Method block must include url, body, auth

  4. URL Format:

    • Use {{variable}} for dynamic parts
    • Include query parameters directly in URL
    • Use full path after domain

  5. Body Format:

    • JSON must be valid (double quotes, proper commas)
    • Use 2-space indentation
    • No trailing commas

  6. Auth:

    • inherit: Use folder-level auth
    • bearer: Token in auth:bearer block
    • basic: Username/password in auth:basic block
    • none: No authentication

  7. Example Section:

    • Optional but recommended for documentation
    • Use triple single quotes for multi-line content
    • Include both request and response

Formatting Standards

  • Indentation: 2 spaces for nested structures
  • Spacing: One blank line between sections
  • Line Length: No strict limit, but prefer readable lengths
  • Comments: Not supported in .bru format

Variable Naming

  • Use snake_case for variables: {{access_token}}, {{api_version}}
  • Common variables:
    • {{url}} - Base URL
    • {{access_token}} - Bearer token
    • {{user_id}} - Resource ID
    • {{page}}, {{per_page}} - Pagination

AI Generation Template

Template for Generating .bru Files

When asked to generate .bru files, use this structure:

For each API endpoint:
1. Create directory structure matching resource hierarchy
2. Generate folder.bru for each directory
3. Generate {Action}.bru file for each endpoint
4. Generate environment files if needed

Output format:
- Show complete .bru file content
- Include file path as comment
- Follow all formatting rules strictly

Generation Prompt Template

Copy this prompt when asking AI to generate .bru files:

Generate Bruno (.bru) collection files for the following API endpoints:

[INSERT API ENDPOINTS HERE - e.g., Rails routes, API documentation]

Requirements:
1. Follow the bru-file-generation-guide.md specifications exactly
2. Create proper directory structure
3. Include folder.bru files for each directory
4. Use proper HTTP methods (get/post/put/patch/delete)
5. Include auth: bearer for authenticated endpoints
6. Use {{url}} variable for base URL
7. Include example request/response for POST/PUT endpoints
8. Follow PascalCase naming for request files

Context:
- Base URL: {{url}}
- Auth: Bearer token for most endpoints
- Response format: JSON
- Follow existing kulcare-apis/ structure

Example Generation Request

Generate Bruno (.bru) files for these Rails routes:

GET    /identity/users/profile
GET    /identity/users/:id
PUT    /identity/users/:id
POST   /identity/registrations
POST   /identity/sessions

Follow the bru-file-generation-guide.md specifications.
Use {{url}} as base URL variable.
Auth: bearer token required except for registrations/sessions.
Create proper folder structure.

Quick Reference Card

HTTP Method Blocks

MethodSyntax
GETget { url: ... body: none auth: ... }
POSTpost { url: ... body: json auth: ... }
PUTput { url: ... body: json auth: ... }
PATCHpatch { url: ... body: json auth: ... }
DELETEdelete { url: ... body: none auth: ... }

Auth Types

TypeSyntax
Noneauth: none
Inheritauth: inherit
Bearerauth: bearer + auth:bearer { token: ... }
Basicauth: basic + auth:basic { username: ... password: ... }

Body Types

TypeSyntax
Nonebody: none
JSONbody:json + body:json { {...} }
Formbody:formdata + body:formdata { key: value }

Essential Variables

  • {{url}} - Base URL
  • {{access_token}} - Bearer token
  • {{id}} - Resource ID
  • {{page}}, {{per_page}} - Pagination

Validation Checklist

Before finalizing .bru files, verify:

  • Meta section present with name, type, seq
  • HTTP method block lowercase (get/post/put/patch/delete)
  • URL uses {{variable}} for base URL
  • Body type specified (json/none/formdata)
  • Auth type specified (inherit/bearer/basic/none)
  • JSON body is valid (double quotes, no trailing commas)
  • File naming follows PascalCase for requests
  • folder.bru files in each directory
  • Environment variables defined in environments/*.bru
  • Example section included for documentation endpoints

Additional Resources

Last Updated: 2026-01-12 Version: 1.0 Maintainer: Kulcare Development Team

Audit Schema

Previous Page

Careplan API Integration Documentation

Next Page

On this page

Table of ContentsOverviewFile StructureDirectory StructureNaming ConventionsComponent Specifications1. Meta Section (REQUIRED)2. HTTP Method Block (REQUIRED)GET Request (No Body)POST Request (JSON Body)PUT/PATCH Request3. Authentication Block (OPTIONAL)Bearer TokenBasic AuthInherit from Folder4. Request Body (OPTIONAL)JSON BodyForm Data5. Query Parameters6. Headers7. Settings (OPTIONAL)8. Example Section (OPTIONAL)9. Folder Metadata (folder.bru)10. Environment VariablesComplete ExamplesExample 1: Simple GET Request (No Auth)Example 2: POST Request with JSON Body (No Auth)Example 3: GET Request with Bearer AuthExample 4: PUT Request with AuthExample 5: GET with Query ParametersExample 6: Folder ConfigurationExample 7: Environment ConfigurationGeneration RulesMust-Follow RulesFormatting StandardsVariable NamingAI Generation TemplateTemplate for Generating .bru FilesGeneration Prompt TemplateExample Generation RequestQuick Reference CardHTTP Method BlocksAuth TypesBody TypesEssential VariablesValidation ChecklistAdditional Resources