Collections

What is a collection

A collection is a named group of HTTP requests organized into nested folders. Collections are saved as JSON files on disk. One file holds one collection with all its folders, subfolders, and requests.

Structure

A collection contains:

• A name (e.g. “My API”).
• An optional base URL prepended to relative request URLs.
• A list of folders. Each folder has a name, a list of requests, and an optional list of subfolders. Folders can nest arbitrarily deep.

Editing a collection

Hook has two tree editors that both operate on the same underlying file:

• The sidebar tree on the left of the main window edits the currently active collection and persists every change immediately.
• The Collection editor popup (toolbar > Collections) edits any collection you load into it and also persists on every structural change.

Both editors expose the same four buttons on the selected tree node:

Requests don’t have a separate name field; the tree label is METHOD URL, edited through the normal request editor (click the request, change URL/method, Send or Save).

Reordering folders and requests

Use the + Folder, + Subfolder, Rename and Delete buttons under the tree to build and reshape the structure. To move an item to a different parent, delete it and re-add it in the new location, or use the Save in Collection dialog (for requests) which lets you pick any folder as the destination. Drag-and-drop reorder is currently disabled.

Creating a collection

From the Collection editor

1. Click Collections in the toolbar.
2. Click New to start a fresh collection with a single “Default” folder.
3. Edit the Name and Base URL fields at the top.
4. Use + Folder / + Subfolder to build out the structure, or drop in requests via “Save in Collection”.
5. Click Save As the first time to pick a file path; subsequent Save overwrites.

From Save in Collection

1. Compose a request (method, URL, headers, body, auth, etc.).
2. Click the Save in Collection button in the toolbar.
3. Pick the destination collection from the top combobox (or “(New Collection)” and type a name).
4. The tree shows that collection’s folders and requests.
5. Select a folder node – the primary button reads “Save”. Click it to append the current editor contents to that folder.
6. Or select an existing request leaf – the primary button changes to “Replace”. Click it (and confirm in the dialog) to overwrite that slot in place while keeping its position in the folder.
7. You can also build folders in-memory directly in the popup (+ Folder / + Subfolder / Rename / Delete) before clicking Save. Edits stay in a scratch copy until Save commits them to disk.

The collection file is written to the collections/ directory (or its existing location). If the saved-to collection is currently active, the sidebar tree refreshes automatically.

Destructive-action confirmations

Every destructive operation surfaces a Yes / No dialog that names the specific target:

• Delete a folder: Delete folder 'X' and its N request(s) / M subfolder(s)? This cannot be undone.
• Delete a request: Delete request 'METHOD URL' from folder 'Y'?
• Replace an existing request: Replace request 'METHOD URL' in folder 'Y' with the current editor contents?
• Delete a collection file: Delete collection 'X'? The file will be removed from disk.
• Overwrite on Save when the file already exists: Overwrite 'name.json'?

Rename collisions (including case-only changes like foo -> Foo) are refused silently with a statusbar message – no dialog, just “Name ‘X’ already used in this folder”.

Deleting a collection

1. Open the Collections editor and load the collection (or ensure it’s the active one so the editor mirrors it on open).
2. Click Delete.
3. Confirm. The JSON file is removed, the collection is unloaded, and the toolbar combobox refreshes.

Loading a collection

Select a collection from the toolbar combobox. The collection loads into the sidebar tree. Click a request leaf in either the sidebar or the Collection editor tree to populate the main request editor with all its saved settings.

JSON format

A collection file has this structure (nested folders via folders on each folder object):

{
  "name": "My API",
  "base_url": "https://api.example.com",
  "folders": [
    {
      "name": "Users",
      "folders": [
        {
          "name": "Admin",
          "requests": [
            { "method": "GET", "url": "/admin/users", "body_type": 0 }
          ]
        }
      ],
      "requests": [
        {
          "method": "GET",
          "url": "{{base_url}}/users",
          "headers": [
            { "name": "Accept", "value": "application/json", "enabled": 1 }
          ],
          "params": [],
          "body_type": 0,
          "body": "",
          "tls_verify": 1,
          "timeout_ms": 0
        }
      ]
    }
  ]
}

Body type values: 0 = none, 1 = raw, 2 = JSON, 3 = form, 4 = multipart, 5 = GraphQL.

Since Hook now has full tree-based editing, you rarely need to edit collection JSON by hand, but the format is stable and round-trip safe if you do.

base_url and variable precedence

The collection base_url field is available as {{base_url}} in request URLs. When clicking a collection request, templates are expanded using both the collection’s base_url and the active environment variables.

If the same variable (e.g. base_url) is defined in both the collection and the active environment, the environment value takes precedence. This allows environments to override the collection default:

• Collection base_url: https://api.example.com
• Environment base_url: https://api.dev.example.com
• Result: https://api.dev.example.com/users

Request fields tls_custom_ca_file, proxy_override, and use_curl_backend are optional and omitted when not set. GraphQL requests include graphql_query, graphql_variables, and graphql_operation fields. Auth settings are stored per-request when the auth type is not “none”.

Importing from Postman

Hook can import Postman Collection v2.1 JSON files.

In the GUI, click “Import Datas” in the toolbar, then click “Import Postman Collection (.json)” and select the JSON file.

From the CLI:

hook import postman myapi.postman_collection.json -o myapi.json

The imported collection preserves folder structure (including nested folders), request methods, URLs, headers, body, and basic/bearer auth where present.

Importing from Bruno

Hook can import Bruno .bru files. A single .bru file produces a one-request collection. A directory of .bru files (recursive) produces a collection with one folder per subdirectory.

In the GUI, use Import Datas > Bruno and select the file or directory.

From the CLI:

hook import bruno get_users.bru -o myapi.json
hook import bruno ./bruno_collection/ -o myapi.json

Importing a directory of collections

To bulk-import an entire directory of Hook collection JSON files:

1. Click “Import Datas” in the toolbar.
2. Click “Import Collection Directory (.json)”.
3. Select the directory containing .json collection files.

Each valid collection file is copied into the collections/ data directory. The toolbar combobox refreshes automatically.

Collection runner

The collection runner executes all requests in a collection, recursing into subfolders. Requests run in parallel. Each request produces a result with:

• Request method and URL.
• HTTP status code.
• Elapsed time in milliseconds.
• Pass/fail status (pass = 2xx status code).
• Error message if the request failed.

In the GUI, open the Runner panel from the sidebar. Select a collection, optionally select an environment, and click Run.

From the CLI, use hook run -f collection.json to execute the first request. Full collection runs are GUI-only.