TiefWise

TiefWise User Guide

Complete documentation for the TiefWise desktop API client.

Getting Started

TiefWise is a desktop API client for testing and managing REST API requests. The interface consists of:

  • Left Sidebar: Collections, Environments, History, Favorites
  • Center Panel: Request Builder (URL, params, headers, body, auth)
  • Right Panel: Response Viewer

1. Collections

Collections help you organize related API requests together.

Creating a Collection

  1. In the sidebar, click the + button next to "Collections"
  2. Enter a Name (required) and Description (optional)
  3. Click Create Collection

Collection Quick Actions

Each collection row shows these buttons (hover to see):

  • Play button (blue) - Run Collection immediately
  • Star button - Add/Remove from Favorites
  • Add file button - Add a new Request directly
  • 3 dots menu (...) - Click for more options

Collection Menu (3 dots)

Click the ... button on a collection to see:

  • Run Collection - Execute all requests in sequence
  • Rename - Change collection name
  • Collection Info - View details and description
  • Export - Export as TiefWise JSON
  • Share - Share collection
  • Add Folder - Create new folder inside collection
  • Add Request - Add new request to collection
  • Delete - Remove collection permanently

Creating Folders in Collections

  1. Click the ... menu on a collection
  2. Select Add Folder
  3. A new folder named "New Folder" is created (auto-renamed if duplicate)
  4. Click the ... on the folder to rename it

Saving a Request to a Collection

  1. Build your request in the center panel
  2. Click the Save button in the URL bar
  3. Select a collection (and optionally a folder)
  4. Enter a name for the request
  5. Click Save

Running a Collection

Quick Method: Click the blue play button on the collection row

Menu Method: Click ... then select Run Collection

Configure the runner:

  • Iterations: Number of times to run all requests
  • Delay: Milliseconds between requests
  • Click Run
  • View results for each request with pass/fail status

Request/Folder Actions (3 dots menu)

Click ... on any request or folder:

  • Edit/Rename - Change name
  • Info - View details
  • Duplicate - Create a copy
  • Move/Copy - Move or copy to another collection/folder
  • Export as cURL - Generate cURL command (requests only)
  • Add to Favorites - Star the request
  • Delete - Remove item

2. Making Requests

URL Bar

  1. Select HTTP method from dropdown: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
  2. Enter the full URL (e.g., https://api.example.com/users)
  3. Click Send button or press Enter

Query Parameters (Params Tab)

  1. Click the Params tab below the URL bar
  2. Add key-value pairs using the input fields
  3. Enable/disable individual params with the checkbox
  4. Parameters are automatically appended to the URL

Headers (Headers Tab)

  1. Click the Headers tab
  2. Add custom headers as key-value pairs
  3. Enable/disable individual headers with checkbox
  4. Common headers like Content-Type are auto-added based on body type

Request Body (Body Tab)

Select body type from the dropdown:

  • none - No body (typical for GET requests)
  • raw - JSON, XML, or plain text with syntax highlighting
  • form-data - Multipart form data with file upload support
  • x-www-form-urlencoded - URL encoded form data
  • binary - Binary file upload
  • GraphQL - GraphQL queries with variables support

Authentication (Auth Tab)

  1. Click the Auth tab
  2. Select authentication type:

None - No authentication

Basic Auth - Two modes available:

  • Credentials mode: Enter username and password
  • Pre-encoded mode: Enter base64-encoded token directly

Bearer Token - Enter JWT or access token

API Key - Configure key name, value, and location (Header or Query Parameter)

Request Settings Tab

Configure per-request settings:

  • Timeout - Request timeout in milliseconds (0 = no timeout)
  • Follow Redirects - Automatically follow HTTP redirects
  • Max Redirects - Maximum number of redirects to follow
  • Auto-encode URL - Automatically encode URL characters
  • Validate SSL - Verify SSL certificates

Import cURL

  1. Click the Import button (arrow icon) in the request panel
  2. Paste a cURL command
  3. Click Import
  4. Request is populated with URL, method, headers, and body from cURL

3. Environment Variables

Environments let you switch between different configurations (development, staging, production).

Creating an Environment

  1. Click Environments in the sidebar
  2. Click the + button to add new environment
  3. Enter environment name (e.g., "Development", "Production")
  4. Click Save

Adding Variables to an Environment

  1. Select an environment from the list
  2. Click Add Variable button
  3. Enter Key (e.g., baseUrl) and Value (e.g., https://dev.api.com)
  4. Click Save

Using Variables in Requests

Use double curly braces syntax anywhere: {{variableName}}

URL: {{baseUrl}}/users/{{userId}}

Header value: Bearer {{accessToken}}

Request body: {"api_key": "{{apiKey}}"}

Query param value: {{searchTerm}}

Activating an Environment

  1. Click the checkmark icon next to an environment to activate it
  2. Only one environment can be active at a time
  3. The active environment is highlighted
  4. All {{variables}} in requests are replaced with values from the active environment

Unresolved Variables Warning

If you use a variable that doesn't exist in the active environment, you'll see an error message listing the unresolved variables. The request won't be sent until you define the missing variables.

Importing Environment Variables

  1. Click the upload icon on an environment
  2. Upload a .env file
  3. Choose to merge with existing or overwrite all variables
  4. Variables are added to the environment

Exporting Environment Variables

  1. Click the download icon on an environment
  2. Download as .env file format

Environment Actions (3 dots menu)

  • Edit - Rename environment
  • Duplicate - Create a copy
  • Delete - Remove environment

4. Request History

Every request you send is automatically saved to history.

Viewing History

  1. Click History in the sidebar
  2. See all past requests with:
  • HTTP method badge (colored by method type)
  • Status code (green for 2xx, red for 4xx/5xx)
  • URL
  • Timestamp (relative time like "2 minutes ago")
  • Response time in milliseconds

Tabs in History

  • All - All history entries
  • Favorites - Starred entries only

Filtering History

  • Method filter - Filter by GET, POST, PUT, etc.
  • Status filter - Filter by 2xx, 4xx, 5xx
  • Date range - Filter by date picker
  • Tags - Filter by custom tags
  • Search - Search by URL

Sorting History

  • Click the sort icon to toggle ascending/descending order
  • Default: newest first

History Entry Actions

Hover over an entry to see action buttons:

  • Replay - Load request back into the editor
  • Favorite - Star/unstar the entry
  • Add Note - Add notes to the entry
  • Compare - Compare with another response
  • Delete - Remove from history

Viewing Entry Details

Click on a history entry to see full details:

  • Complete request (URL, headers, body)
  • Complete response (status, headers, body)
  • Timing information

Comparing Responses

  1. Click Compare icon on a history entry
  2. Select another entry to compare against
  3. View side-by-side differences in status codes, response bodies, and headers

Bulk Actions

  1. Click Select to enter selection mode
  2. Check multiple entries
  3. Use Delete Selected to remove multiple entries

Clear History

  1. Click the trash icon in the History header
  2. Confirm to delete all history entries
  3. This action cannot be undone

5. Import & Export

Importing Collections

Supported Formats:

  • Postman Collection v2.1
  • OpenAPI 3.x (Swagger)
  • cURL commands
  • TiefWise native JSON

How to Import:

  1. Click Import button in the toolbar
  2. Choose import method: File Upload or URL
  3. Format is auto-detected
  4. If collection name already exists, choose Replace or Create Copy
  5. Collection appears in sidebar

Importing Environments

  1. In Import modal, click Environments tab
  2. Upload Postman environment JSON or .env file
  3. Environment is added to your list
  4. Activate it to use its variables

Exporting Collections

  1. Click the ... menu on a collection
  2. Select Export
  3. Choose format: TiefWise JSON (recommended for backup)
  4. Save the file

Exporting Individual Requests as cURL

  1. Click the ... menu on a request
  2. Select Export as cURL
  3. Copy the generated cURL command
  4. Use in terminal or share with others

Workspace Import/Export

For complete backup including all collections and environments:

Export Workspace:

  1. Open Settings (gear icon)
  2. Go to Workspace tab
  3. Click Export Workspace
  4. Save the JSON file

Import Workspace:

  1. Open Settings (gear icon)
  2. Go to Workspace tab
  3. Click Import Workspace
  4. Select previously exported file

6. Response Viewer

After sending a request, the response appears in the right panel.

Response Header Bar

Shows at a glance:

  • Status - Code and text (e.g., "200 OK", "404 Not Found")
  • Time - Request duration in milliseconds
  • Size - Response body size

Response Tabs

Body Tab

  • View response content with syntax highlighting
  • JSON responses show in tree view (expandable/collapsible)
  • Toggle between Pretty (formatted) and Raw views
  • Copy button to copy entire response
  • Download button to save response as file
  • Search within response content

Headers Tab

  • View all response headers
  • Key-value pairs in table format
  • Copy individual header values

Cookies Tab

  • View cookies set by the response
  • See cookie name, value, domain, path, expiration

Response Status Colors

  • Green (2xx) - Success
  • Yellow (3xx) - Redirect
  • Red (4xx) - Client error
  • Red (5xx) - Server error

7. Favorites

Mark frequently used requests for quick access.

Adding to Favorites

From Collections:

  1. Click the star icon on a collection row
  2. Or click ... menu on a request and select Add to Favorites

From History:

  1. Click the star icon on a history entry

Accessing Favorites

  1. Click Favorites in the sidebar
  2. See all starred collections and requests
  3. Click any favorite to load it into the editor

Removing from Favorites

  1. Click the star icon again (now filled/yellow)
  2. Item is removed from favorites

8. Global Search

Search across all collections, requests, and environments.

Opening Search

  • Press Cmd+K (Mac) or Ctrl+K (Windows)
  • Or click the search icon in the toolbar

Using Search

  1. Type your search term
  2. Results show matching collection names, request names/URLs, folder names, environment names
  3. Click a result to navigate directly to it
  4. Press Escape to close search

9. Settings

Access settings via the gear icon in the toolbar.

Appearance Tab

  • Theme: Light or Dark mode
  • Sidebar Width: Adjust sidebar size (drag or use slider)
  • Editor Font Size: Small, Medium, or Large

Request Defaults Tab

Set global defaults for all new requests:

  • Timeout - Default timeout in milliseconds (0 = no timeout)
  • Follow Redirects - Enable/disable by default
  • Max Redirects - Default maximum redirects
  • Auto-encode URL - Auto-encode special characters
  • Validate SSL - Verify SSL certificates by default
  • Reset to Defaults - Restore original settings

Cache Tab

Configure response body caching:

  • Enable/Disable caching - Toggle response caching
  • Max cached responses - Number of responses to keep
  • Max cache size - Maximum cache size in MB
  • Clear Cache - Remove all cached responses
  • Shows current cache usage with progress bar

Workspace Tab

  • Link to Folder - Sync workspace to a local folder for backup
  • Unlink - Disconnect from sync folder
  • Linked Path - Shows current sync location
  • Statistics: Total collections, requests, and environments

10. Keyboard Shortcuts

Action Mac Windows/Linux
Send Request Cmd+Enter Ctrl+Enter
Global Search Cmd+K Ctrl+K
Save Request Cmd+S Ctrl+S
New Request Cmd+N Ctrl+N

Tips & Best Practices

  1. Use environments to avoid hardcoding URLs and tokens - switch between dev/staging/prod easily
  2. Organize with folders - Group related requests (e.g., "Authentication", "Users", "Orders")
  3. Name requests clearly - Use descriptive names like "Get User by ID" not just "GET request"
  4. Star frequently used requests - Quick access from Favorites panel
  5. Add notes to history - Document why certain requests were made
  6. Export collections regularly - Backup your work as TiefWise JSON
  7. Use cURL import - Quickly convert cURL commands from documentation
  8. Compare responses - Use history comparison to debug API changes