Every request in Tetiva lives inside a collection, and every collection lives inside a workspace. A workspace isolates your data — collections, environments, request history and the cookie jar all belong to exactly one of them. A collection is a folder that holds requests and other collections, and hands them shared settings: authentication and pre/post-request scripts.
Workspaces#
The workspace switcher sits at the top of the sidebar. The icon next to the name tells you what kind it is: a cloud means the workspace is paired with the sync server, a monitor means it is local only. Pairing is covered in Sync.
A fresh install already has a Default Workspace and an active environment called Default. The switcher's context menu renames, creates and deletes workspaces. Deleting the last remaining workspace is rejected — there is always one left. The create dialog has a “Sync to server” checkbox that provisions the matching workspace on the server right away.
Switching workspaces swaps everything at once: the collection tree, the environment list, the history sidebar and the cookie jar. That makes workspaces the right tool for keeping a client project and your own scratch requests apart, variables included.
Nested collections#
A collection can sit at the root of a workspace or inside another collection, with no depth limit. “New Sub-Collection” in the context menu creates a child folder, “New Request” adds a request to it. A request always belongs to a collection — it cannot live at the root.
Nesting is more than visual grouping. A request whose auth type is Inherit searches upward through its parent collections, and collection scripts are inherited the same way. The walk stops after 50 levels — see Authentication and Scripting.
To search the tree, use the field in the sidebar header row, next to the buttons; Cmd/Ctrl+F puts the cursor in it. Matches are highlighted, and a folder that matches expands with all of its contents.
Description, auth and scripts#
“Open Details” opens the collection as its own tab with three sections.
Overview shows request and folder counts plus the description field. The description is Markdown: headings, lists, links, fenced code. The button on the right toggles Edit and Preview, and clicking the rendered text returns you to editing. Raw HTML inside the description is not executed, and bare URLs become links automatically.
Authorization sets the credentials used by every nested request whose auth type is Inherit. The list of types matches the request-level one, plus “Inherit from parent” for nested collections.
Scripts holds the collection-level pre- and post-request scripts.
Both the description and the auth settings survive a round trip through Postman format — see Import and export.
Multi-select#
The sidebar supports acting on several items at once:
- Cmd/Ctrl+Click adds an item to the selection or removes it;
- Shift+Click selects the range between the previous item and the current one, following the rows currently visible in the tree;
- Esc clears the selection;
- Delete or Backspace deletes everything selected.
While a selection is active the context menu changes: instead of the usual entries it offers “Move to...” and “Delete N items”. Bulk deletion always goes through a confirmation dialog, so a stray Backspace never wipes anything silently.
Moving items#
“Move to...” works both on a single item and on a selection. The dialog shows the collection tree plus a “Root (top level)” entry — the top level accepts collections only, a request always needs a target collection.
Moving a collection into one of its own descendants is rejected: Tetiva walks the parent chain and returns a validation error instead of breaking the tree.
Deleting#
Deletion is soft — the record is flagged as deleted rather than removed from the database. The confirmation dialog warns that the collection goes away with everything inside it, and open tabs for the nested collections and requests are closed at the same time.
Collections and environments travel together in practice: if your requests reference {{base_url}}, define that variable before you reorganise anything. Environments and variables explains how resolution works.