Skip to content
t-req t-req
HomeDocs

Collections

Organize and manage API requests in collections.

Collections help you organize related API requests together. Save requests to collections, browse them in a tree view, and share them with your team through version control.

Overview

A collection is a group of saved HTTP requests. Use collections to:

  • Organize by project - Group all requests for an API or service
  • Share with team - Collections are stored as files, easily committed to git
  • Reuse requests - Load saved requests without re-entering details

Creating Collections

Press ctrl+n in HTTP mode and select New Collection.

Enter a name for your collection. Collection names should be descriptive and unique within your workspace.

Collections are stored in the collections/ directory within your workspace as JSON files, making them easy to version control and share.

Saving Requests

Save New Request

  1. Build your request (URL, method, headers, body, etc.)
  2. Press ctrl+s to save
  3. Enter a name for the request
  4. Select or create a collection

Request names are used to generate file slugs. For example, “Get User Profile” becomes get-user-profile.

Update Existing Request

When editing a saved request, press ctrl+s to update it in place. The request stays in its current collection.

Save to Different Collection

Use the command palette (ctrl+p) and search for “Save to Collection” to save the current request to a different collection.

Managing Collections

Collection Tree

Press <leader>t to open the collection tree view. This shows all collections and their requests in a hierarchical view.

Navigate with arrow keys and press Enter to load a request.

View Collections

Use the command palette to access:

  • View Collections - Browse collections and their requests
  • Collection Tree - Hierarchical tree view

Delete Requests

From the collection tree or request list, select a request and choose delete to remove it from the collection.

Workspace Storage

Collections are stored in your workspace under collections/:

<workspace>/
├── collections/
│   ├── my-api/
│   │   ├── collection.json
│   │   ├── get-users/
│   │   │   ├── request.http
│   │   │   ├── get-users.hooks.js    (optional)
│   │   │   └── get-users.test.js     (optional)
│   │   └── create-user/
│   │       └── request.http
│   └── another-api/
│       └── ...
├── environments/
│   └── ...
└── workspace.json

File Format

Request files use standard HTTP format:

request.http
GET {{BASE_URL}}/users?limit=10
Accept: application/json

Or with a body:

request.http
POST {{BASE_URL}}/users
Content-Type: application/json


{
  "name": "John Doe",
  "email": "john@example.com"
}

Request IDs are the formatted directory names (e.g., get-users, create-user).

This format is designed to be:

  • Human-readable - Standard HTTP format familiar to developers
  • Git-friendly - Minimal merge conflicts
  • Portable - Share with teammates

Best Practices

Naming Conventions

  • Use descriptive names: “Get User by ID” not “Request 1”
  • Include the HTTP method in the name for clarity
  • Group related requests in the same collection

Version Control

Add collections/ to your repository to share requests with your team:

Terminal window
git add collections/
git commit -m "Add API request collection"

Secrets

Never save sensitive values (API keys, passwords) directly in requests. Instead:

  • Use environment variables: {{API_KEY}}
  • Store secrets in .secrets.json (gitignored by default)

See Environments for details.

Running Collections

There are three ways to execute requests from collections:

Individual Requests

Execute a single request:

Terminal window
treq http run <collection>/<request>
treq http run auth-service/login --env local

Each invocation is independent with no shared state between calls.

Test Execution

Run requests in the context of their test scripts:

Terminal window
treq test --collection <collection-name>
treq test --collection auth-service --env local

Focuses on test validation. Each request runs independently. See Scripts for test file format.

Sequential Workflow

Run all requests in a collection with shared state:

Terminal window
treq collection run <collection-name>
treq collection run auth-service --order login,me --env local

Requests share a session store (ctx.store), making this ideal for auth flows where login extracts a token that subsequent requests use.

See Scripts for hook examples that pass tokens between requests.