# Changelog Source: https://docs.hoppscotch.io/documentation/changelog Latest Hoppscotch releases, including new features, bug fixes, and performance improvements across the web, desktop, and CLI clients. For a full list of releases, visit the [GitHub Releases page](https://github.com/hoppscotch/hoppscotch/releases). ## 2026.5.0 *Released: May 22 – June 2, 2026* ### New features * **OpenAPI 3.1 collection export** — You can now export [collections](/documentation/features/collections) as OpenAPI 3.1 specs, making it easier to share APIs with external tools. * **Collection-level pre-request and test scripts** — Define [pre-request and test scripts](/documentation/features/scripts) at the collection level so every request inside inherits the same setup and assertions. * **Configurable proxy URL** — Self-hosted admins can now set the proxy URL from environment variables or directly in the [admin dashboard](/documentation/self-host/enterprise-edition/admin-dashboard). * **Zoom level control on desktop** — The [desktop client](/documentation/clients/desktop/overview) now includes a zoom level setting so you can scale the UI to your preference. * **Mongolian translation** — Hoppscotch is now available in Mongolian. See the full list of [supported languages](/documentation/i18n). ### Updates * **Improved syncing engine** — The sync system has been refactored to reduce duplication across clients, improving reliability across web and desktop [workspaces](/documentation/features/workspaces). * **Desktop keyboard layout handling** — Keyboard layout detection has been reworked for more predictable [shortcut behavior](/documentation/features/shortcuts) across platforms. * **Security hardening** — Additional security patches have been applied across the dependency chain in this release. ### Bug fixes * **Published docs access control** — Public documentation links now revalidate the publisher's access before serving live data from team [collections](/documentation/features/collections), preventing data exposure when a member is removed after publishing. * **Secret variables stay local** — Values of secret [environment variables](/documentation/features/environments) no longer leak to the backend during sync. * **OpenAPI re-import preserves structure** — Re-importing an OpenAPI spec now keeps your existing folder tree intact. See [importing collections](/documentation/features/importer). * **Proxy settings load before requests** — Requests now wait for proxy settings to be ready before firing, avoiding misrouted calls on first load. * **Script imports preserved** — Pre-request and test [scripts](/documentation/features/scripts) now retain their imports correctly, including on WebKit-based browsers. * **Desktop fixes** — Resolved type mismatches and shell import issues in the desktop app for a smoother startup. * **Backend validation fixes** — Corrected validation on REST user request updates and class validator decorator usages. ## 2026.3.0 & 2026.3.1 *Released: March 27 – April 10, 2026* ### New features * **Cloud for organizations on desktop** — The desktop app now supports cloud-connected organizations, so you can access your org workspaces directly from the [desktop client](/documentation/clients/desktop/overview). * **User workspace memberships in admin dashboard** — Admins can now view which workspaces a user belongs to from the [admin dashboard](/documentation/self-host/enterprise-edition/admin-dashboard), making it easier to manage team access. * **Optional SMTP authentication and TLS settings** — Self-hosted deployments can now configure `MAILER_SMTP_IGNORE_TLS` and run SMTP without authentication, giving you more flexibility when setting up [email for your instance](/documentation/self-host/enterprise-edition/prerequisites). ### Updates * **Keyboard shortcuts on non-English layouts** — Shortcuts now work correctly regardless of your keyboard layout, including numpad support for tab switching. See [keyboard shortcuts](/documentation/features/shortcuts) for the full list. * **Clipboard shortcuts on Linux (desktop)** — The desktop app on Linux now includes a native Edit menu, restoring copy, paste, and other clipboard shortcuts. * **OAuth2 code challenge method** — Your PKCE code challenge method selection now persists correctly when using [OAuth2 authorization](/documentation/features/authorization). * **OpenAPI import improvements** — Importing OpenAPI specs now uses the operation title as a fallback name, and response examples are populated correctly. Learn more about [importing collections](/documentation/features/importer). ### Bug fixes * Newly created folders now appear immediately in the save-as dialog when organizing [collections](/documentation/features/collections). * Fixed an issue where request history entries could lose fields when restored. * Team collections now load the full folder tree when importing a workspace. * File attachments are now handled correctly when generating HAR exports. * Tooltips on icon-only buttons inside popovers are restored. * Fixed an infinite retry loop that could occur when authentication tokens expired permanently. * Resolved several security hardening fixes across the platform. ## 2026.2.0 & 2026.2.1 *Released: February 23 – March 4, 2026* ### New features * **API documentation versioning** — You can now publish multiple versions of your [API documentation](/documentation/features/documentation), letting consumers reference the exact version they need. * **Organization switcher** — A new dropdown-based switcher makes it easy to move between organizations from anywhere in the app. See [workspaces](/documentation/features/workspaces). * **URL encode/decode context menu** — Right-click any URL or parameter value to quickly encode or decode it, right from the context menu. * **Search and pagination in admin teams list** — Self-hosted admins can now search and paginate the teams list in the [admin dashboard](/documentation/self-host/enterprise-edition/admin-dashboard). ### Updates * **Legacy interceptor system deprecated** — The legacy interceptor has been deprecated in favor of the current [interceptor](/documentation/features/interceptor). If you're still using it, now is a good time to switch. * **Improved responsive layout for realtime pages** — [Realtime API testing](/documentation/features/realtime-api-testing) pages now handle smaller screens and overflow content more gracefully. ### Bug fixes * Secret environment variables are now correctly resolved in basic auth headers. * [Mock servers](/documentation/features/mock) now load reliably on initialization and workspace changes. * Fixed a scrollbar appearing in the URL input on Firefox. * Modal dialogs now display at the correct width on more screen sizes. * Opening a request from search results no longer causes a TypeError. * Variable tooltips with long values no longer overflow the viewport. * Fixed a corrupted sandbox state that could cause the app to hang. * CLI scripts with module prefixes now execute correctly. * Resolved a database connection leak in self-hosted infrastructure config operations. * Auth cookie expiration now uses the correct duration format. ## 2026.1.0 & 2026.1.1 *Released: January 20 – February 5, 2026* ### New features * **jq for JSON response filtering** — Response filtering now uses jq instead of JSONPath, giving you a more expressive way to query JSON responses. Learn more about [response handling](/documentation/getting-started/rest/response-handling). * **Web Crypto API in scripting sandbox** — [Scripts](/documentation/features/scripts) now have access to the Web Crypto API, enabling cryptographic operations like hashing and signing directly in your pre-request and test scripts. * **User roles in member stack tooltips** — Hovering over team member avatars now shows their role, making it easier to identify who has what access in your [workspace](/documentation/features/workspaces). * **Full request path in tab tooltips** — Tab tooltips now display the complete request path, so you can distinguish between similarly named requests. ### Bug fixes * Fixed a performance issue that could cause the app to hang when highlighting very large responses. * Prevented duplicate request IDs when duplicating requests. * Resolved memory leaks in the experimental scripting sandbox. * Fixed broken scrolling on the latest Chrome versions. * The support menu no longer triggers accidentally inside code editors. # Hoppscotch CLI Source: https://docs.hoppscotch.io/documentation/clients/cli/overview Use the Hoppscotch CLI to run API tests, automate monitoring, and manage collections from your terminal. Includes install steps and commands. Hoppscotch gives you multiple ways to interact with and configure your APIs. With the command-line interface (CLI) you can interact with the Hoppscotch platform using a terminal, or through an automated system. This enables you to run API tests, manage automated API monitoring, and more. This section contains a complete list of all Hoppscotch CLI commands available, alongside their optional parameters for additional behavior. You can also find a complete list of configuration options to configure your APIs through Hoppscotch. Hoppscotch CLI is currently in alpha stage. Report a bug by [opening a new issue](https://github.com/hoppscotch/hoppscotch/issues/new/choose). ## Pre-requisites Before installing the Hoppscotch CLI, ensure your system meets the following requirements. You will need `node-gyp` installed. Thus, follow the instructions from [node-gyp](https://github.com/nodejs/node-gyp). Execute the following command: ``` sudo apt-get install python g++ build-essential ``` Execute the following command: ``` sudo apk add python3 make g++ ``` Execute the following command: ``` sudo yum install gcc72 gcc72-c++ ``` Execute the following command: ``` sudo pacman -S make gcc python ``` Execute the following command: ``` sudo dnf install python3 make gcc gcc-c++ zlib-devel brotli-devel openssl-devel libuv-devel ``` ## Installing Hoppscotch CLI Once the dependencies are installed, install @hoppscotch/cli from npm by running: ```bash theme={null} npm i -g @hoppscotch/cli ``` The **minimum supported Node.js version** for the CLI is now **v22**. If you're on Node.js v20 (EOL in April, 2026), you can continue using CLI `v0.26.0` alongside `v2025.10.1` of the Hoppscotch app. Future CLI versions will require Node.js v22 or higher. ## Commands ### `hopp test` The `hopp test` command allows you to run tests against a Hoppscotch collection file. * The hopp test command recursively goes through each request in the collection and runs them, validating the responses with the test script provided in each request. Hence, the order of execution is the same as the order specified in the collection structure. * If upon executing the command, a failed assertion (a failing test case) has occurred, the command will give a non-zero exit code and 0 exit code if all tests have passed. * Unless there was a network error (for example, DNS resolution errors or network Connectivity Issues), the test script will be running and it is up to the test script to define what happens to error status codes. Non-200 status codes are still considered valid responses for test script execution. ```bash theme={null} hopp test [-e ] [-d ] ``` ### Running Collections present on the API client The `hopp test` command can also be used to run collections present in your API client on Hoppscotch cloud or self-hosted platforms. Do note that you need to create a personal access token for your CLI to connect to your API client, and you can not run collections present in your personal workspace. ```bash theme={null} hopp test [-e ] [-d ] [--token ] [--server ] ``` You can directly copy the command with the auto-populated **Collection ID** and **Environment ID** by navigating to the **“CLI"** tab within the **“Run Collection”** action found in the context menu. ### Generate JUnit Report for Collection Runs The `hopp test` command now has the ability to generate a JUnit Report for collection runs in the CLI. The report is generated as an XML file at the specified path provided in the command. If no path is specified, the report will be saved in the working directory with the default name `hopp-junit-report.xml`. ```bash theme={null} hopp test --env --reporter-junit [path] ``` #### JUnit Report Format Overview The JUnit report generated for collection runs provides a structured summary of the test results. The table below provides a detailed breakdown of the JUnit report format, explaining the significance of each XML element: | Element | Description | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `` | Root element representing the entire set of test suites. | | `` | Represents a collection of test cases for a specific request. | | `` | Represents an individual test case. It corresponds to `pw.expect()` assertions with the description prefixed by that of the test suite `pw.test()`. It appears as a direct child of ``. | | `name` | Attribute for `` and `` elements. For ``, it indicates the hierarchy of collections up to the request. Organized at the request level using the naming convention: `//`. While, for ``, it'll be the description. | | `classname` | Attribute of `` that mirrors the `name` attribute of the parent ``. | | `` | Indicates an assertion failure within a ``. Includes `type` and `message` attributes describing the failure. | | `` | Indicates an error during assertion within a ``. Includes `message` attribute describing the error. | | `` | Represents errors reported at the request level (e.g., invalid URL, reference error in the test script). These errors are detailed within a `CDATA` section, with each error separated by newlines to ensure each issue is clearly identified. | | `time` | Attribute of `` that shows the execution time for the test cases (excluding request execution time). The total time is at the root ``. | | `timestamp` | Attribute of `` that records the execution date and time in ISO string format. | | `tests`, `failures`, `errors` | Attributes of `` and `` that track the number of test cases, failed cases, and errors, at the request level and effective count at the root level test suite respectively. Set to `0` at a request level test suite, if errors halt further execution. | ### Arguments * `hoppscotch collection id` : Each collection created in a Hoppscotch workspace is given a unique identifier known as the Collection ID. Collection IDs for each collection can be found under **“Details”** tab inside Collection **“Properties”**. * `environment id` : Similar to Collection IDs, each environment created in a Hoppscotch workspace is assigned a unique identifier known as the Environment ID. * `delay_in_ms` : Represents a time interval (in milliseconds) to pause execution of API requests before within a collection. * `access token` : It is a secure, unique identifier used to authenticate a user's access to their Hoppscotch account and its resources like collections, environments data. [Learn more about personal access tokens](/documentation/features/pat) * `server url` : This is optional and is the URL of your self-hosted instance when you're self-hosting your API client * `path` : Accounts for a file path where the JUnit report will be saved as an XML file in your file system. * `no_of_iterations`: Indicates the number of iterations to run the collection. Each iteration will run the entire collection once, replacing any iteration-specific data defined by the `--iteration-data` flag (if provided). ```bash theme={null} hopp test [--iteration-count ] [--iteration-data ] ``` * `file_path`: The path to the CSV file for iteration data. This file should follow the format: ``` key1,key2,key3 value1,value2,value3 value4,value5,value6 ``` Each row in the CSV corresponds to an iteration, and the values from that row will replace the respective environment variables during the iteration. For example: * **Iteration 1:** The values value1, value2, and value3 will be used. * **Iteration 2:** The values value4, value5, and value6 will be used. ### Example ```bash theme={null} hopp test kitchen-sink-hoppscotch-collection.json hopp test -e environment.json kitchen-sink-hoppscotch-collection.json hopp test -e environment.json -d 1000 kitchen-sink-hoppscotch-collection.json hopp test clxsntdgh0000lcx9fnits2h8 --token hopp test -e clxspay2r0006lcx99aqgjbay -d 1000 clxsntdgh0000lcx9fnits2h8 --token --server http://localhost:3170 hopp test -e environment.json kitchen-sink-hoppscotch-collection.json --reporter-junit kitchen-sink-junit.xml hopp test kitchen-sink-hoppscotch-collection.json --iteration-count 3 --iteration-data /path/to/iteration-data.csv ``` ## Environment Hoppscotch allows templates in several places. For example, you could specify your endpoint URL as `<>/post` and specify baseurl as [`https://echo.hoppscotch.io`](https://echo.hoppscotch.io) in an environment file. Hoppscotch CLI supports environment files in two specific formats: ### 1. Single Environment Entry Export Format This format is generated by Hoppscotch App when you export any of your environment. It includes a named environment (name) with key-value pairs, allowing you to define various variables within a single file. ```json theme={null} { "name": "my_env", "variables": [ { "key": "base_url", "value": "https://echo.hoppscotch.io" }, { "key": "auth_token", "value": "xxxxxxxxxxxx" } ] } ``` ### 2. Legacy Export Format Hoppscotch CLI continues to support the legacy format which was previously the only accepted format used by CLI. ```json theme={null} { "key1": "value1", "key2": "value2", "key3": "value3" } ``` ### 3. Environment ID To use an environment on your API client using its ID, click on the `Properties` action present in the **menu icon** next to each environment. Within the Details section, you'll find the **Environment ID**. Copy this ID and use it in the Hoppscotch CLI for execution. Please note that the Hoppscotch CLI exclusively supports the above three formats for importing environment variables. It **does not** offer compatibility with **Bulk Environment** exports or **any other export** format. ## Secrets If requests in a collection consists of secret variables we recommend either of the two approaches. 1. Inject the secret values as variables into the OS environment 2. Edit the environment export file and add the secret values manually ## Options | Option | Description | | ------------------- | ----------------------------------------------------------------------------------------------------------------- | | `-h` | Gives a list of associated commands and their descriptions | | `-v` | Displays the current version of the CLI | | `--env or -e` | Accepts environments in all the formats present in [Environment section](/documentation/clients/cli#environment). | | `--delay` or `-d` | Used to defer the execution of requests in a collection. | | `--token` | Expects a personal access token to be passed for establishing connection with your Hoppscotch account. | | `--server` | URL of your self-hosted instance, if your collections are on a self-hosted instance. | | `--reporter-junit` | Expects a file path to store the JUnit Report. | | `--iteration-count` | Defines the number of iterations to run the collection. | | `--iteration-data` | Accepts the path to a CSV file that contains iteration data. | | `--legacy-sandbox` | Opt-out from the latest experimental scripting sandbox. | ## Test Report Components Upon executing the commands, a comprehensive test report is generated, offering detailed insights into the performance of each request. Below, you'll find a breakdown of the components outlined in the test summary for the exported API Collection: Each instance of `pw.expect()` within the testScript of a request is considered a test case. Each invocation of `pw.test()` within the testScript of a request is regarded as a test suite. The total number of `testScript` fields across all requests in the provided collection export file, representing the overall number of test scripts executed. The total time taken to execute all test cases within the collection. The total number of requests executed within the collection. The cumulative time taken to execute all requests within the collection. The scripts executed prior to each request. The count matches the number of requests in the provided collection export file. # Hoppscotch CLI Troubleshooting Source: https://docs.hoppscotch.io/documentation/clients/cli/troubleshooting Resolve Hoppscotch CLI errors with this reference of error codes, messages, and causes related to tokens, workspace access, and collections. Below is a set of error codes and the corresponding messages that will be displayed in the CLI under various scenarios associated with workspace access. Understanding the reasons behind these errors will help you troubleshoot them on your end. ## `TOKEN_EXPIRED` > **The specified access token is expired. Please provide a valid token.** **Reason:** The supplied access token via the `--token` flag has been expired. ```bash theme={null} hopp test [-e ] [--token ] [--server ] ``` ## `TOKEN_INVALID` > **The specified access token is invalid. Please provide a valid token.** **Reason:** The specified access token via the `--token` flag is invalid or might have been deleted. ```bash theme={null} hopp test [-e ] [--token ] [--server ] ``` ## `INVALID_ID` > **The specified collection/environment (ID or file path) is invalid or inaccessible. Please ensure the supplied ID or file path is correct.** ### Case I **Reason:** Either an invalid ID is supplied or the resource is inaccessible to the user because the user isn't part of the team to which the resource belongs. ```bash theme={null} hopp test [-e ] [--token ] [--server ] ``` ### Case II **Reason:** Supplied file path of the collection or environment doesn't exist. ```bash theme={null} hopp test [-e ] ``` ## `INVALID_SERVER_URL` > **Please provide a valid SH instance server URL.** **Reason:** There are multiple cases in which this error can occur: * If the supplied server URL doesn't have a valid path under `/v1/access-tokens/{collection/environment}/{path/id}`, resulting in a `404` network call error. * If the received content type from the response is not `application/json`, safeguarding against cases where the network call doesn't fail, such as when the route is invalid as above, and checking against the content type (e.g., supplying the FE instance URL). * The supplied server URL doesn't conform to URL semantics (received `ERR_INVALID_URL` as the error code from the network call). For instance, missing a protocol (e.g., `http://` or `https://`), having an invalid structure, or containing illegal characters. * Couldn't find the server because the domain name couldn't be resolved (received `ENOTFOUND` as the error code from the network call). For instance, a typo in the domain name. ```bash theme={null} hopp test [-e ] [--token ] [--server ] ``` ## `SERVER_CONNECTION_REFUSED` > **Unable to connect to the server. Please check your network connection or server instance URL and try again.** **Reason:** Found the server, but the server refused to connect (received `ECONNREFUSED` as the error code from the network call). ```bash theme={null} hopp test [-e ] [--token ] [--server ] ``` # Hoppscotch Desktop App Source: https://docs.hoppscotch.io/documentation/clients/desktop/overview Download and install the Hoppscotch Desktop App for macOS, Windows, and Linux. Build and test APIs natively with a cross-platform client. Hoppscotch Desktop App is a cross-platform desktop application that helps you create and manage API requests. It is built on top of the [Hoppscotch Web Client](/documentation/clients/web/overview) and is powered by [Tauri](https://tauri.app). ## Download Hoppscotch Desktop App Download the latest version of Hoppscotch Desktop App for your operating system: Download for Apple Silicon-based Mac. Download for Intel-based Mac. Download the installer for Windows (64-bit). Download the portable version for Windows (64-bit). Download the Debian package for Debian-based Linux distributions. Download the AppImage for Linux. ## Version numbering Desktop version numbers use a shortened form where the major is the last two digits of the release year, so `26.6.0` is the desktop build of the `2026.6.0` release. A Windows MSI major version cannot exceed 255, so the full `2026` will not fit. The app info screen and the backup folder names show the `26.x.x` form, while the [releases page](https://github.com/hoppscotch/releases/releases) lists them as `2026.x.x`. ## Install Hoppscotch Desktop App 1. Download the latest version of Hoppscotch Desktop App from the links above or from [official website](https://hoppscotch.com/download). 2. Open the downloaded file. 3. Follow the on-screen instructions to install Hoppscotch Desktop App. 4. Open Hoppscotch Desktop App. 5. If you see a warning message, click "**Open**". # Connect to Hoppscotch Source: https://docs.hoppscotch.io/documentation/clients/desktop/setup Connect the Hoppscotch Desktop App to Hoppscotch Cloud, organization instances, or self-hosted editions. Includes setup steps for each platform. ## Hoppscotch Cloud Edition for Individuals Seamlessly access Hoppscotch Cloud Edition from Hoppscotch Desktop App: 1. Open Hoppscotch Desktop App. 2. Click the Hoppscotch logo in the top-left corner. 3. Click "**HOPPSCOTCH CLOUD**". 4. Sign in with your Hoppscotch Cloud account to access your workspaces and collections. ## Hoppscotch Cloud Edition for Organizations Add your Hoppscotch Organization instance to Hoppscotch Desktop App: 1. Open Hoppscotch Desktop App. 2. Click the Hoppscotch logo in the top-left corner. 3. Click "**Add instance**". 4. Provide your instance URL. 5. Sign in with your organization's Hoppscotch Cloud account to access your workspaces and collections. ## Hoppscotch Self-Hosted Edition for Community To enable desktop app support for your self-hosted Hoppscotch instance, make sure to update the `WHITELISTED_ORIGINS` environment variable in your `.env` file with your deployment URL. e.g. to allow connection to `https://hoppscotch.my-domain.com` you need to add `app://hoppscotch_my_domain_com` and `http://app.hoppscotch_my_domain_com` to the `WHITELISTED_ORIGINS` environment variable. ```bash theme={null} WHITELISTED_ORIGINS=...existing_origins,app://hoppscotch_my_domain_com,http://app.hoppscotch_my_domain_com ``` *app\://hoppscotch\_my\_domain\_com*   for Linux and macOS machines. *http\://app.hoppscotch\_my\_domain\_com*   for Windows machine. Add your self-hosted Hoppscotch Community Edition instance to Hoppscotch Desktop App: 1. Open Hoppscotch Desktop App. 2. Click the Hoppscotch logo in the top-left corner. 3. Click "**Add an instance**". 4. Enter the URL of your self-hosted Hoppscotch instance. 5. Click "**Connect**". You can also self-host Hoppscotch Desktop App. Follow the instructions in the [Hoppscotch GitHub repository](https://github.com/hoppscotch/hoppscotch/tree/main/packages/hoppscotch-desktop). ## Hoppscotch Self-Hosted Edition for Enterprise To enable desktop app support for your self-hosted Hoppscotch instance, make sure to update the `WHITELISTED_ORIGINS` environment variable in your `.env` file with your deployment URL. e.g. to allow connection to `https://hoppscotch.my-domain.com` you need to add `app://hoppscotch_my_domain_com` and `http://app.hoppscotch_my_domain_com` to the `WHITELISTED_ORIGINS` environment variable. ```bash theme={null} WHITELISTED_ORIGINS=...existing_origins,app://hoppscotch_my_domain_com,http://app.hoppscotch_my_domain_com ``` *app\://hoppscotch\_my\_domain\_com*   for Linux and macOS machines. *http\://app.hoppscotch\_my\_domain\_com*   for Windows machine. Add your self-hosted Hoppscotch Enterprise Edition instance to Hoppscotch Desktop App: 1. Open Hoppscotch Desktop App. 2. Click the Hoppscotch logo in the top-left corner. 3. Click "**Add an instance**". 4. Enter the URL of your self-hosted Hoppscotch instance. 5. Click "**Connect**". You can also self-host Hoppscotch Desktop App. Follow the instructions in the [Hoppscotch GitHub repository](https://github.com/hoppscotch/hoppscotch/tree/main/packages/hoppscotch-desktop). # Hoppscotch Web App Source: https://docs.hoppscotch.io/documentation/clients/web/overview Access the Hoppscotch Web App to build, test, and share APIs directly in your browser. Also available as a progressive web app (PWA). Hoppscotch web client provides you with a really easy interface to develop and test your APIs. You can start using the web client by opening [hoppscotch.io](https://hoppscotch.io) in your browser. # Hoppscotch Progressive Web App Source: https://docs.hoppscotch.io/documentation/clients/web/pwa Install Hoppscotch as a Progressive Web App (PWA) on any device for a fast, native-like API testing experience without an app store download. Hoppscotch is also available as a PWA (Progressive Web App). Progressive Web Apps (PWAs) are web apps that are fast, reliable, and engaging. They are installable and live on the user's home screen, without the need for an app store. They offer an immersive full-screen experience and re-engage users with web push notifications. ## Why PWA * **Fast** - Load instantly to get started with Hoppscotch in seconds. * **Installable** - Install Hoppscotch on your device's home screen, just like a native app. * **Reliable** - Never shows the downasaur, even in uncertain network conditions. * **Engaging** - Feel like a natural app on the device, with an immersive user experience. ## Install Hoppscotch PWA 1. On your computer, open Chrome or any Chromium-based browser. 2. Go to [hoppscotch.io](https://hoppscotch.io). 3. At the top right of the address bar, click "**Install +**". 4. Follow the on-screen instructions to install the PWA. Read more about [Progressive Web Apps](https://web.dev/progressive-web-apps). # Hoppscotch community Source: https://docs.hoppscotch.io/documentation/community Join the Hoppscotch community on Discord, GitHub, and X. Share feedback, get help from other developers, and stay updated on product releases. At Hoppscotch, we believe that the community is the most important part of our product. We want to make sure that our users have a great experience using our products and that they can contribute to the development of our products with their ideas, feedback, and suggestions. Join our open communities and forums to stay up to date with the latest happenings in the product. Follow us on X for news, updates and more. Join our Discord server to chat with the community. Contribute to the development of Hoppscotch. # Contributors Source: https://docs.hoppscotch.io/documentation/contributors Meet the open-source contributors behind Hoppscotch. View the full list of developers who help build and improve the API platform. Hoppscotch is a community-driven project. We are thankful to all the contributors who have helped us in making Hoppscotch a better tool for developers. Here are some of our top contributors who helped us to make Hoppscotch a better tool for developers. ![Contributors](https://contrib.rocks/image?repo=hoppscotch/hoppscotch) * [View the full list of contributors here →](https://github.com/hoppscotch/hoppscotch/graphs/contributors) # Develop Source: https://docs.hoppscotch.io/documentation/develop Contribute to Hoppscotch by reporting bugs, proposing features, or submitting pull requests. Learn the development workflow and guidelines. We love your input! We want to make contributing to Hoppscotch as easy and transparent as possible, whether it's: * Reporting a bug * Discussing the current state of the code * Submitting a fix * Proposing new features ## We develop with GitHub We use GitHub to host code, track issues, and feature requests, as well as accept pull requests. **We use [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow), So all code changes happen through pull requests.** Pull requests are the best way to propose changes to the codebase (we use [GitHub Flow](https://guides.github.com/introduction/flow/index.html)). We actively welcome your pull requests. ## Contributing When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change. Please note we have a [code of conduct](/support/code-of-conduct), please follow it in all your interactions with the project. ## Pull Request Process 1. Ensure any install or build dependencies are removed before the end of the layer when doing a build. 2. Update the README.md with details of changes to the interface, this includes new environment variables, exposed ports, useful file locations and container parameters. 3. Increase the version numbers in any examples files and the README.md to the new version that this Pull Request would represent. The versioning scheme we use is [SemVer](https://semver.org). 4. You may merge the Pull Request once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you. ## **Developing** * Section moved to [Self-Hosting](/documentation/self-host/getting-started). ### Browser-based development environment [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/hoppscotch/hoppscotch) [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/hoppscotch/hoppscotch) ### Local development environment * Section moved to [Self-Hosting](/documentation/self-host/getting-started). ### Docker compose * Section moved to [Self-Hosting](/documentation/self-host/getting-started). ## **Docker** * Section moved to [Self-Hosting](/documentation/self-host/getting-started). ## **Releasing** * Section moved to [Self-Hosting](/documentation/self-host/getting-started). #### Any contributions you make will be under the MIT License. In short, when you submit code changes, your submissions are understood to be under the same [MIT License](https://choosealicense.com/licenses/mit) that covers the project. Feel free to contact the maintainers if that's a concern. #### Report bugs using GitHub's Issues We use GitHub issues to track public bugs. Report a bug by [opening a new issue](https://github.com/hoppscotch/hoppscotch/issues); it's that easy! #### Write bug reports with detail, background, and sample code [This is an example](https://stackoverflow.com/q/12088905/180626) of a bug report I wrote, and I think it's not a bad model. Here's [another example](https://www.openradar.me/11905408). **Great Bug Reports** tend to have: * A quick summary and/or background * Steps to reproduce * Be specific! * Give a sample code if you can. * What you expected would happen * What happens * Notes (possibly including why you think this might be happening, or stuff you tried that didn't work) People love thorough bug reports. I'm not even kidding. #### Use a consistent coding style I'm again borrowing these from [Facebook's Guidelines](https://reactjs.org/docs/how-to-contribute.html) * 2 spaces for indentation rather than tabs * You can try using ESLint code extensions in VS Code or something similar. ## Recommended VS Code extensions * WindiCSS IntelliSense [Install](https://marketplace.visualstudio.com/items?itemName=voorjaar.windicss-intellisense) • [Repository](https://github.com/windicss/windicss-intellisense) * Vue Language Features (Volar) [Install](https://marketplace.visualstudio.com/items?itemName=vue.volar) • [Repository](https://github.com/johnsoncodehk/volar) * Stylelint [Install](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint) • [Repository](https://github.com/stylelint/vscode-stylelint) * SCSS IntelliSense [Install](https://marketplace.visualstudio.com/items?itemName=mrmlnc.vscode-scss) • [Repository](https://github.com/mrmlnc/vscode-scss) * SCSS Formatter [Install](https://marketplace.visualstudio.com/items?itemName=sibiraj-s.vscode-scss-formatter) • [Repository](https://github.com/sibiraj-s/vscode-scss-formatter) * PostCSS Language Support [Install](https://marketplace.visualstudio.com/items?itemName=csstools.postcss) • [Repository](https://github.com/csstools/postcss-language) * npm Intellisense [Install](https://marketplace.visualstudio.com/items?itemName=christian-kohler.npm-intellisense) • [Repository](https://github.com/ChristianKohler/NpmIntellisense) * JavaScript and TypeScript Nightly [Install](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-typescript-next) • [Repository](https://github.com/microsoft/vscode-typescript-next) * GraphQL [Install](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql) • [Repository](https://github.com/graphql/vscode-graphql) * ESLint [Install](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) • [Repository](https://github.com/Microsoft/vscode-eslint) * EditorConfig for VS Code [Install](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) • [Repository](https://github.com/editorconfig/editorconfig-vscode) * npm [Install](https://marketplace.visualstudio.com/items?itemName=eg2.vscode-npm-script) • [Repository](https://github.com/Microsoft/vscode-npm-scripts) ## License By contributing, you agree that your contributions will be licensed under [MIT License](https://github.com/hoppscotch/hoppscotch/blob/main/LICENSE). # AI Features Source: https://docs.hoppscotch.io/documentation/features/ai-features Use AI-powered features in Hoppscotch to rename requests, generate payloads, and write pre-request scripts and test cases automatically. Experimental Hoppscotch now offers a set of AI-powered features designed to simplify core stages of the API development lifecycle. These include renaming of API requests, generation of structured request payloads, and scripting capabilities for pre-request logic and test cases. These AI features are currently in the `alpha` stage and are exclusively available on [Hoppscotch Cloud](https://hoppscotch.io) and our [Desktop app](https://hoppscotch.com/download). They are **NOT** supported in the Self-Hosted Edition at this time. ### Enable AI-powered features To activate AI-powered features, follow these steps: 1. Open the **Settings** page within the Hoppscotch application. 2. Scroll to the **Experiments** section. 3. Toggle the **AI Experiments** option to enable the features. ### Rename API Requests When saving an API request to a collection, click the **Modify with AI** icon **( .⟡⁺ )** next to the request name field to have the system automatically assign a name based on the request's context and properties. Alternatively, you can use this feature to rename the pre-saved requests. You can even customize the naming convention (e.g., CamelCase, PascalCase) through the **Request Naming Style** dropdown located in the **Experiments** section of the **Settings** page. ### Generate Request Body Dynamically generate structured request payloads: 1. Click the **Modify with AI** icon **( .⟡⁺ )** in the **Request Body** section. 2. Define constraints or provide input for the desired structure. 3. Validate the generated body and select **Accept Change** to populate the request body field. ### Generate Pre-request Scripts Generate pre-request scripts to handle necessary setup operations before sending the request: 1. Click the **Modify with AI** icon **( .⟡⁺ )** within the **Pre-request Script** section. 2. Enter specific logic or conditions required for the pre-request phase. 3. After reviewing the generated script, click **Accept Change** to apply it to the pre-request script section of your API request. ### Generate Test Scripts Develop test cases for your API workflow: 1. Click the **Modify with AI** icon **( .⟡⁺ )** in the **Tests** section. 2. Specify the test parameters or expected outcomes. 3. Select **Accept Change** to integrate it into the test script editor for execution. # Authorization Source: https://docs.hoppscotch.io/documentation/features/authorization Configure API authorization in Hoppscotch using Basic Auth, Bearer Tokens, OAuth 2.0, and more. Set auth at the request or collection level. REST APIs use authorization to ensure that a client has secure access only to the resources permitted by their roles. If you are building or integrating with a 3rd party API, you can choose between Basic Auth, Bearer Tokens, and OAuth2.0. Auth details can be added to a header, body, or as parameters to a request. However, if you enter your auth details in the Authorization Tab, Hoppscotch will automatically modify the relevant parts of the request based on your chosen `Auth` type. Storing Auth Credentials or Bearer Tokens as environment variables, lets you re-use these more safely and efficiently. ## Inherit Inherit Authorization allows requests to automatically adopt the authorization settings defined at the parent collection or subfolder level. This means you only need to configure the authorization once, and all nested requests will inherit these settings, ensuring consistency and saving time during setup. ## Basic Auth Basic Authentication is one of the simplest methods to secure your API requests in Hoppscotch. It works by requiring a username and password to be sent along with each request. To get started, head to the **Authorization** tab and select `Basic Auth` as your authentication type. You'll then input your verified **username** and **password**. When you send the request, Hoppscotch will automatically encode your credentials in the format: ``` Basic ``` Basic Auth transmits your credentials in a way that can be easily decoded, so it's best suited for secure channels like HTTPS to prevent exposure. ## Bearer Tokens Bearer Tokens are used to authenticate requests using an access token, which can be a simple string or a JWT (JSON Web Token). To set it up, choose `Bearer` from the **Authorization** tab and enter your **access token**. Hoppscotch will include the token in the request header as: ``` Bearer ``` Be aware that if your token expires, you'll need to refresh it manually and update it in Hoppscotch. For better security, consider storing your token as an environment variable so that you can easily reference it in your requests. ## API Key API Keys are unique identifiers that help authenticate your requests to an API. In Hoppscotch, you can set up `API Key` authentication by selecting it from the **Authorization** tab. Here, you'll need to fill in two fields: the **Key**, which is the name the API expects (like `api_key` or `Authorization`), and the **Value**, which is your actual API Key. You can also choose whether to pass this API Key as a **Header** or as a **Query Parameter**. When using API Keys, keep an eye on the rate limits set by the API provider to avoid any issues. For improved security practices, store your API Key as an environment variable to facilitate easy management across different environments. ## OAuth 2.0 OAuth 2.0 provides a secure way to let third-party applications access your resources without needing to share your passwords. Instead of directly passing credentials, you authenticate through a trusted service, which then issues an access token. This **token** allows your app to make API requests on your behalf. OAuth 2.0 workflows are not fully supported in the Hoppscotch Desktop application and are currently a work in progress. We're actively working on it, and it will function as intended soon! ### Steps for OAuth 2.0 Setup 1. In the "**Authorization Tab**" for a request, select `OAuth 2.0` from the Authorization Type drop-down. 2. Select the [Grant Type](/documentation/features/authorization#grant-types) from Authorization Code (with or without PKCE), Client Credentials, Password Credentials, and Implicit. 3. Fill out the fields in the section below and click on "**Generate Token**" to generate a new access token. 4. You can save the token to be re-used later. ### Grant types When using OAuth 2.0 authorization with Hoppscotch, you can utilize the following grant types: #### 1. Authorization Code The Authorization Code grant is used when your application needs to access a user's account. The user logs in to the OAuth provider and gives permission, allowing your app to receive a special code. You then use this code to request an access token that lets you access the user's data. To use the `Authorization Code` grant type, ensure the [Callback URL](#oauth-callback-url-configuration) is correctly configured (either `https://hoppscotch.io/oauth` for Hoppscotch Cloud or `/oauth` for self-hosted editions). Next, provide the **Authorization Endpoint** and **Access Token Endpoint** from the API provider, along with the **Client ID** (and the Client Secret if you choose to use it). You can also specify the desired permissions in the **Scope** field and pass the token as a **Header** or as a **Query Parameter**. Once you've filled in these fields, click Generate Token to get your access token. If your API provider supports token refreshing, you can use the **"Refresh Token"** button in Hoppscotch to obtain a new access token without requiring the user to log in again. > #### Using PKCE > > Opting for OAuth 2.0 with PKCE (Proof Key for Code Exchange), you gain the option to enhance security. Upon selecting PKCE, you can choose between **SHA-256** or **Plain** algorithms. #### 2. Client Credentials The Client Credentials grant is suitable for server-to-server interactions, where your application needs to access its own resources rather than user-specific data. This method relies on your app's credentials to obtain an access token directly. To obtain a token using `Client Credentials` grant type, input the **Authorization Endpoint** from the API provider, and fill in your **Client ID**. Including a Client Secret is optional. You can now choose how the **client credentials** (Client ID and Client Secret) are sent to the server. Hoppscotch supports both: * Sending them in the **body of the request** (default behavior). * Sending them via **Basic Authentication headers**. Just select your preferred method in the `Client Authentication` field to suit your security requirements. #### 3. Password Credentials The Password Credentials grant allows you to authenticate users by sending their username and password directly to the API. This method is less secure and is generally discouraged for third-party applications. To implement the `Password` credentials grant type in Hoppscotch, provide your API provider's **Authorization Endpoint**, along with the **Username** and **Password**. Occasionally, you may also be required to supply a Client ID and Secret. #### 4. Implicit The Implicit grant is intended for client-side applications, where the access token is returned immediately without the need for an authorization code. While this method simplifies the process, it does come with security risks. To configure the `Implicit` grant type in Hoppscotch, make sure the [Callback URL](#oauth-callback-url-configuration) is set as required (either `https://hoppscotch.io/oauth` or `/oauth`). You will need to further provide the **Authorization Endpoint** and **Client ID** to generate the token. ### OAuth Callback URL Configuration When using OAuth 2.0 with Hoppscotch Cloud, the **callback URL** is fixed to `https://hoppscotch.io/oauth` while for self-hosted editions of Hoppscotch, the callback URL should be set to `/oauth`. You must configure this URL as a valid **redirect URI** in your OAuth provider's settings. This is important because Hoppscotch handles all OAuth requests on the client side. When your OAuth provider redirects you to this URL, we process the response to obtain the token or authorization code. Any mismatch between the registered callback URL and what Hoppscotch uses will result in errors like `INVALID_REDIRECT_URI` during the authorization process. The Callback URL is required only for **Authorization Code** and **Implicit** grant types. Other grant types do not need this configuration. ## Digest Digest Auth is a way to verify your identity without transmitting plain-text passwords. Instead of sending your credentials directly as plain-text, it uses a challenge-response system to keep your information safe. When you attempt to access a restricted resource, the server responds with a `401 Unauthorized` status and a `WWW-Authenticate` header. This header contains essential information, including a unique challenge that you will use to generate a valid response. To configure Digest Auth in Hoppscotch, start by entering your **Username** and **Password**. For added security, you can also provide optional parameters like Realm and Nonce from the `WWW-Authenticate` header. Choose the appropriate **Algorithm** for hashing and define the **Quality of Protection (QoP)** to further secure your requests. You can also specify parameters such as **Nonce Count**, **Client Nonce**, and **Opaque** to further bolster the authentication process. **Digest Auth** is supported exclusively when using the [Hoppscotch Agent interceptor](/documentation/features/interceptor#hoppscotch-agent). ## AWS Signature AWS Signature is a method used to authenticate API requests made to AWS services. When you send a request, this configuration ensures that your request is genuine and has not been tampered with. It does this by using a process called HMAC (Hash-based Message Authentication Code), which creates a unique signature based on your request details. To set up `AWS Signature` in Hoppscotch, enter your AWS **Access Key** and **Secret Key** to sign your requests. For advanced configuration, you can also provide details like the **AWS Region** where your service is hosted (like *us-east-1*), the **Service Name** of the specific AWS service you're accessing (such as *s3 or dynamodb*), and a **Service Token** if you're using temporary security credentials. ## JWT JWT (JSON Web Token) is a compact and secure way to transmit information between parties as a JSON object. It is commonly used for authentication and information exchange in web applications. In Hoppscotch, you can easily configure JWT authentication by selecting `JWT` from the **Authorization** tab. You can then enter your **JWT Token** directly, or if you have a JWT secret, you can use it to generate the token. This token will be included in the request header as: ``` Authorization: Bearer ``` *** # Managing Authorization at the Collection Level When managing multiple requests within a collection, setting identical authorization configurations for each request individually can be tedious. It is now possible to set authorization at the collection level, ensuring it applies to all the requests stored within that collection. **To set collection-level authorization:** * Right-click on a collection or a subfolder within a collection to open its **properties**. * Specify the authorization that all nested requests or folders should adhere to. * If a subfolder should inherit the properties of a parent collection, specify the authorization as `inherit`. # Client Certificate Source: https://docs.hoppscotch.io/documentation/features/client-certificate Add and manage PEM or PFX client certificates for SSL/TLS authentication in the Hoppscotch Desktop App or via the Hoppscotch Agent. Add and manage client certificates in [Hoppscotch Desktop App](https://hoppscotch.com/download) or in Hoppscotch Web App using the [Hoppscotch Agent](/documentation/features/interceptor#hoppscotch-agent) as an interceptor to authenticate your identity when connecting to secure APIs. ### Prerequisites Before you begin, ensure you have the following: * Either the **Hoppscotch Desktop App** installed on your system, or if you are using the Hoppscotch Web App, make sure the **Hoppscotch Agent** is installed and configured. * A valid Client Certificate in one of the following formats: * **.pem Certificate** * **.pfx/.pkcs12 Certificate** * The corresponding private key file, if the certificate is in .pem format. ### Adding Client Certificate 1. Open Hoppscotch's settings page from the side bar. 2. Within Interceptors section, locate the `Client Certificates` action: * Under Native settings if using the Desktop App. * Under Agent if using the Web App. 3. Click on the option to add a new client certificate and select the type of certificate you want to add: **.pem** or **.pfx/.pkcs12**. 4. **Upload Certificate Files** * **.pem Certificate**: Choose the **certificate file** (.crt/.cer/.pem) and upload the **private key file** (.key/.pem) in the designated field. * **.pfx/.pkcs12 Certificate**: Choose the **.pfx/.pkcs12** file. You may need to enter the password associated with the certificate file. 5. After uploading the certificate files, click on the save button to store the settings. **You cannot edit a certificate after adding it.** ### Using Client Certificate Once you add the certificate, it will automatically be applied to the configured domain whenever you make an HTTP request. If you wish to disable the certificate for a domain, simply uncheck the corresponding checkbox. ### Removing a certificate Remove a certificate when no longer needed for sending requests by selecting the **delete icon** located next to the certificate associated with a specific domain. # Collections Source: https://docs.hoppscotch.io/documentation/features/collections Create, organize, and share API request collections in Hoppscotch. Import and export collections from Postman, OpenAPI, and other formats. Hoppscotch helps you to organize your API requests with collections. You can create collections and add requests to them to share with your team or to use later. You can also import and export collections from Hoppscotch, OpenAPI, and Postman. You can access the collections by clicking the "**Collections**" icon on the side panel. ## Creating a new collection To create a new collection, click on the "**Add new**" button on the collections section and enter the name of the collection. You can also create a sub-collection by clicking on the "**Add new**" button on the desired collection and entering the name of the sub-collection. ## Save requests to collections To add a new request to your collection, you can click on the "**Save**" button on the request page and select the collection you want to add it to. Click on the drop-down menu next to the save button and click on "**Save as**" to save the request to a new location. You can also use the keyboard shortcut `Ctrl/Cmd` + `S` to save the request to a collection. ## Organizing collections You can organize your collections by dragging and dropping them to the desired location. You can also create sub-collections by dragging and dropping a collection into another collection. ### Editing collections To edit a collection, click on the "**Edit**" button on the collection's options. ### Adding requests to collections To add a request to a collection, click on the "**New request**" button on the collection's options to save the current request to the collection. ## Duplicating collections To duplicate a collection, click on the **"Duplicate"** button on the collection's options. ## Deleting collections To delete a collection, click on the "**Delete**" button on the collection's options. ## Importing and exporting collections You can import and export collections from Hoppscotch, OpenAPI, and Postman. ### Importing collections To import a collection, click on the "**Import**" button in the collections section and select the collection type you want to import. ### Exporting collections To export a collection, click on the "**Export**" button on the collection's options and select the collection type you want to export. ## Collection Properties Collection properties enable you to define settings that universally apply to all requests within the collection. At the collection level, you can configure: * Authorization * Headers * Variables Subfolders and individual requests within the collection inherit these properties by default and can override them when needed. To set collection properties: 1. Right-click on a collection or a subfolder within a collection to open its properties. 2. Specify the authorization, headers, and variables that all nested requests or folders should adhere to. 3. If a subfolder should inherit the properties of a parent collection, specify the authorization as "inherit" and leave headers unchanged. Variables inherit automatically—override by redefining the same variable in the child. # Context Menu Source: https://docs.hoppscotch.io/documentation/features/context-menu Use the Hoppscotch context menu to quickly set environment variables, add query parameters, or open requests in new tabs from selected text. Context-aware menus enable quick actions like creating variables or adding query parameters by selecting text or elements. The context menu offers three options: **Set as Variable**, **Add to Parameters**, and **Open Request in New Tab**. The "Add to Parameters" option is available only when using query parameters. ## Set as Variable You can use the **Set as Variable** option from the context menu to assign a selected value to an environment variable. Hoppscotch supports various variable scopes, including global, environment, and request-specific variables. For more details on these scopes [click here](/documentation/features/variables). ### How to use "Set as Variable" After setting an [environment variable](/documentation/features/environments), you can reference it using the format `<>`. This allows you to store values for reuse. For example, `<>` can be used to dynamically insert the base URL across your requests. ## Add to Parameters The **Add to Parameters** option allows you to quickly add parameters along with their values. When you select **Add to Parameters**, it automatically captures the parameter and its value. For example, if the `baseURL` is `https://jsonplaceholder.typicode.com/?user=1`, now the `user` with ID `1` will be included in the parameter placeholder. ## Open Request in New Tab The **Open Request in New Tab** option allows you to open any **selected URL or text** as a new request in a separate tab. By opening the selected URL in a new tab, you can continue working on your original request in its own tab without any interruptions. # Cookies Source: https://docs.hoppscotch.io/documentation/features/cookies Use the Hoppscotch Cookie Manager to add, edit, and remove cookies for specific domains. Send cookies with API requests in the Desktop App. Cookies support is only available in the [Hoppscotch Desktop App](/documentation/clients/desktop/overview). Hoppscotch Cookie Manager enables you to add, edit, and remove cookies for a domain. You can also send a cookie with a request. To open the Cookie Manager, click on the "**Cookies**" button in the bottom bar. ### Adding a domain The Cookie Manager allows you to specify a domain and add the cookies associated with that domain. You can remove all the domains using the "**Clear All**" button. 1. Add domain URL in the input field. 2. Click on the "**Add**" button. 3. Click on the "**Save**" button. Once you've specified a domain, you can add a cookie by clicking the **+** icon and entering a cookie string. ### Removing a domain You can remove a domain by clicking on the "**Delete**" icon from the Cookie Manager. ### Adding a cookie You can add a cookie by clicking on the "**+**" icon from the Cookie Manager. 1. Click on the "**+**" icon. 2. Enter the cookie string in the input field. 3. Click on the "**Save**" button. ### Editing a cookie You can edit a cookie by clicking on the "**Edit**" icon from the Cookie Manager. 1. Click on the "**Edit**" icon. 2. Edit the cookie string in the input field. 3. Click on the "**Save**" button. ### Removing a cookie You can remove a cookie by clicking on the "**Delete**" icon from the Cookie Manager. ### Sending a cookie with requests When you send a request to a domain for which you've specified a cookie, Hoppscotch will automatically include it as part of the request. # Customization Source: https://docs.hoppscotch.io/documentation/features/customization Personalize Hoppscotch by changing the background color, accent color, font size, language, and other settings to match your workflow. You can access the customization settings by clicking on the "[**Settings**](https://hoppscotch.io/settings)" icon on the side panel. ## Background color You can choose from a range of colors to set as your background. * System (Default) * Light * Dark * Black ## Accent color You can choose from a range of colors to set as your accent color. * Green * Teal * Blue * Indigo (Default) * Purple * Yellow * Orange * Red * Pink ## Language Hoppscotch supports multiple languages. You can choose your preferred language from the list of available languages. ## Expand navigation You can choose to expand the side panel to view the navigation menu with labels. ## Sidebar position You can choose to position the side panel on the left or right side of the screen. # API Documentation Source: https://docs.hoppscotch.io/documentation/features/documentation Generate API documentation from your Hoppscotch collections with code samples, Markdown descriptions, and shareable public URLs for your team. When you build a collection in Hoppscotch, documentation is generated for you out of the box. It covers every endpoint with ready-to-use code samples across popular languages. Request information like HTTP method, URL, headers, auth configuration, payload format, and response examples are all captured automatically. Want to provide more context? Use Markdown to write descriptions for collections, folders, or requests, they'll appear directly in your published docs, helping developers get up to speed faster. ## What you can do * Generate API documentation from your Collections * Collaborate with your team to edit and refine content * Support for Markdown descriptions * Share documentation with your team or the world * Publish documentation to a public URL * Organize endpoints with folders and subfolders * Include example requests and responses * Code snippets for various languages and frameworks * Version your documentation to maintain multiple releases * Allow users to switch environments dynamically ## Create documentation Descriptions make your documentation more useful by providing context beyond the raw request details. You can add descriptions at multiple levels — collections, folders, and individual requests — using Markdown syntax for formatting, links, images, and code blocks. 1. **Select a Collection**: Choose the collection you want to document. 2. **Write Documentation**: Navigate to Menu > Documentation. 3. **Publish**: Get a shareable link to your documentation by publishing it. ### Adding a description to a request 1. Select the request you want to document. 2. Navigate to the request's description field. 3. Add details about the endpoint's purpose, expected parameters, or usage notes. 4. Save to include it in the generated documentation. ## Collaborative Editing Invite team members to your workspace to collaborate on documentation. Changes made to the collection are reflected in the documentation, keeping everything in sync. ## Features ### Real-time Updates Documentation updates automatically as you modify your collection. You need to publish changes to redeploy the documentation. ### Code Snippets Automatically generated code snippets for various languages and frameworks help developers integrate with your API quickly. ### Example Responses Display example responses to help users understand what to expect from your API endpoints. You can add multiple examples for different scenarios (e.g., success, error). ### Markdown Support Use Markdown to add rich text descriptions, images, and links to your documentation, making it easy to read and understand. ### Versioning Maintain multiple versions of your API documentation to support different releases and API iterations. 1. **Create a Version**: When publishing your documentation, you can create a new version with a label (e.g., `v1.0`, `v2.0`). 2. **Switch Versions**: Users viewing your documentation can switch between available versions using the version selector dropdown. Versioning helps you maintain backward compatibility documentation while showcasing new features in the latest release. ### Environment Selector Each documentation version can be associated with a specific environment (e.g., Production, Staging, Development), allowing you to provide accurate base URLs and variables for that release. 1. **Configure Environments**: Set up environments with their respective base URLs and variables in your workspace. 2. **Select Environment per Version**: When publishing a documentation version, choose the environment to associate with it. Each version supports one environment. 3. **Dynamic Base URLs**: The documentation automatically displays the correct base URLs and code snippets based on the environment linked to the selected version. This feature is particularly useful when your API is deployed across multiple environments, allowing you to publish separate documentation versions for each environment (e.g., `v1.0-prod`, `v1.0-staging`). Selecting an environment will expose its variables to users viewing the documentation. Avoid using environments that contain sensitive information such as API keys, tokens, or other secrets. Consider creating a dedicated environment for documentation purposes with only non-sensitive variables. ## Publishing Publishing your documentation makes it accessible to anyone with the link, enabling developers worldwide to understand and integrate with your API. Once published, your documentation serves as a comprehensive guide for your collection, helping users explore endpoints and learn how to interact with your API. Published documentation automatically includes details for each request in your collection, complete with sample code snippets in multiple programming languages. When auto-sync is enabled, any updates you make to your collection are reflected in the documentation instantly, no need to republish after every change. Publishing Options Publishing Option ### First-time Publishing When you publish a collection for the first time, Hoppscotch automatically creates the initial version for you. The documentation will be auto-synced with your collection, meaning any changes you make to the collection will automatically update the published documentation. 1. **Open Documentation Panel**: Navigate to your collection and click on the Documentation option from the menu. 2. **Click Publish**: The initial version is created automatically and synced with your collection. ### Creating New Versions After your first publish, you can create additional versions to maintain different releases of your API documentation. Click on "Create Version" to open the publishing options. Publishing versions Publishing versions The publishing dialog includes the following options: * **Title**: The name of your documentation (e.g., "Swagger Petstore"). * **Version**: A label for this version of your documentation (e.g., `v1.0`, `v2.0`). * **Auto-sync with collection**: Enable this option to automatically update the published documentation when the collection changes. Disable it if you want to freeze this version. * **Environment**: Attach an environment to resolve variables in the published documentation. The environment's base URL and variables will be displayed in the documentation. Click **Publish** to deploy the new version. ### Published Documentation Snapshot After creating a version, a snapshot view of the published documentation opens up. This provides a preview of what your users will see. The snapshot view displays: * **Title and Version**: The documentation name and version label (e.g., "Swagger Petstore v2.0.0"). * **Published URL**: The shareable link to your documentation with options to copy or open in a new tab. * **Collection Structure**: A preview of your API endpoints organized by folders. * **Documentation Content**: The description, contact information, and variables (such as `baseUrl`) from the attached environment. Published versions are read-only snapshots. To make changes, create a new version or enable auto-sync with the collection. ### Managing Published Documentation * **Update**: Republish to reflect collection changes. * **Unpublish**: Remove public access at any time. * **Share**: Copy the documentation URL to distribute. ### Viewing Published Documentation Published Documentation View Published Documentation View The published view includes a sidebar for navigating endpoints, a version selector, and the environment indicator showing the associated base URL and variables. # Environments Source: https://docs.hoppscotch.io/documentation/features/environments Create global, personal, and shared environments in Hoppscotch to manage reusable variables across API requests, scripts, and workspaces. An environment allows you to group together a set of variable data. You can reference the variable data you define in an environment throughout Hoppscotch when sending requests or using scripts. Environments are also useful when you need to manage shared variables with a team. You can create environments and share them with your workspace members. ## Types of Environments 1. Global Environment - Variables defined in a global environment can be accessed from any workspace anytime. However, the variables defined in a personal or shared workspace environment, if used, will have higher precedence over global variables. 2. Personal Environment - Are personal to the user and is not associated with a shared workspace, however a user can use a personal environment in a shared workspace without sharing it with the workspace members 3. Shared Environments - Are unique to each shared workspace, all the shared environments created in a shared workspace are accessible to every member of the shared workspace ## Types of Variables in an Environment Hoppscotch environment provides support for two types of variables 1. A Regular environment variable allows users to reference the variable throughout Hoppscotch, and anyone can see the value associated with the variable. In a shared workspace, regular environment variable-value pairs will be synced to the server, making them available to all workspace members. However, you have the option to choose whether to sync a personal or global environment. 2. A secret environment variable enables users to specify secrets and reference the values as variables. The values of secret variables in any workspace will never be synced to the server or shared with any workspace members. It is expected that the user will populate the value of the variable at runtime. All secret variable values in Hoppscotch will be masked using asterisks (\*\*\*). Secret variables values will not be exported when an environment is exported. ## Types of Values in an Environment An environment variable can have two types of values: 1. **Initial Value** - The initial value of the variable when it is created. This value is used when the environment is first loaded. 2. **Current Value** - The current value of the variable, which can be modified at any time. This value is used when the environment is active. ## Shared Environment Access | | Environment Variable | Secret Variable | | ---------------- | -------------------------------------------- | --------------------------------------------------- | | Workspace Owner | create / delete variable, edit value and use | create / delete secret variable, add values and use | | Workspace Editor | create / delete variable, edit value and use | create / delete secret variable, add value and use | | Workspace Viewer | use | add value and use | ## Creating an environment Click on the ”Environments” icon on the sidebar to create environments. A variable created in an environment can be used by typing the variable name enclosed in double angle brackets `<>` ## Using scripts You can also create and delete environment variables using scripts by using the `pw` object. ```javascript theme={null} pw.env.set("variable", "value"); // Creates an environment variable pw.env.unset("variable"); // Deletes the environment variable ``` ## Duplicating an environment Create a copy of an existing environment to modify or test different configurations without affecting the original: 1. Click the "Environments" icon in the sidebar to view all existing environments under Global Environments. 2. Next to the environment you want to duplicate, click the **More** icon. 3. From the dropdown menu, select **Duplicate**. A new environment with the suffix `- Duplicate` will be created. Secret variable values will not be copied to the duplicated environment. Learn how you can create environment variables from the client. Learn how you can create environment variables using pre-request scripts. Learn more pre-request script examples. # GraphQL API Testing Source: https://docs.hoppscotch.io/documentation/features/graphql-api-testing Test GraphQL APIs in Hoppscotch with the query builder, schema explorer, variables, headers, and real-time response inspection tools. Hoppscotch's GraphQL API platform provides you with the best experience to test and play around with GraphQL. It's primarily divided into two sections along with other features to help you build and test queries. ## Request The request section houses the feature to enter your server endpoint and initiate a connection. Once the connection is made, the `query` builder assists you in designing queries to fetch the data that you require and run it. You can also add dynamic behavior to your queries by defining `variables`, `headers`, and `authorization`. ## Response This is where you see the responses to your API endpoints. You can download and copy the returned responses for further use. ## Other features ### Documentation GraphQL documentation is where you can view the documentation provided by the developer. ### Schema GraphQL uses a schema to define the structure of the data, the schema explorer helps you to understand how your data is structured. The GraphQL platform also houses other features like: * [Environments](/documentation/features/environments) * [Collections](/documentation/features/collections) * [History](/documentation/features/history) # History Source: https://docs.hoppscotch.io/documentation/features/history View and revisit your past API requests and responses in Hoppscotch. Favorite, filter, and quickly re-send previous requests from history. Hoppscotch helps you to keep track of your requests and responses. You can access the history of your requests by clicking on the "**History**" icon on the side panel. ## Save requests to history To save a request to your history, you can click on the "Send" button on the request page. Hoppscotch will automatically save the request to your history. ## Accessing requests from history To access a request from your history, click on the desired request in the history section. You can also access a request from your history by clicking on the "**History**" icon on the side panel. ## Favorite requests You can favorite a request by clicking on the "**Favorite**" button on the history entry's options. Click on the "**Favorite**" button again to unfavorite the request. Favorite requests can be filtered by clicking on the "**Filter**" button in the history section and selecting the "**Favorites**" filter. ## Filter history You can filter your history by clicking on the "**Filter**" button in the history section and selecting the desired filter. ## Deleting requests from history To delete a request from your history, click on the "**Delete**" button on the history entry's options. You can also delete all requests from your history by clicking on the "**Clear history**" button in the history section. # Importer Source: https://docs.hoppscotch.io/documentation/features/importer Import collections and environments from Postman, Insomnia, OpenAPI, and other tools into Hoppscotch. Supports JSON and HAR formats. Import data from other tools into Hoppscotch. You can import data from the following tools: | Service | Collections | Environments | | ------------------ | --------------------------------------------------- | ------------ | | **Hoppscotch** | ✓ | ✓ | | **Postman** | ✓ | ✓ | | **Insomnia** | ✓ | ✓ | | **OpenAPI** | ✓ | | | **HTTP Archive** | ✓ | | | **Other services** | [Contact support](/support/getting-started/contact) | | The size limit for importing collections varies by Hoppscotch edition. In **Hoppscotch Cloud**, you can import collections up to **10 MB**, while **Self-Hosted editions** allow imports of up to **50 MB**. ## Import from Hoppscotch 1. Export your Hoppscotch collection/environment to a JSON file. 2. Open Hoppscotch and click on the "**Import**" button on the collection/environment section. 3. Click on the "**Import from Hoppscotch**" tab. 4. Click on the "**Choose file**" button and select the JSON file you exported in step 1. 5. Click on the "**Import**" button. ## Import from Personal and other workspaces 1. Open Hoppscotch and click on the "**Import**" button on the collection section. 2. Click on the "**Import from another workspace**" tab. 3. Select the desired **workspace** from the drop-down menu. 4. Choose the "**collection**" from the list. 5. Click on the "**Import**" button. ### What's Imported in the above 2 cases * **Collections:** Complete set of request details, including parameters, request bodies, headers, authorization settings, pre-request scripts, test cases, request variables, response examples and collection-level properties are retained. * **Environments:** Regular environment variables are imported. **Secret variables' values** need to be manually entered as they aren't stored server-side for security reasons. ## Import from Postman 1. Export your Postman collection/environment to a JSON file. 2. Open Hoppscotch and click on the "**Import**" button on the collection/environment section. 3. Click on the "**Import from Postman**" tab. 4. Click on the "**Choose file**" button and select the JSON file you exported in step 1. 5. Click on the "**Import**" button. **Experimental Script Import:** When importing Postman collections (v2.0/v2.1), Hoppscotch can now import pre-request scripts and test scripts as an experimental feature. You'll be prompted to consent to this import during the process. This enables seamless migration of your existing Postman workflows including their scripting logic with Chai.js-powered assertions through the `pm` namespace compatibility layer. ### What's Imported * **Collections:** Query parameters from Postman are imported as request parameters and path parameters are imported as request variables. Request bodies, headers, and basic authorization are also imported. **Pre-request scripts and test cases** can now be imported (experimental, requires consent). Advanced authorization setups and collection-level settings aren't imported. * **Environments:** Imports both regular and secret environment variables directly. ## Import from Insomnia 1. Export your Insomnia collection/environment to a JSON file. 2. Open Hoppscotch and click on the "**Import**" button on the collection/environment section. 3. Click on the "**Import from Insomnia**" tab. 4. Click on the "**Choose file**" button and select the JSON file you exported in step 1. 5. Click on the "**Import**" button. ### What's Imported * **Collections:** Request details like query parameters are imported as request parameters, and path parameters are imported as request variables. Request bodies, headers, and basic authorization settings are also imported. However, other sections like scripts, tests, and advanced authorization methods aren't synced. * **Environments:** Regular environment variables are imported. ## Import from OpenAPI There are two ways to import OpenAPI collections into Hoppscotch: ### 1. Import from File 1. Export your OpenAPI specification to a JSON file. 2. Open Hoppscotch and click on the "**Import**" button on the collection section. 3. Click on the "**Import from OpenAPI**" tab. 4. Select **Import from File** option. 5. Click on the "**Choose file**" button and select the JSON file you exported in step 1. 6. Click on the "**Import**" button. ### 2. Import from URL 1. Copy the URL of your OpenAPI specification. 2. Open Hoppscotch and click on the "**Import**" button on the collection section. 3. Click on the "**Import from OpenAPI**" tab. 4. Select **Import from URL** option 5. Click on the "**Import from URL**" field and paste the URL that you copied in step 1. 6. Click on the "**Import**" button. ### What's Imported * **Collections:** Query parameters are imported as request parameters, and path parameters are imported as request variables. Authorization methods, headers, and response examples are also included. However, details like request bodies, scripts, and tests aren't imported. ## Import from HAR 1. Export the HTTP Archive (HAR) file from your browser or network monitoring tool. 2. Open Hoppscotch and click on the "**Import**" button on the collection section. 3. Click on the "**Import from HAR**" tab. 4. Click on the "**Choose file**" button and select the HAR file you exported in step 1. 5. Click on the "**Import**" button. ### What's Imported * **Collections:** Imports request headers and body content. Additional metadata or settings aren't included in this format. ## Import from other services * If you want to import data from other services, please [contact support](/support/getting-started/contact) and we will help you out. ### Import from cURL You can import cURL commands into Hoppscotch in the following ways: * **Copy and paste**: Copy and paste the cURL command into the Hoppscotch URL bar. * **Send drop-down menu**: Click on the send drop-down menu and select "**Import cURL**". Paste the cURL command into the text area and click on the "**Import**" button. # Inspections Source: https://docs.hoppscotch.io/documentation/features/inspections Use Hoppscotch inspections to detect misconfigured API request inputs like missing headers, parameters, or auth settings before sending. Hoppscotch Inspections help you identify and fix configuration issues in your API requests before sending them. They detect common problems such as missing headers, parameters, or authentication settings. When a request section is not configured correctly, Inspections displays an alert icon to notify you about potential issues. Clicking the alert icon opens the Inspections panel, which provides details about the problem and suggestions to resolve it. ## Inspecting Configuration Errors The Inspections panel provides an overview of configuration errors that may prevent your request from working as expected and offers guidance on how to fix them. # Interceptor Source: https://docs.hoppscotch.io/documentation/features/interceptor Bypass CORS restrictions using the Hoppscotch Agent, Proxyscotch, browser extension, or custom middleware to intercept API requests. You can access APIs blocked by `Cross-Origin Resource Sharing (CORS)` restriction by using either Hoppscotch Agent, Proxyscotch or custom middleware. You can also use the Hoppscotch web extension to intercept requests and responses. ## Hoppscotch Agent The Hoppscotch Agent is a micro application designed to mitigate the challenges posed by `CORS` in modern web browsers. Acting as a local intermediary, it intercepts API requests made through the Hoppscotch web app and reroutes them through your local machine. This means that the Hoppscotch Agent handles requests using your local network configuration. 1. Download the Hoppscotch Agent for your operating system: Download for Apple Silicon-based Mac. Download for Intel-based Mac. Download the installer for Windows (64-bit). Download the portable version for Windows (64-bit). Download the Debian package for Debian-based Linux distributions. Download the AppImage for Linux. 2. Open [Hoppscotch](https://hoppscotch.io) app and navigate to the "**Interceptors**" section in the **"Settings"** page. 3. Locate the "**Agent**" option within the Interceptors section to initiate a connection to your local agent. 4. The application will prompt you for a "**One-Time Verification Code**". This verification code will be generated within the Hoppscotch Agent. 5. Enter the verification code into the application to establish a secure connection. Once connected, all API requests made through the Hoppscotch web app will be routed through Hoppscotch agent, effectively eliminating CORS-related issues. Recommended interceptor for most users as it is compatible with all platforms. ## Proxy A proxy server acts as an intermediary between your device and the internet, forwarding requests and responses to and from the desired API. By routing requests through a proxy, you can bypass CORS restrictions and access APIs that would otherwise be blocked by the browser. * Enable proxy interceptor from "[**Settings page**](https://hoppscotch.io/settings)" under the **Interceptors** section. * You can replace the default Proxy URL with your own proxy middleware if you wish or use [Proxyscotch](https://github.com/hoppscotch/proxyscotch), which acts as a remote proxy server for routing API requests. ## Proxyscotch [Proxyscotch](https://github.com/hoppscotch/proxyscotch) is our official proxy server. It is an MIT licensed open-source project that can bypass Cross-Origin Resource Sharing (CORS) restrictions by routing API requests through a remotely hosted proxy, ensuring that requests originate from a trusted environment. #### Self-Hosted Proxyscotch To use Proxyscotch with a minimal setup, you can pull and run the official pre-built Docker image. This provides an instant proxy environment without requiring manual compilation or installation. You can host Proxyscotch on your own server by following the instructions below: ```bash theme={null} # Pull the latest Proxyscotch image from Docker Hub docker pull hoppscotch/proxyscotch # Run the container in detached mode, exposing port 9159 docker run -d -p 9159:9159 --name proxyscotch hoppscotch/proxyscotch ``` #### Proxyscotch Installer If you prefer a native installation, download and install both the Desktop and Server binaries for your operating system. Download proxyscotch for macOS desktops. This will install the tray application for seamless proxy management. Download the proxy server binary for Intel-based (x86-64) Macs. Download the proxy server binary for Apple Silicon-based (ARM64) Macs. Download proxyscotch for AMD-based Windows desktops. This will install the tray application for easy proxy management. Download the proxy server binary for AMD-based Windows machines. Download proxyscotch for ARM-based Windows desktops. This will install the tray application for easy proxy management. Download the proxy server binary for ARM-based Windows machines. Download proxyscotch for AMD-based Linux desktops. This will install the tray application for seamless proxy management. Download the proxy server binary for AMD-based Linux machines. The proxy will add a **desktop application to your system tray**, providing quick access to various proxy settings such as setting the access token. After launching the application, a dialog will prompt you to complete the **certificate installation** process. For more details on how to install the certificate, [visit this wiki](https://github.com/hoppscotch/proxyscotch/wiki/Certificate-Installation). Upon activation, the **server** will run in the background and interact with the proxy to route and manage requests. ### Building Proxyscotch from Source If you prefer to build and run Proxyscotch manually from source, you can clone the repository and compile the binaries for your platform. ```bash theme={null} git clone https://github.com/hoppscotch/proxyscotch.git ``` Follow the platform-specific instructions below to build the proxy and server from source for your operating system: ```bash theme={null} # Build the desktop tray application ./build.sh darwin # Build the standalone server application ./build.sh darwin server ``` You can use Git Bash to run the following commands: ```bash theme={null} # Build the desktop tray application ./build.sh windows # Build the standalone server application ./build.sh windows server ``` ```bash theme={null} # Build the desktop tray application ./build.sh linux # Build the standalone server application ./build.sh linux server ``` After building, the compiled binaries will be available in the `out/` directory. #### Running the Proxyscotch Server After building the server, use the following command to start the proxy server: ```bash theme={null} $ ./out/-server/server --host=":" --token="" # e.g. on Linux $ ./out/linux-server/server --host="localhost:9159" --token="" # or on Windows $ ./out/windows-server/server.exe --host="localhost:9159" --token="" ``` When the **token is left blank**, it grants unrestricted access to your proxy server. While this might be convenient, please be aware of the potential security risks and consider whether this level of open access is appropriate for your use case. #### Available Server Options After running the Proxyscotch server, you can customize its behavior using various command-line options. | **Option** | **Description** | | ----------------------------- | -------------------------------------------------------------------------- | | `--host=":"` | Define the host and port (default: `localhost:9159`). | | `--token=""` | Set an access token to restrict proxy usage (leave blank for open access). | | `--allowed-origins="*"` | Comma-separated list of allowed origins for CORS. | | `--banned-outputs=""` | Comma-separated list of response values to redact. | | `--banned-dests=""` | Comma-separated list of blocked destination hosts. | ### Configure Proxyscotch in Hoppscotch Once the container is running or the server is active, configure Hoppscotch to use `http://localhost:9159` as the Proxy URL in the "**Settings**" page. This setup will route all API requests through Proxyscotch, facilitating communication with APIs that enforce strict CORS policies. ## Browser Extension Since `CORS` is as simple as adding some HTTP headers, it's only blocked by the browser. You can build some proxy-like component that will make a call for you and get the response from the desired API. You add it to the headers and then send it back to Hoppscotch. ### How to use the Browser Extension 1. Install the browser extension from the below links: * [  Chrome](https://chrome.google.com/webstore/detail/hoppscotch-browser-extens/amknoiejhlmhancpahfcfcfhllgkpbld?hl=en) * [  Firefox](https://addons.mozilla.org/en-US/firefox/addon/hoppscotch) 2. Click on the Hoppscotch Browser Extension icon from the browser toolbar and ensure that `hoppscotch.io` is in your active origins. If you are using Hoppscotch Self-Host, add your own domain as a new origin 3. Refresh the Hoppscotch web app. 4. Open the interceptor and change the middleware to the browser extension You can either go to the settings and enable the use of the browser extension as shown below: Or you can open the interceptor menu and change the middleware as shown below: ### Origins The origin list defines the URLs that the extension can connect to. If you're using hoppscotch.io, then you do not need to add any other origins. However, if you are using a self-hosted instance, you should add the domain of your self-hosted instance as an active origin. # API Mocking Source: https://docs.hoppscotch.io/documentation/features/mock Create mock servers in Hoppscotch to simulate API endpoints with custom responses, status codes, and latency for prototyping and testing. Hoppscotch API Mocking lets you stand up mock servers that return predictable responses to HTTP requests. It's ideal for prototyping, front‑end development, contract-first API design, demos, and testing failure/latency scenarios, now built right into Hoppscotch. ## What you can do * Spin up mock servers without writing code * Define routes by method and path (with path params and queries) * Return custom status codes, headers, and bodies * Choose between static and dynamic responses (with [Variables](/documentation/features/variables)) * Simulate latency and flaky behaviors for realism * Organize and reuse mocks with [Collections](/documentation/features/collections) and [Environments](/documentation/features/environments) * Collaborate via [Workspaces](/documentation/features/workspaces) ## Create a mock server You can create a mock server from scratch or from an existing Collection. 1. New mock server * Click "New" * Select source collection * Provide a mock server name * Choose a response delay 2. From a Collection * Select a Collection menu, then click "Configure Mock Server" * Provide a mock server name * Choose a response delay * Each request/example becomes an initial mock route you can refine Once created, you'll get a mock server URL you can call from your app or your Hoppscotch requests. Keep the mock server URL in an Environment variable, for example `{{MOCK_BASE_URL}}`, so you can swap between mock and real servers easily. ## Define routes and responses A mock server is made of one or more routes. Each route matches an incoming request and returns a configured response. Route fields: * Method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS` * Path: Supports path params and query strings * Matching: Optional header and query matchers to choose the correct example * Response: Status code, headers, body, and artificial latency ### Example route Request ``` GET /users/42 ``` Response ```json theme={null} { "id": 42, "name": "Jane Doe", "role": "admin" } ``` ### Dynamic responses with variables Use Hoppscotch variables to make responses dynamic and realistic. * Timestamps: `{{timestamp}}` * UUIDs: `{{uuid}}` * Environment values: `{{ENV_NAME}}` Example dynamic body: ```json theme={null} { "requestId": "{{uuid}}", "generatedAt": "{{timestamp}}", "region": "{{REGION}}" } ``` You can also reference variables in headers, for example `X-Request-ID: {{uuid}}`. ## Save a response as an Example In Hoppscotch, you can save responses as examples to quickly populate mock routes with realistic data. Examples capture both the request configuration and its actual response, making it easy to convert real API behavior into mock endpoints. **To save a response as an example:** 1. Navigate to the right-sidebar and select the collection with your request 2. Choose the request and click **"Send"** 3. In the response section, click the **"Save as Example"** icon 4. The example will be stored in the request's history within the collection **Using examples in mock servers:** * When creating a mock server from a Collection, each saved example automatically becomes a mock route * Examples preserve the exact response status, headers, and body you received * You can edit examples to adjust the mock response (modify status codes, add headers, introduce delays) * Multiple examples for the same request let you simulate different scenarios (success, errors, edge cases) **Example workflow:** 1. Call your API endpoint and receive a response 2. Save that response as an example 3. Create a mock server from the collection 4. The mock route now returns the exact response you captured 5. Edit the example to add delays or modify data for testing Use examples to quickly bootstrap realistic mock data from your actual API, then refine them to test edge cases and failure scenarios. ## Latency, errors, and headers Control the realism of your mocks by tuning: * Status: 2xx, 3xx, 4xx, 5xx * Headers: `Content-Type`, `Cache-Control`, custom headers * Delay: Add fixed or ranged latency (for example, 250–1500 ms) Simulate network timeouts by setting a delay higher than your client's timeout to test retry logic. ## Using mocks with Collections and Environments * Save your mock routes alongside requests in a Collection for easy reuse * Store the mock server base URL in an Environment, for example `{{MOCK_BASE_URL}}` * Switch between mock and real backends by toggling the Environment variable Example request target: ``` {{MOCK_BASE_URL}}/orders?limit=10 ``` ## Collaboration and sharing Mocks live in your workspace, so teammates can: * View and edit routes and examples * Fork Collections and iterate on contracts * Use the same Environments to keep URLs and tokens in sync ## Best practices * Keep contracts first: define mocks before building the backend * Add negative cases early (400/401/403/409/429/500) to harden clients * Use example names that describe intent (for example, “empty list”, “invalid token”) * Centralize variables (for example, `{{MOCK_BASE_URL}}`, `{{REGION}}`) in Environments * Review and version mocks with your Collection changes ## Troubleshooting * 404 from mock: Ensure the method and path match exactly (including base path), and check example matching rules * Wrong example returned: Inspect header/query matchers and example priorities * CORS errors in the browser: Add `Access-Control-Allow-Origin: *` (or your origin) to the response headers * Timeouts: Reduce mock delay or increase your client timeout ## FAQs ### How do mocks differ from live endpoints? Mocks return predefined responses based on your rules. They don't execute business logic or touch data stores. ### Can I generate mocks from my existing requests? Yes. You can bootstrap routes from saved requests or examples in a Collection and refine them. ### Can I parametrize responses without code? Yes. Use Hoppscotch variables (UUID, timestamp, and Environment values) directly in response bodies and headers. ### Can I self‑host mock servers? Yes. See [Self‑host](/documentation/self-host/getting-started) for details on deploying Hoppscotch in your own infrastructure. ## Related * [Collections](/documentation/features/collections) * [Environments](/documentation/features/environments) * [Variables](/documentation/features/variables) * [Scripts](/documentation/features/scripts) * [Workspaces](/documentation/features/workspaces) # Personal Access Token Source: https://docs.hoppscotch.io/documentation/features/pat Generate and manage personal access tokens (PATs) to authenticate the Hoppscotch CLI with your Hoppscotch Cloud or self-hosted instance. A Personal Access Token (PAT) in Hoppscotch acts as a secure authentication method, allowing you to smoothly link your Hoppscotch API client, on Hoppscotch cloud or self-host, with the Hoppscotch CLI. ## Generating Personal Access Token Follow these steps to create a new token and manage its settings. Personal access tokens cannot be used to access data in your personal workspace. 1. Login to the Hoppscotch API client using your credentials. 2. Once logged in, navigate to your profile settings by clicking on your profile icon, located in the top right corner of the screen. 3. In the profile settings menu, locate and click on `Personal Access Tokens`. 4. Within the Personal Access Tokens section, find the option to "Generate New Token" and click on it. 5. Provide a brief description under **Label** to remind yourself of the token's purpose and select an expiration date for the token. Options typically include 7 days, 30 days, 60 days, 90 days, or set it to never expire. Once a Personal Access Token (PAT) is generated with **read-only access** permissions, it cannot be modified. Please review the token settings carefully before generating it to ensure it meets your access requirements. 6. After generating the token, it will be securely displayed. Use the **copy icon** to copy the token to your clipboard for immediate use. 7. If you decide that you no longer need the token, you can delete it by navigating back to your profile page. Remember, deleted tokens cannot be recovered. 8. Once you've copied or saved your PAT, you can use it to authenticate API requests across different Hoppscotch services. ## Enterprise Token Management In Self-Hosted Enterprise settings, users with Admin privileges have additional capabilities for managing Personal Access Tokens (PATs). 1. Admin can **oversee and manage** tokens generated by all users within the enterprise environment. 2. An Admin also possesses the **authority to delete** tokens under their purview. This capability ensures compliance with security protocols and allows for the removal of tokens that are no longer necessary or have expired. # Realtime API Testing Source: https://docs.hoppscotch.io/documentation/features/realtime-api-testing Connect to and test real-time APIs in Hoppscotch using WebSocket, Server-Sent Events (SSE), Socket.IO, and MQTT protocols with live logs. Hoppscotch's Realtime API platform helps you test your real-time APIs easily. It's primarily divided into two sections: the request section and the response section. ## Request The request section houses the feature to enter your server endpoint and initiate a connection. You also get the option to choose from four different protocols `WebSocket`, `SSE`, `Socket.IO`, and `MQTT`. ## Response Once the connection is established, you can view the responses and logs in the response section. Read our step-by-step tutorial on working with Realtime protocols. # RESTful API Testing Source: https://docs.hoppscotch.io/documentation/features/rest-api-testing Build and debug RESTful API requests in Hoppscotch with support for HTTP methods, headers, parameters, body, auth, and pre-request scripts. Hoppscotch's REST API platform provides you with a fast and seamless experience to test and debug your API endpoints. It's primarily divided into two sections along with other features to help you build better APIs. ## Request The request section provides you the capability to define your API endpoint and initiate the communication. You can select from a range of HTTP methods such as `GET`, `POST`, `PUT` etc. You can read more about HTTP methods in [RESTful protocol](/documentation/protocols/rest). You can also add dynamic behaviors to your requests by specifying `Headers`, `Request Body`, `Authorization Headers`, `Parameters`, and `Pre-request scripts`. Hoppscotch also provides the capability to run `Tests` on the responses you receive. ## Response This is where you see the responses to your API endpoints. You can download and copy the returned responses for further use. ## Other features The REST API platform also houses other features like: * [Environments](/documentation/features/environments) * [Collections](/documentation/features/collections) * [History](/documentation/features/history) # Runner Source: https://docs.hoppscotch.io/documentation/features/runner Run all requests in a Hoppscotch collection sequentially with configurable delays, iterations, and environment variables using the Runner. The Runner is a powerful tool that allows you to run a collection of requests sequentially. You can also configure the run settings to suit your needs. ## Running a Collection To run a collection: * Right-click on the collection and select the "**Run Collection**" option. * Alternatively, hover over the collection name and click on the "**Run Collection**" icon. You can choose to run the collection from the CLI or through the web interface based on your preference. A new tab will open where you can configure the run settings as described below. ## Run Settings 1. **Delay**: Set an interval delay (in milliseconds) between running each request. 2. **Stop Run if Error Occurs**: The collection run stops if an error is encountered within a script or if there's a problem sending a request. 3. **Persist Responses**: Log response headers and bodies for review after running the collection. Note that persisting responses may impact performance for large collections. 4. **Keep Variable Values**: Persist the variables used in the run, so any updates made to the variables during the run will retain their changes after completion. ## Executing the Run After setting up your preferences, start the collection runner. A new tab will display, showing real-time execution details, including: * **Collection**: The name of the collection being executed. * **Environment**: The active environment at runtime. * **Duration**: Total time taken to complete the run. * **Average Response Time**: The mean response time across all requests. ### Running and Post-Run Actions * **Stop**: Stop the current run at any time. * **Run Again**: When a run completes, you can restart with the same configurations as needed. * **New Run**: Stop the current run and restart with new settings. ## Runner Results The results view provides a comprehensive summary of your collection run, including: * **Request Status**: Success or failure of each request, along with HTTP status codes. * **Tests**: Detailed views of tests that passed or failed. * **Persisted Responses**: If enabled, view headers and bodies by selecting each request; otherwise, this section remains hidden. # Scripts Source: https://docs.hoppscotch.io/documentation/features/scripts Write pre-request scripts and post-request tests in Hoppscotch using JavaScript to add dynamic behavior, set variables, and validate responses. It is not recommended to migrate or reformat your existing scripts to the new scripting APIs at this time. Upcoming updates are expected to introduce breaking changes as we continue to refine and improve the scripting experience. The current rollout is intentionally gradual, allowing us to gather user feedback and iterate based on real-world usage. All further updates to scripting will be scoped to the experimental scripting sandbox, which is the default, and the preference can be updated from `Settings → Experiments`. [Your feedback will be invaluable as we shape the next generation of Hoppscotch scripting.](https://github.com/hoppscotch/hoppscotch/discussions/5221) This new experimental implementation provides a robust foundation for API scripting with enhanced capabilities for environment management, request manipulation, response processing, cookie handling, and comprehensive testing. The new system maintains backwards compatibility while introducing powerful new features for modern API testing workflows. ## `hopp.env` Namespace Environment variable management with scope-specific operations and enhanced functionality. ### `hopp.env.get(key: string)` Retrieves the value of the selected environment's variable. Accepts an environment variable as an argument. ```javascript theme={null} hopp.env.get("variable"); hopp.env.get("baseURL"); ``` ### `hopp.env.getRaw(key: string)` Retrieves the raw value of the selected environment's variable without variable resolution. ```javascript theme={null} hopp.env.getRaw("variable"); ``` ### `hopp.env.set(key: string, value: string)` Sets the value of an environment variable in the selected environment. ```javascript theme={null} hopp.env.set("baseURL", "https://httpbin.org"); ``` ### `hopp.env.delete(key: string)` Deletes an environment variable from the selected environment. ```javascript theme={null} hopp.env.delete("baseURL"); ``` ### `hopp.env.reset(key: string)` Resets an environment variable to its initial value in the selected environment. ```javascript theme={null} hopp.env.reset("baseURL"); ``` ### `hopp.env.getInitialRaw(key: string)` Retrieves the initial raw value of an environment variable. ```javascript theme={null} hopp.env.getInitialRaw("baseURL"); ``` ### `hopp.env.setInitial(key: string, value: string)` Sets the initial value of an environment variable. ```javascript theme={null} hopp.env.setInitial("baseURL", "https://httpbin.org"); ``` #### Active Environment Scope Operations specific to the currently active environment. ### `hopp.env.active.get(key: string)` Retrieves the value of the active environment's variable. ```javascript theme={null} hopp.env.active.get("variable"); ``` ### `hopp.env.active.getRaw(key: string)` Retrieves the raw value of the active environment's variable. ```javascript theme={null} hopp.env.active.getRaw("variable"); ``` ### `hopp.env.active.set(key: string, value: string)` Sets the value of an active environment variable. ```javascript theme={null} hopp.env.active.set("baseURL", "https://httpbin.org"); ``` ### `hopp.env.active.delete(key: string)` Deletes a variable from the active environment. ```javascript theme={null} hopp.env.active.delete("baseURL"); ``` ### `hopp.env.active.reset(key: string)` Resets a variable in the active environment to its initial value. ```javascript theme={null} hopp.env.active.reset("baseURL"); ``` ### `hopp.env.active.getInitialRaw(key: string)` Retrieves the initial raw value of an active environment variable. ```javascript theme={null} hopp.env.active.getInitialRaw("baseURL"); ``` ### `hopp.env.active.setInitial(key: string, value: string)` Sets the initial value of an active environment variable. ```javascript theme={null} hopp.env.active.setInitial("baseURL", "https://httpbin.org"); ``` #### Global Environment Scope Operations specific to the global environment. ### `hopp.env.global.get(key: string)` Retrieves the value of the global environment's variable. ```javascript theme={null} hopp.env.global.get("variable"); ``` ### `hopp.env.global.getRaw(key: string)` Retrieves the raw value of the global environment's variable. ```javascript theme={null} hopp.env.global.getRaw("variable"); ``` ### `hopp.env.global.set(key: string, value: string)` Sets the value of a global environment variable. ```javascript theme={null} hopp.env.global.set("baseURL", "https://httpbin.org"); ``` ### `hopp.env.global.delete(key: string)` Deletes a variable from the global environment. ```javascript theme={null} hopp.env.global.delete("baseURL"); ``` ### `hopp.env.global.reset(key: string)` Resets a variable in the global environment to its initial value. ```javascript theme={null} hopp.env.global.reset("baseURL"); ``` ### `hopp.env.global.getInitialRaw(key: string)` Retrieves the initial raw value of a global environment variable. ```javascript theme={null} hopp.env.global.getInitialRaw("baseURL"); ``` ### `hopp.env.global.setInitial(key: string, value: string)` Sets the initial value of a global environment variable. ```javascript theme={null} hopp.env.global.setInitial("baseURL", "https://httpbin.org"); ``` ## `hopp.request` Namespace Request manipulation with immutable properties and dedicated mutation functions. #### Read-only Properties ### `hopp.request.url` The request URL as a string. ```javascript theme={null} const url = hopp.request.url; ``` ### `hopp.request.method` The HTTP method of the request. ```javascript theme={null} const method = hopp.request.method; ``` ### `hopp.request.params` The query parameters of the request. ```javascript theme={null} const params = hopp.request.params; ``` ### `hopp.request.headers` The headers of the request. ```javascript theme={null} const headers = hopp.request.headers; ``` ### `hopp.request.body` The body of the request. ```javascript theme={null} const body = hopp.request.body; ``` ### `hopp.request.auth` The authentication configuration of the request. ```javascript theme={null} const auth = hopp.request.auth; ``` #### Mutation Functions (Pre-request Phase Only) ### `hopp.request.setUrl(url: string)` Sets the request URL. ```javascript theme={null} hopp.request.setUrl("https://api.example.com/users"); ``` ### `hopp.request.setMethod(method: string)` Sets the HTTP method of the request. ```javascript theme={null} hopp.request.setMethod("POST"); ``` ### `hopp.request.setHeader(name: string, value: string)` Sets a header on the request. ```javascript theme={null} hopp.request.setHeader("Authorization", "Bearer token"); ``` ### `hopp.request.setHeaders(headers: HoppRESTHeader[])` Sets multiple headers on the request. ```javascript theme={null} hopp.request.setHeaders([{ key: "Content-Type", value: "application/json" }]); ``` ### `hopp.request.removeHeader(name: string)` Removes a header from the request. ```javascript theme={null} hopp.request.removeHeader("Authorization"); ``` ### `hopp.request.setParam(name: string, value: string)` Sets a query parameter on the request. ```javascript theme={null} hopp.request.setParam("userId", "123"); ``` ### `hopp.request.setParams(params: HoppRESTParam[])` Sets multiple query parameters on the request. ```javascript theme={null} hopp.request.setParams([{ key: "userId", value: "123" }]); ``` ### `hopp.request.removeParam(name: string)` Removes a query parameter from the request. ```javascript theme={null} hopp.request.removeParam("userId"); ``` ### `hopp.request.setBody(body: Partial)` Sets the body of the request. ```javascript theme={null} hopp.request.setBody({ body: '{"key": "value"}' }); ``` ### `hopp.request.setAuth(auth: Partial)` Sets the authentication for the request. ```javascript theme={null} hopp.request.setAuth({ authType: "bearer", token: "token" }); ``` #### Request Variables ### `hopp.request.variables.get(key: string)` Retrieves the value of a request variable. ```javascript theme={null} const value = hopp.request.variables.get("varName"); ``` ### `hopp.request.variables.set(key: string, value: string)` Sets the value of a request variable. ```javascript theme={null} hopp.request.variables.set("varName", "value"); ``` > Please note that only updates to request variables get persisted and reflected in the UI while the remaining are specific to the session. ## `hopp.response` Namespace Response access with multiple data formats and comprehensive metadata. #### Response Metadata ### `hopp.response.statusCode` The HTTP status code of the response. ```javascript theme={null} const status = hopp.response.statusCode; ``` ### `hopp.response.statusText` The status text of the response. ```javascript theme={null} const statusText = hopp.response.statusText; ``` ### `hopp.response.headers` The headers of the response. ```javascript theme={null} const headers = hopp.response.headers; ``` ### `hopp.response.responseTime` The response time in milliseconds. ```javascript theme={null} const time = hopp.response.responseTime; ``` ### Response Body Access Methods ### `hopp.response.body.asJSON()` Parses the response body as JSON. ```javascript theme={null} const data = hopp.response.body.asJSON(); ``` ### `hopp.response.body.asText()` Returns the response body as text. ```javascript theme={null} const text = hopp.response.body.asText(); ``` ### `hopp.response.body.bytes()` Returns the response body as a Uint8Array. ```javascript theme={null} const bytes = hopp.response.body.bytes(); ``` ## `hopp.cookies` Namespace Domain-aware cookie management with comprehensive CRUD operations. ### `hopp.cookies.get(domain: string, cookieName: string)` Retrieves a cookie by domain and name. ```javascript theme={null} const cookie = hopp.cookies.get("example.com", "sessionId"); ``` ### `hopp.cookies.set(domain: string, cookie: Cookie)` Sets a cookie for a domain. ```javascript theme={null} hopp.cookies.set("example.com", { name: "session_id", value: "abc123", domain: "api.example.com", path: "/api", expires: new Date(Date.now() + 86400000).toISOString(), // 24 hours from now maxAge: 86400, // 24 hours in seconds httpOnly: true, secure: true, sameSite: "Lax", }); ``` ### `hopp.cookies.has(domain: string, cookieName: string)` Checks if a cookie exists for a domain. ```javascript theme={null} const exists = hopp.cookies.has("example.com", "sessionId"); ``` ### `hopp.cookies.getAll(domain: string)` Retrieves all cookies for a domain. ```javascript theme={null} const cookies = hopp.cookies.getAll("example.com"); ``` ### `hopp.cookies.delete(domain: string, cookieName: string)` Deletes a cookie for a domain. ```javascript theme={null} hopp.cookies.delete("example.com", "sessionId"); ``` ### `hopp.cookies.clear(domain: string)` Clears all cookies for a domain. ```javascript theme={null} hopp.cookies.clear("example.com"); ``` ## `hopp.test` and `hopp.expect` Testing Framework Comprehensive testing API with custom assertions and Chai.js-powered BDD assertions for advanced API testing. ### `hopp.test(testName: string, testFunction: () => void)` Creates a group of tests with a name. ```javascript theme={null} hopp.test("API Tests", () => { hopp.expect(1).toBe(1); }); ``` ### `hopp.expect(actual: any)` Returns an expectation object for assertions. Hoppscotch extends the testing framework with comprehensive Chai.js BDD assertion support, enabling advanced testing patterns with 50+ assertion methods. ```javascript theme={null} hopp.expect(value).toBe(expected); ``` #### Basic Custom Assertions ### `hopp.expect(value).toBe(expected: any)` Tests for exact equality. ```javascript theme={null} hopp.expect(1).toBe(1); ``` ### `hopp.expect(value).toBeType(type: string)` Tests for type equality. ```javascript theme={null} hopp.expect("hello").toBeType("string"); ``` ### `hopp.expect(value).toHaveLength(number: number)` Tests that a value has a specific length. ```javascript theme={null} hopp.expect([1,2,3]).toHaveLength(3); ``` ### `hopp.expect(value).toInclude(item: any)` Tests that a value includes an item. ```javascript theme={null} hopp.expect([1,2,3]).toInclude(2); ``` #### HTTP Status Code Level Assertions ### `hopp.expect(statusCode).toBeLevel2xx()` Tests that the status code is in the 2xx range. ```javascript theme={null} hopp.expect(200).toBeLevel2xx(); ``` ### `hopp.expect(statusCode).toBeLevel3xx()` Tests that the status code is in the 3xx range. ```javascript theme={null} hopp.expect(302).toBeLevel3xx(); ``` ### `hopp.expect(statusCode).toBeLevel4xx()` Tests that the status code is in the 4xx range. ```javascript theme={null} hopp.expect(404).toBeLevel4xx(); ``` ### `hopp.expect(statusCode).toBeLevel5xx()` Tests that the status code is in the 5xx range. ```javascript theme={null} hopp.expect(500).toBeLevel5xx(); ``` #### Negation Support All assertions support `.not` for negation. ```javascript theme={null} hopp.expect(1).not.toBe(2); hopp.expect("hello").not.toBeType("number"); hopp.expect([1,2]).not.toHaveLength(3); hopp.expect([1,2]).not.toInclude(3); hopp.expect(200).not.toBeLevel4xx(); ``` ## Chai.js Assertion Support Hoppscotch includes comprehensive Chai.js BDD assertion support through `hopp.expect()` for native scripts and `pm.expect()` for Postman compatibility, enabling advanced testing patterns with 50+ assertion methods. ### Type Assertions Check value types and instances: ```javascript theme={null} // Basic type checking hopp.test("Type validation", () => { hopp.expect(hopp.response.statusCode).to.be.a('number') hopp.expect(hopp.response.body.asJSON()).to.be.an('object') hopp.expect([1, 2, 3]).to.be.an.instanceOf(Array) hopp.expect(new Date()).to.be.an.instanceOf(Date) }) ``` ### Equality Assertions Test for strict and deep equality: ```javascript theme={null} hopp.test("Equality checks", () => { hopp.expect(hopp.response.statusCode).to.equal(200) hopp.expect(hopp.response.body.asJSON()).to.eql({ userId: 1, name: 'John' }) hopp.expect(hopp.response.statusCode).to.deep.equal(200) }) ``` ### Property Assertions Validate object properties and nested structures: ```javascript theme={null} hopp.test("Response structure", () => { const data = hopp.response.body.asJSON() hopp.expect(data).to.have.property('userId') hopp.expect(data).to.have.own.property('email') hopp.expect(data).to.have.nested.property('profile.name') hopp.expect(data).to.have.all.keys('id', 'name', 'email') hopp.expect(data).to.have.any.keys('id', 'name') }) ``` ### Collection and Array Assertions Validate arrays and collections: ```javascript theme={null} hopp.test("Array validation", () => { const tags = hopp.response.body.asJSON().tags hopp.expect(tags).to.have.lengthOf(3) hopp.expect(tags).to.include('nodejs') hopp.expect(tags).to.have.members(['nodejs', 'javascript', 'api']) hopp.expect(tags).to.have.ordered.members(['api', 'javascript', 'nodejs']) }) ``` ### Numeric Comparisons Perform numeric comparisons and range checks: ```javascript theme={null} hopp.test("Numeric assertions", () => { const responseTime = hopp.response.responseTime hopp.expect(responseTime).to.be.below(500) hopp.expect(responseTime).to.be.above(0) hopp.expect(responseTime).to.be.within(0, 1000) hopp.expect(3.14159).to.be.closeTo(3.14, 0.01) }) ``` ### String Assertions Validate string content and patterns: ```javascript theme={null} hopp.test("String validation", () => { const contentType = hopp.response.headers['content-type'] hopp.expect(contentType).to.include('application/json') hopp.expect(contentType).to.match(/^application\/json/) hopp.expect('hello').to.have.lengthOf(5) }) ``` ### Boolean State Assertions Check boolean values and states: ```javascript theme={null} hopp.test("Boolean checks", () => { hopp.expect(true).to.be.true hopp.expect(false).to.be.false hopp.expect(1).to.be.ok hopp.expect(null).to.be.null hopp.expect(undefined).to.be.undefined hopp.expect({}).to.exist hopp.expect([]).to.not.be.empty }) ``` ### Complex Assertion Chains Combine multiple assertions for comprehensive validation: ```javascript theme={null} hopp.test("Complex validation", () => { const data = hopp.response.body.asJSON() hopp.expect(data) .to.be.an('object') .and.have.property('userId') .that.is.a('number') .and.is.above(0) }) ``` ### Real-World Example: API Pagination ```javascript theme={null} hopp.test("Pagination metadata validation", () => { const data = hopp.response.body.asJSON() // Validate pagination structure hopp.expect(data).to.have.all.keys('items', 'page', 'total', 'hasMore') hopp.expect(data.items).to.be.an.instanceOf(Array) hopp.expect(data.items).to.have.lengthOf.at.most(50) // Validate each item data.items.forEach(item => { hopp.expect(item).to.have.all.keys('id', 'name', 'createdAt') hopp.expect(item.id).to.be.a('string') }) // Store next page cursor if (data.hasMore) { hopp.env.active.set('nextPage', String(data.page + 1)) } }) ``` ### Complete Assertion Reference **Type assertions:** * `.a(type)` / `.an(type)` - Check value type * `.instanceof(constructor)` - Check instance type **Equality assertions:** * `.equal(value)` / `.eq(value)` - Strict equality (===) * `.eql(value)` - Deep equality **Property assertions:** * `.property(name)` - Has property * `.own.property(name)` - Has own property (not inherited) * `.nested.property(path)` - Has nested property (e.g., 'a.b.c') **Collection assertions:** * `.include(value)` / `.contain(value)` - Contains value * `.members(array)` - Has members (order-independent) * `.ordered.members(array)` - Has members in order * `.keys(...keys)` - Has keys * `.lengthOf(n)` - Length equals n * `.lengthOf.at.least(n)` - Minimum length * `.lengthOf.at.most(n)` - Maximum length **Comparison assertions:** * `.above(n)` / `.gt(n)` - Greater than * `.below(n)` / `.lt(n)` - Less than * `.at.least(n)` / `.gte(n)` - Greater than or equal * `.at.most(n)` / `.lte(n)` - Less than or equal * `.within(min, max)` - Within range * `.closeTo(expected, delta)` - Approximately equal **Boolean assertions:** * `.ok` - Truthy * `.true` - Strictly true * `.false` - Strictly false * `.null` - Strictly null * `.undefined` - Strictly undefined * `.exist` - Not null or undefined * `.empty` - Empty (string, array, object) **String assertions:** * `.match(regex)` - Matches regular expression * `.string(substring)` - Contains substring **Function assertions:** * `.throw()` / `.throw(ErrorType)` - Throws error * `.respondTo(method)` - Has method **Object state assertions:** * `.extensible` - Object.isExtensible() * `.sealed` - Object.isSealed() * `.frozen` - Object.isFrozen() **Modifiers:** * `.not` - Negation * `.deep` - Deep comparison * `.own` - Own properties only * `.ordered` - Order matters * `.nested` - Nested property access * `.all` - All items/keys * `.any` - Any items/keys * `.to` / `.be` / `.is` / `.that` / `.and` / `.have` / `.with` - Language chains for readability ## `pm` Namespace - Postman Compatibility Layer Postman API compatibility for seamless migration with experimental Postman collection import support (v2.0/v2.1). The `pm` namespace provides `pm.expect()` with full Chai.js assertion support for Postman-compatible testing. **Experimental Script Import:** When importing Postman collections, Hoppscotch can now import pre-request scripts and test scripts (experimental feature requiring user consent). This enables you to migrate your existing Postman workflows including their scripting logic. ### Core APIs ```javascript theme={null} // Environment and variable management pm.environment.get(key: string): string | null pm.environment.set(key: string, value: string): void pm.environment.unset(key: string): void pm.environment.has(key: string): boolean pm.globals.get(key: string): string | null pm.globals.set(key: string, value: string): void pm.globals.unset(key: string): void pm.globals.has(key: string): boolean pm.variables.get(key: string): string | null pm.variables.set(key: string, value: string): void pm.variables.has(key: string): boolean pm.variables.replaceIn(template: string): string // Request access (read-only) pm.request.url: URL-like (toString available; additional properties may be limited initially) pm.request.method: string pm.request.headers: HoppRESTHeader[] pm.request.body: HoppRESTReqBody pm.request.auth: HoppRESTAuth // Response access (post-request only) pm.response.code: number pm.response.status: string pm.response.responseTime: number // ms pm.response.json(): Record pm.response.text(): string pm.response.headers.get(name: string): string | null pm.response.headers.has(name: string): boolean pm.response.headers.all(): HoppRESTResponseHeader[] pm.response.stream: Uint8Array // Raw response bytes // Testing integration pm.test(testName: string, testFunction: () => void): void pm.expect(actual: any): Expectation // Script context information pm.info.eventName: string // "pre-request" or "post-request" pm.info.requestName: string pm.info.requestId: string // Asynchronous requests pm.sendRequest(request: string | Object, callback: (err: any, res: any) => void): void ``` ### Postman Chai.js Assertions Use `pm.expect()` with full Chai.js BDD assertion support for Postman-compatible scripts: ```javascript theme={null} // Basic assertions pm.test("Status code is 200", () => { pm.expect(pm.response.code).to.equal(200) pm.expect(pm.response.responseTime).to.be.below(500) }) // Response body validation pm.test("Response structure", () => { const jsonData = pm.response.json() pm.expect(jsonData).to.have.property('success') pm.expect(jsonData.success).to.be.true pm.expect(jsonData.data).to.be.an('array') }) // Array validation pm.test("Array contains expected items", () => { const items = pm.response.json().items pm.expect(items).to.have.lengthOf.at.least(1) pm.expect(items).to.include('apple') pm.expect(items).to.have.members(['apple', 'banana', 'cherry']) }) // Header validation pm.test("Headers are correct", () => { pm.expect(pm.response.headers.get('content-type')).to.include('application/json') }) ``` ### Postman Response Assertions Postman-specific response validation methods: ```javascript theme={null} pm.test("Response validation", () => { pm.expect(pm.response.to.have.status(200)) pm.expect(pm.response.to.have.header('content-type')) pm.expect(pm.response.to.have.body()) pm.expect(pm.response.to.have.jsonBody()) pm.expect(pm.response.to.be.ok) // 2xx status pm.expect(pm.response.to.be.json) }) pm.test("JSON body validation", () => { pm.expect(pm.response.to.have.jsonBody('userId')) pm.expect(pm.response.to.have.jsonBody('profile.name')) pm.expect(pm.response.to.have.jsonSchema({ type: 'object', required: ['userId', 'email'], properties: { userId: { type: 'number' }, email: { type: 'string' } } })) }) ``` ### OAuth Token Handling Example ```javascript theme={null} pm.test("OAuth token handling", () => { const response = pm.response.json() const expiresIn = response.expires_in // 3600 seconds const expiryTime = Date.now() + (expiresIn * 1000) // Auto-converts number to string pm.environment.set('token_expiry', expiryTime) pm.environment.set('access_token', response.access_token) // Verify storage pm.expect(pm.environment.get('access_token')).to.equal(response.access_token) }) ``` ### PM-Specific Response Assertions The following assertions are specific to the Postman compatibility layer: * `pm.response.to.have.status(code)` - Status code check * `pm.response.to.have.header(name)` - Header existence * `pm.response.to.have.body()` - Has response body * `pm.response.to.have.jsonBody()` - JSON body exists * `pm.response.to.have.jsonBody(path)` - JSON property exists * `pm.response.to.have.jsonSchema(schema)` - Validates JSON schema * `pm.response.to.be.ok` - 2xx status code * `pm.response.to.be.success` - Alias for ok * `pm.response.to.be.json` - JSON content type ### Sending Requests The `pm.sendRequest` method allows you to send HTTP requests asynchronously from your scripts. This is useful for chaining requests or fetching data from other APIs. ```javascript theme={null} pm.sendRequest("https://postman-echo.com/get", (err, res) => { if (err) { console.log(err); } else { pm.expect(res).to.have.property('code', 200); pm.expect(res).to.have.property('status', 'OK'); } }); ``` It is recommended to use the Agent interceptor on the Web App and the Native interceptor on the Desktop App for `fetch()`, `hopp.fetch()` and `pm.sendRequest()` usages. ### Unsupported Postman Features The following Postman features are not currently supported: * `pm.visualizer` * `pm.collectionVariables` * `pm.iterationData` * `pm.execution.setNextRequest()` * Legacy patterns like global `responseBody` variable, `require()`, etc. These limitations are documented in error messages when attempting to use unsupported APIs. The supported version range for Postman collections is v2.0/v2.1. ## `pw` Namespace - Legacy Compatibility Maintained for backwards compatibility with existing scripts: ```javascript theme={null} // Legacy environment operations pw.env.get(key: string): string | null pw.env.getResolve(key: string): string | null pw.env.set(key: string, value: string): void pw.env.unset(key: string): void pw.env.resolve(template: string): string // Legacy response access pw.response.status: number pw.response.body: any pw.response.headers: HoppRESTResponseHeader[] // Legacy testing framework pw.test(testName: string, testFunction: () => void): void pw.expect(actual: any): Expectation ``` ## Cookie Object Structure Cookies are represented as objects with the following properties: ```javascript theme={null} type Cookie = { name: string // Cookie name value: string // Cookie value domain: string // Domain the cookie belongs to path: string // Path scope of the cookie (default: "/") expires?: string // Expiration date in ISO format, null for session cookies maxAge?: number // Maximum age in seconds, null if not set httpOnly: boolean // Whether cookie is HTTP-only secure: boolean // Whether cookie should only be sent over HTTPS sameSite: 'None' | 'Lax' | 'Strict' // SameSite attribute } ``` ## Usage Examples ### Environment Management ```javascript theme={null} // Set and get environment variables hopp.env.set("api_token", "abc123") const token = hopp.env.get("api_token") // Scope-specific operations hopp.env.global.set("base_url", "https://api.example.com") hopp.env.active.set("user_id", "12345") // Reset to initial values hopp.env.reset("api_token") ``` ### Request Manipulation ```javascript theme={null} // Modify request before sending hopp.request.setHeader("Authorization", "Bearer " + hopp.env.get("token")) hopp.request.setUrl("https://api.example.com/users/" + hopp.env.get("user_id")) hopp.request.setMethod("POST") ``` ### Response Testing ```javascript theme={null} hopp.test("API responds successfully", () => { hopp.expect(hopp.response.statusCode).toBeLevel2xx() hopp.expect(hopp.response.responseTime).toBe(1000) const data = hopp.response.body.asJSON() hopp.expect(data).toBeType("object") hopp.expect(data.users).toHaveLength(10) }) ``` ### Cookie Management ```javascript theme={null} // Set authentication cookie hopp.cookies.set("api.example.com", { name: "session_id", value: "abc123", domain: "api.example.com", path: "/api", expires: new Date(Date.now() + 86400000).toISOString(), // 24 hours from now maxAge: 86400, // 24 hours in seconds httpOnly: true, secure: true, sameSite: "Lax", }) // Check if cookie exists if (hopp.cookies.has("api.example.com", "session_id")) { const cookie = hopp.cookies.get("api.example.com", "session_id") hopp.env.set("session_token", cookie.value) } ``` Hoppscotch provides [ECMAScript](https://tc39.es/ecma262) APIs that can be used in writing pre-request scripts and building tests. You can enter your code and run the necessary scripts. ## The `pw` object The `pw` object provides access to request and response data and variables in your Hoppscotch instance. The `pw` object houses the following methods: ## `pw.env.set("variable", "value")` `pw.env.set()` can be used directly for quick and convenient environment variable definition. ```javascript theme={null} pw.env.set("baseURL", "https://httpbin.org"); ``` Here are some practical examples that show how you can use `pw.env.set()` to encode and decode strings with Base64: ### 1. `pw.env.set("variable", atob("value"))` Use the `atob()` function to **decode a Base64 encoded string** and set it as an environment variable. ```javascript theme={null} pw.env.set("atob", atob("SG9wcHNjb3RjaA==")); ``` ### 2. `pw.env.set("variable", btoa("value"))` Use the `btoa()` function to **encode a regular string into Base64** and set it as an environment variable. ```javascript theme={null} pw.env.set("btoa", btoa("Hoppscotch")); ``` ## `pw.env.unset("variable")` `pw.env.unset()` can be used to remove the value of the variable present in the current active environment ```javascript theme={null} pw.env.unset("baseURL"); ``` ## `pw.env.get("variable")` Retrieves the value of the selected environment's variable. Accepts an environment variable as an argument. ```javascript theme={null} pw.env.get("variable"); pw.env.get("baseURL"); ``` ## `pw.env.getResolve("variable")` Retrieves the value of the selected environment's variable recursively. Accepts an environment variable as an argument. ```javascript theme={null} pw.env.getResolve("variable"); pw.env.getResolve("baseURL"); ``` ## `pw.env.resolve("variable")` Retrieves the value of the selected environment's variable recursively. Accepts an environment variable string as an argument. ```javascript theme={null} pw.env.resolve("<><>"); pw.env.resolve("<><>"); ``` ## `pw.expect(value)` The expect method returns an expectation object, on which you can call matcher functions. The example below calls the matcher function `toBe` on the expectation object that is returned by calling `pw.expect` with the response id, `pw.response.body.id` as an argument. Use `pw.expect` directly for quick and convenient testing. Every `pw.expect` statement will generate a line on the test report. ```javascript theme={null} // This test will pass pw.expect(1).toBe(1); // This test will fail pw.expect(2).not.toBe(2); ``` ## `pw.test(name, function)` To create a group of tests, with the name as a string and fn as a callback function to write tests associated with the group. The test results will include the given name for better organization. Let's wrap expect statements with `pw.test` to the group and describe related statements. ```javascript theme={null} // This will return 4 lines on the test report, grouped under "Arithmetic operations" pw.test("Arithmetic operations", () => { const size = 500 + 500; pw.expect(size).toBe(1000); pw.expect(size - 500).toBe(500); pw.expect(size * 4).toBe(4000); pw.expect(size / 4).toBe(250); }); ``` If neither a `pw.expect` nor a `pw.test` statement is present, no test reports will be generated. ```javascript theme={null} // This will not generate any test reports (99 + 1).toBe(100); ``` ## `pw.toBe(value)` Test for exact equality using `toBe`. ```javascript theme={null} pw.expect(pw.response.body.category).toBe("Sneakers"); ``` `toBe` uses strict equality and is recommended for primitive data types. ```javascript theme={null} // These tests will fail pw.expect("hello").toBe("Hello"); pw.expect(5).toBe("5"); pw.expect([]).toBe([]); ``` ## `pw.not()` Test for negation by adding `.not` before calling the matcher function. ```javascript theme={null} // These tests will pass pw.expect(true).not.toBe(false); pw.expect(200).not.toBeLevel3xx(); ``` ## `pw.toBeLevelxxx()` There are four different matcher functions for quick and convenient testing of the http status code that is returned: * `toBeLevel2xx()` * `toBeLevel3xx()` * `toBeLevel4xx()` * `toBeLevel5xx()` For example, an argument passed to expect must be within `200` and `299` inclusive to pass `toBeLevel2xx()`. ```javascript theme={null} // These tests will pass pw.expect(204).toBeLevel2xx(); pw.expect(308).toBeLevel3xx(); pw.expect(404).toBeLevel4xx(); pw.expect(503).toBeLevel5xx(); ``` If the argument passed to `expect()` is a non-numeric value, it is first parsed with `parseInt()`. ```javascript theme={null} // This test will pass pw.expect("404").toBeLevel4xx(); ``` ## `pw.toBeType(type)` Use `.toBeType(type)` for type checking. The argument for this method should be either of the following `string`, `boolean`, `number`, `object`, `undefined`, `bigint`, `symbol`, or `function`. ```javascript theme={null} // These tests will pass pw.expect(5).toBeType("number"); pw.expect("Hello, world!").toBeType("string"); pw.expect(5).not.toBeType("string"); pw.expect("Hello, world!").not.toBeType("number"); ``` ## `pw.toHaveLength(number)` Use `.toHaveLength(number)` to check that an object has a `.length` property and it is set to a certain numeric value. ```javascript theme={null} // These expectations will pass pw.expect("hoppscotch").toHaveLength(10); pw.expect("hoppscotch").not.toHaveLength(9); pw.expect(["apple", "banana", "coconut"]).toHaveLength(3); pw.expect(["apple", "banana", "coconut"]).not.toHaveLength(4); ``` ## `pw.toInclude(value)` Use `.toInclude(value)` to check that a string/array has a value entry. ```javascript theme={null} // These expectations will pass pw.expect("hoppscotch").toInclude("hopp"); pw.expect("hoppscotch").not.toInclude("scotch"); pw.expect(["apple", "banana", "coconut"]).toInclude("banana"); pw.expect(["apple", "banana", "coconut"]).not.toInclude("grape"); ``` ## `pw.response` Assert response data by accessing the `pw.response` object. ```javascript theme={null} // This test will pass pw.test("Response is ok", () => { pw.expect(pw.response.status).toBe(200); }); ``` Currently supports the following response values: * `status`: -number- The status code as an integer. * `headers`: -object- The response headers. * `body`: -object- the data in the response. In many requests, this is the JSON sent by the server. ### Setting Environment Variables from API Responses By following these steps, you can store data from one API response and access it later using Environment Variables, making it available for use in subsequent API calls. Assume in this example that the payload returns `access_token` and `id_token` as part of a JSON response. 1. Create Environment Variables without setting their values initially. For example: * `idToken` * `accessToken` 2. In the "Tests" tab of the first API request (that returns the tokens), add the following code: ```javascript theme={null} const jsonData = pw.response.body; // Save the JSON payload response pw.env.set("accessToken", jsonData.access_token); // Set "accessToken" to the value of "access_token" in the response pw.env.set("idToken", jsonData.id_token); // Set "idToken" to the value of "id_token" in the response ``` 3. Use these Environment Variables in subsequent API calls within the same collection using the `<>` syntax as usual. Read about pre-request scripts. Read about post-request tests. Read about environments. # Shortcuts Source: https://docs.hoppscotch.io/documentation/features/shortcuts Browse the full list of keyboard shortcuts in Hoppscotch for sending requests, navigating tabs, managing collections, and switching views. You can improve your workflow by efficiently performing actions straight from your keyboard. Bring up the shortcuts sidebar on Hoppscotch using `Ctrl/Cmd` + `/`. ## General shortcuts | Shortcut | Action | | ---------------- | --------------------- | | `?` | Help menu | | `K` | Search & command menu | | `Ctrl/Cmd` + `/` | Keyboard Shortcuts | | `esc` | Close current menu | ## Request shortcuts | Shortcut | Action | | -------------------- | ------------------------------------- | | `Ctrl/Cmd` + `enter` | Send request | | `Ctrl/Cmd` + `S` | Save to collections | | `Ctrl/Cmd` + `U` | Generate and copy request link | | `Ctrl/Cmd` + `I` | Reset Request to `echo.hoppscotch.io` | | `Alt/Option` + `↑` | Select Next method | | `Alt/Option` + `↓` | Select Previous method | | `Alt/Option` + `G` | Select GET method | | `Alt/Option` + `H` | Select HEAD method | | `Alt/Option` + `P` | Select POST method | | `Alt/Option` + `U` | Select PUT method | | `Alt/Option` + `X` | Select DELETE method | ## Response shortcuts | Shortcut | Action | | ---------------- | --------------------------- | | `Ctrl/Cmd` + `J` | Download response as a file | | `Ctrl/Cmd` + `.` | Copy response to clipboard | ## Navigation shortcuts | Shortcut | Action | | ------------------ | ------------------------ | | `Ctrl/Cmd` + `←` | Go back to previous page | | `Ctrl/Cmd` + `→` | Go forward to next page | | `Alt/Option` + `R` | Go to REST page | | `Alt/Option` + `Q` | Go to GraphQL page | | `Alt/Option` + `W` | Go to Realtime page | | `Alt/Option` + `S` | Go to Settings page | | `Alt/Option` + `M` | Go to Profile page | ## Miscellaneous shortcuts | Shortcut | Action | | ---------------- | --------------------------- | | `Ctrl/Cmd` + `M` | Invite people to Hoppscotch | # Code Snippets Source: https://docs.hoppscotch.io/documentation/features/snippets Generate ready-to-use code snippets for your API requests in JavaScript, Python, Shell, and other languages directly from Hoppscotch. Code snippets allows you to rapidly build your API integration in a variety of languages and frameworks. ## Generate code snippets To generate a code snippet for your API, locate the **Code Generate** `<>` icon in the right sidebar, alongside collections, environments, and history. Then, select the language in which you prefer to receive your API request. ## Copy code snippets Choose the language and framework you want to generate the code snippet for and click the "**Copy**" button to copy the code snippet to your clipboard. ## Supported languages * Shell * Javascript * Node * C * Java * PHP * Objective-C * Swift * Python * Ruby * C# * Go * OCaml ## Preview request setup 1. Open the "**Generate Code**" tab from the sidebar. 2. Click on the drop-down to select the language. 3. Select "**HTTP - HTTP 1.1 Request String**" from the language list. This displays the current request setup in HTTP 1.1 Request String syntax. # Spotlight Source: https://docs.hoppscotch.io/documentation/features/spotlight Use the Spotlight search and command palette in Hoppscotch to quickly navigate features, switch tabs, and execute actions with keyboard shortcuts. Press   ⌘ + K   anytime to open Spotlight. Spotlight is an innovative feature introduced in Hoppscotch, designed to enhance your interaction with the application. By utilizing Spotlight, you can efficiently navigate through various functionalities and perform tasks swiftly. ## Activation To activate the Spotlight search functionality, you can employ the following key combinations based on your operating system: * On macOS: Press `Cmd` + `K` * On Windows or Linux: Press `Ctrl` + `K` ## Spotlight Interface Upon triggering the Spotlight search, a search field will be displayed, allowing you to provide input. As you type, relevant suggestions will dynamically appear, aiding in quickly finding desired functionalities. ## Navigation and Selection Spotlight not only offers dynamic suggestions but also facilitates their navigation and selection. The presented suggestions are ranked by relevance, enabling you to easily identify your desired options. Navigation can be achieved through: * Arrow keys: Use the arrow keys to move through the suggestions. * Enter key: Press the Enter key to select the highlighted suggestion. Alternatively, you can achieve the same functionality using the mouse or trackpad. Spotlight revolutionizes the user experience within Hoppscotch by streamlining various tasks and reducing unnecessary clicks. With Spotlight, you can accomplish the following tasks more efficiently: * Navigate to any page within the app. * Search and find requests in your collections. * Create, edit, and quickly switch workspaces and environments. * Rename, save, and send requests. # Variables Source: https://docs.hoppscotch.io/documentation/features/variables Use global, environment, request, and collection variables in Hoppscotch to create dynamic, reusable values across your API requests. Hoppscotch provides you the ability to create and use variables throughout the app. This helps you reuse values throughout Hoppscotch just by invoking the variable name. Hoppscotch considers an object within angular brackets as a variable, e.g. `<>`. ## Variable Scopes Hoppscotch provides you different variables scopes, allowing you to use different scopes for different contexts. 1. **Global Variables:** can be accessed throughout Hoppscotch and has the broadest scope of all variables. 2. **Environment Variables:** allow your variables to be scoped to an environment. Environment variables are useful when you have the same set of variables for two environments such as production and staging. 3. **Request Variables:** are scoped to just an individual request, request variables are useful when you want to use variables in your URL path or when you want to embed a variable URL. 4. **Predefined Variables:** are automatically generated at runtime and can be accessed globally throughout Hoppscotch using the `$` symbol, such as `$guid` or `$timestamp`. 5. **Collection Variables:** are scoped to individual collection and child folders, perfect for sharing base URLs, tokens and defaults across a set of requests without leaking to other workspaces. The scope of each variable can be identified from the color of the variable name. If a variable with the same name exists, it is resolved in the order of priority. | Variable Scope | Color | Priority | | -------------- | ----- | -------- | | Request | 🟠 | 1 | | Collection | 🟣 | 2 | | Predefined | 🟡 | 3 | | Environment | 🟢 | 4 | | Global | 🔵 | 5 | | Non resolvable | 🔴 | - | ## Types of Variables 1. **A regular variable**: allows users to reference the variable throughout Hoppscotch, and anyone can see the value associated with the variable. In a workspace, regular environment variable-value pairs will be synced to the server, making them available to all workspace members. However, you have the option to choose whether to sync a regular variable value present in your personal workspace. 2. **A secret variable:** enables users to specify secrets and reference the values as variables. The values of secret variables in any workspace will never be synced to the server or shared with any workspace members. It is expected that in a collaborative workspace the user will populate the value of the variable at runtime. All secret variable values in Hoppscotch will be masked using asterisks (\*\*\*). Secret Variables cannot be scoped to a request and can only be scoped in an environment or globally. Secret variables values will not be exported when an environment is exported. 3. **A predefined variable:** is automatically generated at runtime and provides dynamic, context-specific data. Predefined variables are available throughout your requests and responses and are useful for incorporating system-level information or dynamic values into your API interactions without manual configuration. All predefined variables are accessible throughout Hoppscotch and can be retrieved using the `$` symbol. Below is the list of predefined variables whose values are dynamically generated during the request or collection run: > | **Variable Name** | **Description** | **Example** | > | ----------------- | --------------------------------------------------------------------------------------------- | -------------------------------------- | > | `$guid` | A v4 style unique (GUID) identifier for each request. | `123e4567-e89b-12d3-a456-426614174000` | > | `$timestamp` | The current UNIX timestamp in seconds | `1693047645` | > | `$isoTimestamp` | The current date and time in ISO-8601 format at zero UTC (also known as "Zulu time" or UTC-0) | `2024-09-25T00:00:00.000Z` | > | `$randomUUID` | A random 36-character UUID. | `6929bb52-3ab2-448a-9796-d6480ecad36b` | > > ### Numbers, Text, and Colors > > | **Variable Name** | **Description** | **Example** | > | --------------------- | ------------------------------------------------------------------------ | ----------------------- | > | `$randomAlphaNumeric` | A random alpha-numeric character. | `A9X1Z3` | > | `$randomBoolean` | A random boolean value. | `true` , `false` | > | `$randomInt` | A random integer value between 0 and 1000. | `29` , `432` , `786` | > | `$randomColor` | A random color amongst **red, green, blue, yellow, purple, and orange.** | `yellow` | > | `$randomHexColor` | A random hex value. | `#f2a729` | > | `$randomAbbreviation` | A random abbreviation. | `SQL` , `JSON` , `HTML` | > > ### Internet and IP addresses > > | **Variable Name** | **Description** | **Example** | > | ------------------- | ---------------------------------------------- | ----------------------------------------- | > | `$randomIP` | A random IPv4 address | `192.168.0.101` | > | `$randomIPV6` | A random IPv6 address | `2001:0db8:85a3:0000:0000:8a2e:0370:7334` | > | `$randomMACAddress` | A random MAC address. | `00:1B:44:11:3A:B7` | > | `$randomPassword` | A random 15-character alpha-numeric password. | `H8w72Sx93KlqA1b` | > | `$randomLocale` | A random two-letter language code (ISO 639-1). | `en`, `fr`, `es` | > | `$randomUserAgent` | A random user agent. | `Mozilla/5.0 (Windows NT 10.0; Win64)` | > | `$randomProtocol` | A random internet protocol. | `https`, `ftp` | > | `$randomSemver` | A random semantic version number. | `1.2.3` | > > ### Names > > | **Variable Name** | **Description** | **Example** | > | ------------------- | --------------------- | --------------------------------------------------- | > | `$randomFirstName` | A random first name. | `Ethan` , `Chandler`, `John` | > | `$randomLastName` | A random last name. | `Schaden` , `Schneider` , `Doe` | > | `$randomFullName` | A random Full name. | `Ethan Schaden` , `Chandler Schneider` , `John Doe` | > | `$randomNamePrefix` | A random name prefix. | `Dr.` , `Miss.` , `Prof.` | > | `$randomNameSuffix` | A random name suffix. | `MD` , `PhD` , `Jr.` | > > ### Addresses and Profession > > | **Variable Name** | **Description** | **Example** | > | ---------------------- | ------------------------ | -------------------------------------------------- | > | `$randomCity` | A random city name. | `New York` , `Houston` , `Philadelphia` | > | `$randomJobArea` | A random job area. | `Intranet` , `Development` , `Testing` | > | `$randomJobDescriptor` | A random job descriptor. | `Corporate` , `Lead` , `Principal` | > | `$randomJobTitle` | A random job title. | `Global Branding Officer` , `Productivity Analyst` | > | `$randomJobType` | A random job type. | `Manager` , `Coordinator` , `Director` | Choose the environment that aligns best with your development workflow. # Widgets Source: https://docs.hoppscotch.io/documentation/features/widgets Embed Hoppscotch widgets in your website as shareable links, buttons, or interactive embeds so visitors can try your API requests directly. Widgets are small, interactive components that can be embedded in HTML pages to provide a seamless experience for your audience. Hoppscotch offers three types of widgets: links, buttons, and embeds. ## Links Links are the most basic type of widget. They are simply a URL that can be shared with others. You can generate links to your requests in three different formats: raw, HTML, and Markdown. ## Buttons Buttons are a more advanced type of widget. They are a link that can be embedded in HTML or Markdown files. You can customize the button's appearance and behavior to suit your needs. You can also generate buttons in two different formats: HTML and Markdown. ## Embeds Embeds are the most advanced type of widget. They are a mini version of Hoppscotch that can be embedded in an HTML page, enabling your audience to interact seamlessly with your API request. You can customize the embed's appearance and behavior to suit your needs. ## Shared requests Sharing a request does not provide others with access to your request. Instead, it generates a link that can be shared with others. It's important to note that if a shared request contains any environment variables, proper functionality may be compromised unless the recipient has access to the same environment variables. Therefore, it is advisable to share requests that do not contain environment variables or replace any environment variables with their corresponding values before sharing. ### Create a shared request: #### Sharing a request in a collection: 1. Right-click on a saved request within a collection and select "**Share Request**". 2. Choose between link, button, and embed widgets. 3. Click on the "**Create**" button. 4. Copy the share link. #### Sharing a request in workspace: 1. Click on the "**Share request**" button in drop-down menu next to the "**Save**" button. 2. Choose between link, button, and embed widgets. 3. Click on the "**Create**" button. 4. Copy the share link. ### View your shared requests: 1. Click on the "**Shared Requests**" button in the sidebar. 2. You will see a list of all your shared requests. 3. Click on the request to open it in a new tab. 4. You can also customize the widget, copy the link, or delete the shared request by right-clicking on it or the 3-dot menu. # Workspaces Source: https://docs.hoppscotch.io/documentation/features/workspaces Organize your requests, collections, and environments into different workspaces. You can also invite other users to your workspace to collaborate. Once you are logged into Hoppscotch, you can toggle between multiple workspaces to organize your workflow. You can choose between your workspace titled "**Personal Workspace**" or create a workspace for your teams so that you can collaborate. Currently, organizing requests across multiple shared workspaces is limited to RESTful protocol. GraphQL and Realtime APIs are available only in the personal workspace and are not supported for collaboration in shared workspaces. ## Create a workspace To create a workspace, click on the **"+"** icon on the top right corner of the workspace switcher. Alternatively, you can also click on the "**Create new workspace**" button on the "[Profile](https://hoppscotch.io/profile)" page under the "**Workspaces**" section. Creating a workspace makes you the owner of the workspace. You can invite other users to the workspace and assign them roles. ## Invite users to a workspace To invite users to a workspace, click on the "**Invite**" button and enter the email address of the user you want to invite. You can invite multiple users at once by adding the email addresses in the input field. ## Switch between workspaces To switch between workspaces, click on the workspace switcher in the top right corner of the app and select the workspace you want to switch to. ## Edit a workspace You can only edit a workspace if you are the owner of the workspace. ### Rename a workspace To rename a workspace, click on the workspace settings button on the top right corner of the app. Then click on the workspace name and enter the new name. ### Remove a user from a workspace To remove a user from a workspace, click on the workspace settings button on the top right corner of the app. Then click on the "**Delete**" button on the user you want to remove from the workspace. ### Leave a workspace To leave a workspace, click on the workspace settings button on the top right corner of the app. Then click on the "**Delete**" button on the workspace you want to leave. You can only leave a workspace if you are not the owner of the workspace. If you are the owner of the workspace, you will have to delete the workspace to leave it. Alternatively, you can also transfer the ownership of the workspace to another user and then leave the workspace. ### Change member role There are three types of roles for members in a workspace: * **Owner**: The owner of the workspace has full access to the workspace and can invite other users to the workspace. The owner can also delete the workspace. * **Editor**: The editor of the workspace has edit access to the workspace and can create, edit, and delete collections, environments, and requests in the workspace. * **Viewer**: The viewer of the workspace has read-only access to the workspace and can only view the collections, environments, and requests in the workspace. To change the role of a member in a workspace, click on the workspace settings button on the top right corner of the app. Then click on the "**Role**" drop-down on the user you want to change the role of. Then select the role you want to assign to the user then click "**Save**". ### Delete a workspace To delete a workspace, click on the "**Delete**" button on the workspace you want to delete on the "[Profile](https://hoppscotch.io/profile)" page under the "**Workspaces**" section. # Hoppscotch Clients Source: https://docs.hoppscotch.io/documentation/getting-started/clients Explore the Hoppscotch clients available on web, desktop, and CLI. Learn about the user interface and how to navigate the platform. Hoppscotch has multiple clients that you can use to develop and test your APIs. You can use Hoppscotch on the web, desktop, and terminal. ## Navigating Hoppscotch Interface ## Understanding the user interface Hoppscotch has a simple and intuitive UI. The UI is divided into multiple sections: ### Topbar The top bar is where you can find the search, login, workspace selector, and more. ### Menu The menu is where you will find the different platforms that Hoppscotch offers and switch between them. You can also access the settings page from the menu. ### Sidebar The sidebar is where you can see additional features depending on the platform you are working on. The sidebar houses features like history and collections. ### Main The main panel is where you will spend most of your time. This is where you will create and send requests and view the responses. ### Footer The footer houses the status bar. The status bar allows you to toggle the sidebar, go full screen, get help and support, and more. # Running a simple query Source: https://docs.hoppscotch.io/documentation/getting-started/graphql/creating-a-query Connect to a GraphQL server in Hoppscotch, explore the schema documentation, and run your first query step by step with a real API endpoint. ## Connecting to a GraphQL server Switch to the GraphQL platform on Hoppscotch and connect to the below GraphQL server. ``` https://echo.hoppscotch.io/graphql ``` Once a successful connection has been made, you can view both **documentation** and the **schema** using Hoppscotch. It is important to explore the schema to understand the different **queries, mutations, types, and subscriptions** that are offered by the endpoint. ## Running the query You can execute queries to retrieve data from the GraphQL server by following these steps: * Open the **Documentation** panel to explore the available queries for the endpoint. * Click on `query` under **Root Types** to view the listed query fields. * Click the **"+"** button next to a query field to add it to the Query editor with a structured template. * Expand the query by clicking on it, then use the **"+"** button to add specific fields, arguments, or filters. * Customize the query as needed by modifying fields, adding arguments, or setting variables directly in the Query editor. ## Fetching Countries Data Let's explore a sample query using the Countries GraphQL API. 1. Open Hoppscotch, switch to the [GraphQL client](https://hoppscotch.io/graphql) and connect to the endpoint below: ``` https://countries.trevorblades.com/graphql ``` 2. Explore the schema and documentation to understand more about the endpoint. 3. Select the `countries` query, cherry-pick the fields, and add a filter to return results where the `name` field is equal to **"Germany"**. ```graphql theme={null} { countries (filter: {name: {eq: "Germany"}}) { name code capital emoji currencies } } ``` 4. Click on the run button to execute the query. 5. The query will return the following response. ```json theme={null} { "data": { "countries": [ { "name": "Germany", "code": "DE", "capital": "Berlin", "emoji": "🇩🇪", "currencies": [ "EUR" ] } ] } } ``` # Using variables in a GraphQL query Source: https://docs.hoppscotch.io/documentation/getting-started/graphql/using-variables Pass dynamic variables in your GraphQL queries using Hoppscotch. Follow a step-by-step example to filter country data with query variables. Hoppscotch allows you to pass variables in the query to fetch data dynamically. To demonstrate the use of variables, let's write a query to get countries by their `name` and `continent`. For example, we will fetch the details of **"Bahrain"** from the **"Asia"** continent. ## Variables Go to the variables section and define the variable. ```json theme={null} { "countryName": "Bahrain", "continentCode": "AS" } ``` ## Using the variable in the query Now create a query `getCountries` with variables as shown below: ```graphql theme={null} query getCountries($countryName: String!, $continentCode: String!) { countries(filter: {name: {eq: $countryName}, continent: {eq: $continentCode}}) { name continent { name } code emoji currencies } } ``` Hoppscotch will retrieve the value of the variable and execute the query to get the below response. ```json theme={null} { "data": { "countries": [ { "name": "Bahrain", "continent": { "name": "Asia" }, "code": "BH", "emoji": "🇧🇭", "currencies": [ "BHD" ] } ] } } ``` # Introduction to Hoppscotch Source: https://docs.hoppscotch.io/documentation/getting-started/introduction Hoppscotch is an open-source API development ecosystem with web, desktop, and CLI clients for building, testing, and debugging APIs. Hoppscotch is an open-source API development ecosystem. Available offline, on-prem, and on the cloud with Web, Desktop, and CLI apps. Built from the ground up with ease of use and accessibility in mind, providing all the functionality needed for developers with a minimalist, unobtrusive UI. Source code is open and auditable. Built with privacy and security in mind. Works on Web, Mac, Windows, Linux, and CLI. No installation is required. Host Hoppscotch on your own server and use it with your team. Built with performance in mind and designed to be seamless and instant. Built on top of open source technologies by the community, for the community. Have all your teams in one place and collaborate on your APIs with ease. Designed to be intuitive and easy to use with keyboard shortcuts. Built with security in mind and designed to be safe and secure. # Quick start Source: https://docs.hoppscotch.io/documentation/getting-started/quick-start Get started quickly with Hoppscotch Cloud, self-hosted editions, or the desktop app. Choose your platform and begin testing APIs in minutes. ## Platforms ### Hoppscotch Cloud Hoppscotch Cloud is our hosted API development and testing platform that allows you to share your APIs with your team with ease. No need to worry about hosting, scaling, and maintenance. Hoppscotch Cloud is built for individuals and teams. [Get started for free on Hoppscotch Cloud](https://hoppscotch.io) ### Hoppscotch Self-Host For full data ownership and control over your API development and testing, you can self-host Hoppscotch on your infrastructure. Hoppscotch Community Edition is free and open-source. It is licensed under the MIT License. You can use it for personal and commercial projects. It is a great choice for individuals and small teams. SAML-based SSO, on-prem deployment, audit logs, and more. Hoppscotch Enterprise Edition is a self-hosted version of Hoppscotch Cloud with enterprise-ready features for teams and organizations. Hoppscotch Enterprise Edition is available for on-premise deployment with priority support. [Contact Hoppscotch Support](/support/getting-started/contact) *** ## Solutions ### Hoppscotch Web App The easiest way to get started with Hoppscotch is with our hosted cloud plan. Get unlimited collections with no limits and all of our features are built for individuals and teams. [Open Hoppscotch Web App](https://hoppscotch.io) ### Hoppscotch Desktop App Hoppscotch Desktop App is a cross-platform desktop application built with Tauri and Hoppscotch Web Client. It is a standalone version of Hoppscotch that can be installed on your computer and used without a browser. Hoppscotch Desktop App is available for Mac, Windows and Linux. [Download Hoppscotch Desktop App](https://hoppscotch.com/download) ### Hoppscotch CLI Hoppscotch CLI is a command-line tool that allows you to run Hoppscotch on your terminal and CI/CD pipelines. [Install Hoppscotch CLI](/documentation/clients/cli/overview) # MQTT Source: https://docs.hoppscotch.io/documentation/getting-started/realtime/mqtt Connect to an MQTT broker in Hoppscotch to publish messages, subscribe to topics, and test lightweight publish-subscribe messaging. ## Connect to an MQTT server 1. Enter the MQTT server "**URL**" and click on "**Connect**". ``` wss://test.mosquitto.org:8081 ``` 2. Check the log to see if the connection was successful or not. 3. To test your server add messages under a topic and publish it. 4. Other devices in the server that have subscribed to the topic will get your messages. 5. You can receive messages by subscribing to a topic that another device in the server transmits. 6. Monitor the log for results. ## Sending messages Write your message in the "**Message**" input field under the "**Communication**" tab and click on the "**Publish**" button. Type in the "**Topic**" input field to send a message with a topic. The message you send will be displayed on the "**Logs**" pane. ## Subscriptions Click on the "**New Subscription**" button to add a new subscription. Enter the topic name and click on the "**Subscribe**" button to subscribe to the topic. The messages you receive will be displayed on the "**Logs**" pane. ## Troubleshooting 1. Make sure you enter a valid MQTT URL, they always start with the protocol format `ws://`. 2. Do not add invalid/incorrect authorization tokens before you connect to an MQTT server. # Socket.IO Source: https://docs.hoppscotch.io/documentation/getting-started/realtime/socket-io Test Socket.IO services in Hoppscotch by connecting to a server, listening to events, and sending messages with custom event names. The Hoppscotch Socket.io testing tool lets you test out your socket.io services. ## Connect to a socket.io server 1. Add the "**URL**", "**path**" and click on "**Connect**". 2. Listen to events broadcasted by the server, shown in the log. 3. Use the sidebar to add an event name and send messages to the server. ## Sending messages Write your message in the "**Message**" input field under the "**Communication**" tab and click on the "**Send**" button. Type in the "**Event**" input field to send a message with an event name. The message you send will be displayed on the "**Logs**" pane. ## Troubleshooting 1. Make sure you enter a valid socket.io URL, they always start with the protocol format `ws://`. 2. Do not add an invalid/incorrect authorization token before you connect to a socket.io server. # Server-Sent Events Source: https://docs.hoppscotch.io/documentation/getting-started/realtime/sse Server-Sent Events (SSE) is a server push technology enabling a client to receive automatic updates from a server via HTTP connection. The Hoppscotch SSE testing tool lets you test out your SSE services. ## Connect to an SSE server 1. Add the SSE "**URL**" and "**path**" and click on "**Connect**". 2. Choose the event type that you want to subscribe to and connect. 3. Messages from the SSE server will be continuously updated in the log until either the server or client (you) terminates the connection. ## Listening to events The events sent by the server will be displayed in the log pane. ## Troubleshooting 1. Make sure you enter valid SSE URLs, they always start with the protocol format `http://` or `https://`. 2. Make sure the server is sending the correct event type. # Websocket Source: https://docs.hoppscotch.io/documentation/getting-started/realtime/websocket Connect to a WebSocket server in Hoppscotch, send and receive real-time messages, and troubleshoot common connection issues step by step. Enter your WebSocket "**URL**", valid protocols, and click on "**Connect**". You can also disconnect from the WebSocket by clicking on the "**Disconnect**" button. ## Sending messages Write your message in the "**Message**" input field under the "**Communication**" tab and click on the "**Send**" button. The message you send will be displayed on the "**Logs**" pane. ## Troubleshooting 1. Make sure you enter a valid WebSocket URL, they always start with the protocol format `ws://`. 2. Do not add invalid/blank protocol before you connect to a WebSocket. # Using auth tokens Source: https://docs.hoppscotch.io/documentation/getting-started/rest/auth-tokens Authenticate API requests in Hoppscotch using bearer tokens. Follow a step-by-step tutorial with the GitHub REST API as an example. In this section, we'll look at passing Authorization and Authentication information in our requests, by accessing the [GitHub REST API](https://docs.github.com/en/rest). Let's try making a `GET` request to the URL `https://api.github.com/user`. You'll get the following response: ```json theme={null} { "message": "Requires authentication", "documentation_url": "https://docs.github.com/rest/reference/users#get-the-authenticated-user" } ``` This is because you are not authorized to access the API and to gain access you would need to authenticate yourself. We use tokens to authenticate a user and to do so we first need to generate an access token from GitHub. ## Generating access token To get access to the GitHub API, you first need to generate a personal access token. For our demonstration, we will generate one granting access to public repositories. 1. Login to the GitHub account. 2. Go to your [personal access tokens page](https://github.com/settings/tokens) and click on "**Generate new token**". 3. Select tokens (classic). 4. Specify the note as "**Hoppscotch API**" so that you can remember why you created it. 5. Under the "Select scopes" section only check `public_repo`. 6. Scroll down and click on "**Generate token**". 7. You just generated your access token, now copy the token to your clipboard. ## Storing auth token in a variable It is a recommended safe practice to have your auth details in environment variables rather than inputting them directly to the authorization tab. 1. Click on the "**Global**" environment to add a variable. 2. Create a variable called `token` and paste the token from GitHub as its value. 3. Now open the Authorization tab and select `Bearer` from the dropdown list. 4. Input the token as shown below, make sure that you reference the token in variable format, i.e. `<>`. 5. Click on "**Send**". You should now see the response including details about your GitHub account. # Creating a request Source: https://docs.hoppscotch.io/documentation/getting-started/rest/creating-a-request Create your first REST API request in Hoppscotch. Choose an HTTP method, enter an endpoint URL, and send a request to see the response. The RESTful protocol is the default protocol that is active when you open Hoppscotch. Hoppscotch allows you to make API requests and examine the responses. You can enter the API endpoint and choose the HTTP method according to your needs from the dropdown menu. Once it is configured, click on the "**Send**" button and you will see the response returned by the server. It's that simple. Now try it yourself, copy the below API endpoint, and create a request. ``` https://echo.hoppscotch.io ``` Let's try another API. We'll be using the [Pokemon API](https://github.com/PokeAPI/pokeapi). Go ahead and create a `GET` request to the endpoint below: ``` https://pokeapi.co/api/v2 ``` If your request was successful, then you should get a JSON response as shown below: ```json theme={null} { "ability": "https://pokeapi.co/api/v2/ability/", "berry": "https://pokeapi.co/api/v2/berry/", "pokedex": "https://pokeapi.co/api/v2/pokedex/", "pokemon": "https://pokeapi.co/api/v2/pokemon/", "version-group": "https://pokeapi.co/api/v2/version-group/" } ``` The Pokemon API has returned several new API endpoints or URLs, let's pick the character's URL and explore it. To explore the characters create a `GET` request to the URL `https://pokeapi.co/api/v2/pokemon` by copy-pasting the URL below: ``` https://pokeapi.co/api/v2/pokemon ``` The API should have returned a huge amount of data, something similar to the one below: ```json theme={null} { "count": 1279, "next": "https://pokeapi.co/api/v2/pokemon?offset=20&limit=20", "previous": null, "results": [ { "name": "bulbasaur", "url": "https://pokeapi.co/api/v2/pokemon/1/" }, { "name": "ivysaur", "url": "https://pokeapi.co/api/v2/pokemon/2/" }, ] } ``` Try experimenting with the `/pokedex`, `/berry`, and the other endpoints as well. Learn more about RESTful protocol. # Environment variables Source: https://docs.hoppscotch.io/documentation/getting-started/rest/environment-variables Store and reuse values like base URLs and API keys with environment variables in Hoppscotch. Create environments and reference variables. Environment variables allow you to store and reuse values in your requests and scripts. By storing a value in a variable: * You can reference it throughout your request section. * You can change its value by updating it in a single place. * You increase your ability to work efficiently and minimize the likelihood of errors. ## Adding environment variables You can create a new environment by clicking the environments icon on the sidebar and clicking the `new` button. Let's label the environment as `Pokemon Envs`. Now, let's create an environment variable called `baseURL` pointing to `https://pokeapi.co/api/v2`. Similarly, you can create multiple environments and environment variables. ## Accessing environment variable If you have more than one environment, select the environment whose variables you want to access. You can access the variables in the request section by referencing the variable in the following format `<>`, in our case the variable will be `<>` and the complete URL will be `<>/pokemon/ditto`. You can add your variables to the `Global` environment, which can be accessed globally, i.e., in every other environment. # Organizing requests Source: https://docs.hoppscotch.io/documentation/getting-started/rest/organizing-requests Save and organize API requests into collections in Hoppscotch for easy reuse, team collaboration, and structured project management. It is always best practice to organize your requests when you test multiple API endpoints. You can organize your requests categorically for future reference or collaboration with your team using collections. You can create a new collection on Hoppscotch by clicking the collections icon on the sidebar and clicking the "**+ New**" button. Let's try making a collection for our [Pokemon API](https://github.com/PokeAPI/pokeapi) called `Pokemon API`. ## Adding requests to a collection Now, let's save our current query as `GET three Pokemon` and save it in our `Pokemon API` Collection. 1. Click on the "**Save**" button. 2. Give your request a name. 3. Add it to your collection. You can add multiple requests to a collection and even create subfolders inside a collection to further organize your requests. # Pre-request scripts Source: https://docs.hoppscotch.io/documentation/getting-started/rest/pre-request-scripts Add pre-request scripts in Hoppscotch to execute JavaScript before sending API requests. Set variables, generate tokens, and add logic. ## Scripts Hoppscotch lets you add dynamic behavior to REST API requests. This allows you to write test suites and build requests that can contain dynamic parameters. You can add [ECMAScript](https://tc39.es/ecma262) code that executes based on events in the flow: * Pre-request scripts are executed before a request is sent to the server. * You can add multiple pre-request scripts to a request. * You can add pre-request scripts to both requests saved and not saved in a collection. Hoppscotch will then execute the scripts along with the requests in the specified order. ## Pre-request script Pre-request script is a piece of code that will run before the execution of the request. You can use the pre-request script for a pre-processing task such as: * Setting parameters, headers. * Adding body data. * Adding variable values. * Including timestamps in request headers. ## Writing pre-request scripts Hoppscotch provides a special `pw` object containing various methods to create scripts and tests. The `pw` object is global and can be referenced by name to access methods. For example, to set an environment variable, you can use the `pw.env.set()` method. ```javascript theme={null} pw.env.set("variable", "value"); ``` ## Examples Let us look at some examples of how you can use Hoppscotch to write pre-request scripts. ### Setting environment variables `pw.env.set()` can be used directly for quick and convenient environment variable definition. It can be used to better organize request codes. ```javascript theme={null} pw.env.set("baseURL", "https://httpbin.org"); pw.env.set("method", "get"); ``` Go to the pre-request script tab and copy-paste the above [ECMAScript](https://tc39.es/ecma262) code as shown below: These variables can be accessed in the request section by referencing them in double angle brackets `<>`. So the URL will be `<>/<>`. ### Generating random Values to test API Let us take a case where we need to test random test-user data available at an endpoint. Let us use the following GET API endpoint `https://reqres.in/api/users/`. Add `<>` to the endpoint URL. ``` https://reqres.in/api/users/<> ``` Now in the pre-request script tab add the following logic. ```javascript theme={null} var random = Math.floor(Math.random() * 10); pw.env.set("randomValue", random.toString()); ``` The [ECMAScript](https://tc39.es/ecma262) code will assign a random number to the environment variable `randomValue` and the API will return a random user associated with the random value. You will get a similar response as shown below: ```json theme={null} { "data": { "id": 4, "email": "eve.holt@reqres.in", "first_name": "Eve", "last_name": "Holt", "avatar": "https://reqres.in/img/faces/4-image.jpg" }, "support": { "url": "https://reqres.in/#support-heading", "text": "To keep ReqRes free, contributions towards server costs are appreciated!" } } ``` # Request headers Source: https://docs.hoppscotch.io/documentation/getting-started/rest/request-headers Set and manage HTTP request headers in Hoppscotch to pass authorization, content type, caching, and other key-value metadata with requests. Request Headers are key-value pairs that the client sends to the server with an HTTP request. These headers carry extra details about your request, helping the server understand its context and tailor the response to fit. ## Headers Tab In Hoppscotch, you can easily set and manage request headers using the **Headers tab**. This tab allows you to define **`key-value`** pairs, and you can also add a **`description`** for each header to keep track of its purpose. Here are a few common headers you might set: | **Header** | **Description** | | ----------------- | ----------------------------------------------------------------------------------------- | | **Authorization** | Used for passing credentials, such as tokens, to authenticate the client with the server. | | **Content-Type** | Indicates the format of the data being sent, like `application/json`. | | **Accept** | Tells the server what media types the client can handle in the response. | | **Cache-Control** | Controls caching behavior in both requests and responses. | | **User-Agent** | Provides information about the client making the request. | When the **Authorization and Content-Type** values are set through their respective sections, the description fields in their auto-generated headers are disabled for manual input, leaving the value empty. In contrast, for **Inherited** headers, the specified values are automatically populated in the description fields. Hoppscotch offers a variety of header options beyond these five examples, allowing you to customize how the server processes your requests to meet specific requirements. ### Bulk edit request headers Using the **Bulk edit** feature in Hoppscotch's request headers tab, you can input and manage multiple headers simultaneously, with each header on a new line and the key and value separated by a **colon (:)**. For example, ```yaml theme={null} Authorization: Bearer token123 Content-Type: application/json # User-Agent: CustomAgent/1.0 ``` # Request parameters Source: https://docs.hoppscotch.io/documentation/getting-started/rest/request-parameters Add query parameters to API requests in Hoppscotch using the URL or the parameters tab. Filter and request specific data from endpoints. Query parameters help you to filter and request specific data from an API endpoint. You can add query parameters in two ways: 1. Add them in the URL. 2. Add them in the parameters tab. ## Adding parameters in the URL To add a parameter in the URL, append `?` at the end of the URL and add a parameter in `key=value` format. You can add multiple parameters by separating them using `&`. For example, the below URL is filtered to get the data of the first three Pokemon. ``` https://pokeapi.co/api/v2/pokemon/?offset=6&limit=3 ``` For which you will get a similar response: ```json theme={null} { "count": 1281, "next": "https://pokeapi.co/api/v2/pokemon?offset=9&limit=3", "previous": "https://pokeapi.co/api/v2/pokemon?offset=3&limit=3", "results": [ { "name": "squirtle", "url": "https://pokeapi.co/api/v2/pokemon/7/" }, { "name": "wartortle", "url": "https://pokeapi.co/api/v2/pokemon/8/" }, { "name": "blastoise", "url": "https://pokeapi.co/api/v2/pokemon/9/" } ] } ``` ## Using the parameters tab You can use the **Parameters tab** to set **`key-value`** pairs for your API requests. This tab also lets you add a **`description`** for each parameter, helping you provide a clear explanation of what each parameter does and why it's important. Hoppscotch also offers a **Bulk edit** feature, allowing you to add or modify multiple request parameters at once, with each key-value pair on a new line separated by a **colon (:)**. For example, ```yaml theme={null} param1: value1 param2: value2 # param3: value3 ``` Try using the parameters tab to see if you get the same response as adding parameters in the URL. # Response handling Source: https://docs.hoppscotch.io/documentation/getting-started/rest/response-handling Inspect API responses in Hoppscotch including HTTP status codes, JSON/HTML/XML response bodies, headers, cookies, and response time metrics. A REST API response is the data returned by the API after an application makes an HTTP request. It typically includes an HTTP status code indicating the result of the request, a response body that contains the requested data, and headers that provide metadata. The response may also include cookies set by the server. Hoppscotch uplifts this experience by providing an intuitive interface for analyzing responses, making it easier for you to visualize and interact with API data effectively. ## **Response Body** Depending on the content type of the response, Hoppscotch automatically presents the data in the appropriate format: * **JSON:** Formats the response in a structured JSON format for easy readability. * **HTML:** Renders the response as HTML for visual representation and structured content as a web page. * **XML:** Shows the response in XML format for compatibility with XML-based APIs. * **Image:** Displays image responses directly in the interface. ```json theme={null} { "name": "Hoppscotch", "type": "Open-source API Development Ecosystem", "description": "A powerful platform for developing and testing APIs with an intuitive interface.", "url": "https://hoppscotch.io" } ``` ```html theme={null} Hoppscotch API

Hoppscotch

Type: Open-source API Development Ecosystem

Description: A powerful platform for developing and testing APIs with an intuitive interface.

URL: https://hoppscotch.io

``` ```xml theme={null} Hoppscotch Open-source API Development Ecosystem A powerful platform for developing and testing APIs with an intuitive interface. https://hoppscotch.io ``` ### Raw Response The **Raw** response tab in Hoppscotch presents the unprocessed response body, allowing you to view the exact data returned by the API without any formatting which can be particularly used for debugging or when you need to inspect the original response directly. ## Response Headers Response **Headers** give you important information about the API response that goes beyond just the data itself. They include information such as the content type, which indicates the format of the response (e.g., `application/json` or `text/html`), caching directives that control how the response can be stored and reused, security settings like CORS (Cross-Origin Resource Sharing) that help manage access, and various server-related information, like the server type and version. ## Test Results The **Test Results** section displays the outcomes of any assertions made on the API response, allowing you to verify key aspects such as status codes, response times, and the presence of expected data. ## Save a response as an Example In Hoppscotch, an example connects a specific request with its response, providing a complete view of how an API behaves. Each example includes the essential request details alongside the response information. You can create multiple examples for a single request, which is valuable for illustrating how the same endpoint might respond differently under various conditions. **To save a response as an example in Hoppscotch, follow these steps:** * Navigate to the right-sidebar and select the collection with your request. * Choose the request and hit **"Send.”** * In the response section, click the **"Save as Example"** icon. * The example will be stored in the request's history in the collection for easy retrieval and reference later. * Click on the example and select **"Try"** to open it as a request in a new tab. You can easily `Edit` the response details using the **** menu icon, `Save` any changes made to the examples, and `Duplicate` them to generate various iterations. **Using examples for API mocking:** Saved examples can be used to create [mock servers](/documentation/features/mock) in Hoppscotch. When you create a mock server from a collection, each saved example automatically becomes a mock route with the exact response you captured. This lets you quickly convert real API behavior into mock endpoints for testing, prototyping, or development without a backend. Hoppscotch also supports **importing** collections with **examples** attached to each request from various platforms, including **Postman, Insomnia, OpenAPI, and Hoppscotch.** ## Filter Response Body To extract specific data points from the response body, you can apply filters using [jq](https://jqlang.github.io/jq/) syntax. jq is a powerful and flexible command-line JSON processor that allows you to slice, filter, map, and transform JSON data with ease. **Migration Notice:** JSONPath has been replaced with jq for JSON response filtering. If you have existing JSONPath filters, you'll need to migrate them to jq syntax. Refer to the [jq manual](https://jqlang.github.io/jq/manual/) for detailed documentation on jq syntax and features. ## **Download Response** You can download the response in various formats (JSON, XML, etc.) for offline analysis or record-keeping. Click the **"Download"** button and choose the format you wish to save. ## **Copy Response** To copy the entire response to the clipboard, simply click the **"Copy"** button. ## **Generate Data Schema** Using the **"More"** menu, you can generate a structured representation of the response data tailored to specific programming languages. You can **download the file** or **copy the response** in languages like TypeScript, C#, Go, and others, making it simpler for you to incorporate API responses into your applications. # Tests Source: https://docs.hoppscotch.io/documentation/getting-started/rest/tests Write and run post-request test scripts to validate API responses, check status codes, and verify data. Add tests to saved or unsaved requests. ## Scripts Hoppscotch lets you add dynamic behavior to REST requests. This allows you to write test suites and build requests that can contain dynamic parameters. You can add JavaScript code that executes at two events in the flow: * Tests are executed after a response is received from the server * You can add multiple tests to a request * You can add tests to both requests saved and not saved in a collection Hoppscotch will then execute the scripts after the response is received. ## Post-request tests As you introduce new code, tests ensure that your API is working as intended. The higher your test coverage, the more flexible and bug-resistant your code will be. You'll be spending less time wondering why [deleting a picture of a coconut breaks your code](https://www.thegamer.com/this-coconut-jpg-in-team-fortress-2s-game-files-if-deleted-breaks-the-game-and-no-one-knows-why). ## Writing post-request tests Hoppscotch ships a powerful API called `pw` which can handle post-request scripts as well as tests. Here we'll use `pw` to run tests on the response received from APIs. ## Examples Let us look at some examples of how you can use Hoppscotch to write tests. ### Test response status code Let us write a test to check whether the response to our request has a status code of 200. Which means that there are no errors in the response body. We'll use the below URL with the GET method. ``` https://www.httpbin.org/status/200 ``` In this case, we'll need to write two expect statements one for checking the status and another for checking the response body. However, we can wrap expect statements with the `test` method from the `pw` API to group related statements. There are two ways to test the status code: | Condition | Code | | ------------------------------- | ---------------------------------------------- | | Check if response code is `200` | `pw.expect(pw.response.status).toBe(200)` | | In-built matcher function | `pw.expect(pw.response.status).toBeLevel2xx()` | ```javascript Response code 200 theme={null} pw.test("Response is ok", () => { pw.expect(pw.response.status).toBe(200); }); ``` ```javascript Matcher function theme={null} pw.test("Response is ok", () => { pw.expect(pw.response.status).toBeLevel2xx(); }); ``` The tests will have passed once you click on the "**Send**" button. ### Assert response payload In this example, we test whether a user id points to a particular user. Let us use the following GET API endpoint ``` https://reqres.in/api/users/10 ``` We will use `.toBe()` to assert specific values and `.toBeType()` to assert specific data types as shown in the code snippet below: ```javascript theme={null} pw.test("Check first name", () => { const user = pw.response.body.data; pw.expect(user.first_name).toBe("Byron"); pw.expect(user.first_name).toBeType("string"); }); ``` Running the test will produce the result as shown below: ```json theme={null} { "data": { "id": 10, "email": "byron.fields@reqres.in", "first_name": "Byron", "last_name": "Fields", "avatar": "https://reqres.in/img/faces/10-image.jpg" }, "support": { "url": "https://contentcaddy.io?utm_source=reqres&utm_medium=json&utm_campaign=referral", "text": "Tired of writing endless social media content? Let Content Caddy generate it for you." } } ``` # Uploading data Source: https://docs.hoppscotch.io/documentation/getting-started/rest/uploading-data Upload files and encoded data to APIs in Hoppscotch using POST or PUT methods with multipart form data, JSON, or binary content types. APIs can also be used to upload encoded content to a server. This is usually done with `PUT` or `POST` methods. The most common content types are: * `application/json`: for content in JSON format * `multipart/form-data`: for uploading encoded files * `application/octet-stream`: for uploading binary data directly ## Uploading a file To upload a file, the data you send in a `POST` request must be of the content types `application/x-www-form-encoded` and `multipart/form-data`. ## Uploading an image Let's take a look at **uploading an image** file to an API using Hoppscotch: 1. Select the `POST` HTTP method and set your API Endpoint URL. 2. Add the necessary headers. 3. To add your image file click in the body tab and select `multipart/form-data` in the content-type dropdown. 4. Give your file a name and click on `choose files` to select your file. 5. Click "**Send**" to upload your file. The **Bulk Edit** feature is available for `multipart/form-data` as well. Instead of adding or editing key-value pairs one by one, you can now manage them all at once. ### Set Content Type for Specific Parameters in `multipart/form-data` When sending multiple types of data in a single request using `multipart/form-data`, you can assign a specific content type to each parameter in Hoppscotch. Here's how: 1. Go to the **Body** tab and select `multipart/form-data` from the **Content Type** dropdown. 2. Add the required data for your request by uploading files or entering values. 3. To specify content types for parameters, enable the **"Show Content Type"** option. Then, choose the appropriate content type for each parameter (e.g., `text/plain` for plain text, `image/png` for a PNG image or `application/json` for JSON data). 4. Click **Send** to submit the multipart data, with each parameter using its specified content type. ## Uploading Binary Data When uploading binary files, you may want to send raw binary data instead of files in a multipart form. This is typically done using the `application/octet-stream` content type. Follow these steps to upload binary data: 1. Select the **POST** or **PUT** HTTP method and set your API Endpoint URL. 2. In the **Body** tab, select `application/octet-stream` from the **Content Type** dropdown. 3. Upload your binary data by selecting the file from your local machine. 4. Click **Send** to upload the binary data. Currently, the **Hoppscotch Desktop App** does **NOT** support uploading **Binary files** directly as request bodies for APIs. # Setup Hoppscotch Source: https://docs.hoppscotch.io/documentation/getting-started/setup Set up Hoppscotch on web, desktop, or the command-line interface. Choose your preferred platform and start building and testing APIs in minutes. To get started with Hoppscotch, you need to choose a platform to use it on. Hoppscotch is available on the following platforms: * [Web](#web-app) * [Desktop](#desktop-app) * [CLI](#cli) ## Web To get started with Hoppscotch web client, head to [hoppscotch.io](https://hoppscotch.io) and start using it right away for free. ## Desktop Hoppscotch Desktop App is a cross-platform desktop application built with Tauri and Hoppscotch Web Client. It is a standalone version of Hoppscotch that can be installed on your computer and used without a browser. Hoppscotch Desktop App is available for Mac, Windows and Linux. ## CLI Hoppscotch CLI is the command-line interface for Hoppscotch. It is a standalone version of Hoppscotch that can be installed on your computer and used without a browser. Hoppscotch CLI is available as an npm package. # Troubleshooting Source: https://docs.hoppscotch.io/documentation/getting-started/troubleshooting Fix common Hoppscotch issues including connectivity problems, CORS errors, browser extensions, and firewall configuration for API testing. If you're facing issues with Hoppscotch, you can try the following steps to resolve them. ## Connectivity If Hoppscotch fails to send your request, it could be because you are experiencing connectivity issues. Check your connection by attempting to open a page in your web browser. ## Firewalls Sometimes firewalls may be configured to block non-browser connections. You might need to contact your network administrator so that Hoppscotch can work seamlessly. ## Incorrect protocol You might have specified the wrong protocol, check if you're using `https://` or `http://` in your URL or vice-versa. ## Hoppscotch errors It could also be possible that Hoppscotch might be making invalid requests to your API server. You can confirm this by checking your server logs (if available). If you believe this is happening, do get in touch with the Hoppscotch team. ## CORS restrictions CORS or Cross-Origin Resource Sharing is a security mechanism built into modern web browsers. It may cause the following error when testing API endpoints or some other API endpoints with Hoppscotch. This is because the API is not sending the proper API headers (`Access-Control-Allow-Origin`) and can be solved in the following ways: 1. Use the [Hoppscotch Desktop App](/documentation/clients/desktop/overview) which is not subject to CORS restrictions. 2. Use middleware like the Proxy mode, [Proxy Interceptor](https://github.com/hoppscotch/proxyscotch), or the [Hoppscotch Browser Extension](https://github.com/hoppscotch/hoppscotch-extension), and enable it in the "**Interceptor**" section of "**Settings**". ## Something went wrong If you're still facing issues, with an error message that says "Something went wrong", help us to better understand the issue by: 1. Opening the developer tools in your browser (usually by pressing `F12` or `Ctrl/Cmd`+`Shift`+`I`). 2. Switch to the "**Console**" tab. 3. Reproduce the issue. 4. Take a screenshot of the console and send it to us. Report a bug by [opening a new issue](https://github.com/hoppscotch/hoppscotch/issues/new/choose). # i18n Source: https://docs.hoppscotch.io/documentation/i18n Help translate Hoppscotch into your language. Learn how to contribute translations and support internationalization and localization efforts. Thanks for showing your interest in helping us to translate the software. ## Creating a new translation Before you start working on a new language, please look through the [open pull requests](https://github.com/hoppscotch/hoppscotch/pulls) to see if anyone is already working on a translation. If you find one, please join the discussion and help us keep the existing translations up to date. If there is no existing translation, you can create a new one by following these steps: 1. **[Fork the repository](https://github.com/hoppscotch/hoppscotch/fork).** 2. **Checkout the `main` branch for latest translations.** 3. **Create a new branch for your translation with base branch `main`.** 4. **Create target language file in the [`/packages/hoppscotch-common/locales`](https://github.com/hoppscotch/hoppscotch/tree/main/packages/hoppscotch-common/locales) directory.** 5. **Copy the contents of the source file [`/packages/hoppscotch-common/locales/en.json`](https://github.com/hoppscotch/hoppscotch/blob/main/packages/hoppscotch-common/locales/en.json) to the target language file.** 6. **Translate the strings in the target language file.** 7. **Add your language entry to [`/packages/hoppscotch-common/languages.json`](https://github.com/hoppscotch/hoppscotch/blob/main/packages/hoppscotch-common/languages.json).** 8. **Save and commit changes.** 9. **Send a pull request.** *You may send a pull request before all steps above are complete: e.g., you may want to ask for help with translations, or getting tests to pass. However, your pull request will not be merged until all steps above are complete.* Completing an initial translation of the whole site is a fairly large task. One way to break that task up is to work with other translators through pull requests on your fork. You can also [add collaborators to your fork](https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/inviting-collaborators-to-a-personal-repository) if you'd like to invite other translators to commit directly to your fork and share responsibility for merging pull requests. ## Updating a translation ### Corrections If you notice spelling or grammar errors, typos, or opportunities for better phrasing, open a pull request with your suggested fix. If you see a problem that you aren't sure of or don't have time to fix, [open an issue](https://github.com/hoppscotch/hoppscotch/issues/new/choose). ### Broken links When tests find broken links, try to fix them across all translations. Ideally, only update the linked URLs, so that translation changes will definitely not be necessary. # GraphQL Source: https://docs.hoppscotch.io/documentation/protocols/graphql Learn about the GraphQL query language for APIs, how it fetches only requested data, and how to test GraphQL endpoints in Hoppscotch. ## Platform Hoppscotch has a built-in GraphQL platform that can be used to execute GraphQL queries. The GraphQL platform can be accessed by clicking on the `GraphQL` tab in the left sidebar. The GraphQL platform has the following features: * **GraphQL editor** - The GraphQL editor can be used to write GraphQL queries. The editor has syntax highlighting and auto-completion support for GraphQL queries. * **Collections** - The GraphQL platform supports collections. You can save your GraphQL queries in a collection and execute them later. * **Variables** - The GraphQL platform supports variables. You can define variables in the GraphQL query and pass the values of the variables in the variables section. * **Headers** - The GraphQL platform supports headers. You can add custom headers to the GraphQL query. * **Authentication** - The GraphQL platform supports authentication. You can add authentication to the GraphQL query. * **Schema Explorer** - The GraphQL platform has a schema explorer. You can use the schema explorer to explore the GraphQL schema. * **Documentation Explorer** - The GraphQL platform has a documentation explorer. You can use the documentation explorer to explore the documentation of the GraphQL schema. ## API Testing Hoppscotch's GraphQL API platform provides you with the best experience to test and play around with GraphQL. It's primarily divided into two sections along with other features to help you build and test queries. ## Request The request section houses the feature to enter your server endpoint and initiate a connection. Once the connection is made, the `query` builder assists you in designing queries to fetch the data that you require and run it. You can also add dynamic behavior to your queries by defining `variables`, `headers`, and `authorization`. ## Response This is where you see the responses to your API endpoints. You can download and copy the returned responses for further use. ## Schema GraphQL is a query language for APIs that queries the server and provides the client only the data that is requested by the client. GraphQL enables you to fetch data from multiple APIs in a single query thus helping you build better-performing applications. GraphQL server uses a GraphQL Schema to describe the structure of your data. Given below is an example of a GraphQL Schema. ```graphql theme={null} type Laptop { model: String maker: Maker } type Maker { name: String laptops: [Laptop] } ``` The above schema defines two types `Laptop` and `Maker`. The `Laptop` type has two fields `model` and `maker`. The `Maker` type has two fields `name` and `laptops`. The `laptops` field in the `Maker` type is an array of the `Laptop` type. GraphQL queries are written in the GraphQL query language. Given below is an example of a GraphQL query. ```graphql theme={null} query { maker(name: "Apple") { name laptops { model } } } ``` The above query fetches the `name` and `laptops` of the `Maker` with the name `Apple`. GraphQL queries can be executed using a GraphQL client. Hoppscotch has a built-in GraphQL client that can be used to execute GraphQL queries. ## Other features ### Documentation GraphQL documentation is where you can view the documentation provided by the developer. ### Explorer GraphQL uses a schema to define the structure of the data, the schema explorer helps you to understand how your data is structured. The GraphQL platform also houses other features like: * [Environments](/documentation/features/environments) * [Collections](/documentation/features/collections) * [History](/documentation/features/history) # Realtime Source: https://docs.hoppscotch.io/documentation/protocols/realtime Learn about real-time API protocols supported in Hoppscotch including WebSocket, SSE, Socket.IO, and MQTT for bidirectional communication. ## Platform Hoppscotch has a built-in real-time platform that can be used to execute real-time requests. The real-time client platform can be accessed by clicking on the `Realtime` tab in the left sidebar. Realtime protocols are used in communication, entertainment, and even in the Internet of Things (IoT) to deliver and handle real-time messages, audio, etc. With Hoppscotch you can work with the following real-time protocols: * WebSocket * Socket.IO * SSE * MQTT ## API Testing Hoppscotch's Realtime API platform helps you test your real-time APIs easily. It's primarily divided into two sections: the request section and the response section. ## Request The request section houses the feature to enter your server endpoint and initiate a connection. You also get the option to choose from four different protocols `WebSocket`, `SSE`, `Socket.IO`, and `MQTT`. ## Response Once the connection is established, you can view the responses and logs in the response section. ## WebSocket WebSockets are an alternative to HTTP communication in Web Applications. They offer a long-lived, bidirectional communication channel between client and server. Once established, the channel is kept open, offering a very fast connection with low latency and overhead. This makes them ideal for real-time applications. WebSockets are perfect for scenarios such as: * When you need to support real-time communication between the client and the server. * When you need to support a protocol that is more efficient than HTTP. * When you need to support a protocol that is more efficient than long polling. ## Socket.IO Socket.io is a real-time event-based communication library built on WebSocket. It enables real-time, bi-directional communication between web clients and servers. Socket.io is perfect for scenarios such as: * When you need to support older browsers that don't support WebSockets. * When you need to support polling transports for mobile devices. * When you need to support multiple transports for a single connection. ## SSE SSE is a standard describing how servers can initiate data transmission towards clients once an initial client connection has been established. An SSE connection can discard processed messages without accumulating all of them in memory making it a memory-efficient implementation of XHR streaming. SSE is perfect for scenarios such as: * When an efficient unidirectional communication protocol is needed that won't add unnecessary server load (which is what happens with long polling). * When you need a protocol with a predefined standard for handling errors. * When you want to use HTTP-based methods for real-time data streaming. ## MQTT Message Queuing Telemetry Transport (MQTT) protocol is a publish/subscribe protocol that is lightweight and requires minimal memory, CPU, and bandwidth to connect IoT devices. Unlike HTTP's request/response paradigm, MQTT is event-driven and enables messages to be pushed to clients. Once connected to the MQTT server, you can either publish a message under a topic or subscribe to a topic to get messages about that topic being sent across the server in real time. MQTT is perfect for scenarios such as: * When you need to support real-time communication between the client and the server. * When you need to support a protocol that is more efficient than HTTP. # RESTful Source: https://docs.hoppscotch.io/documentation/protocols/rest Understand the RESTful protocol, HTTP methods like GET, POST, PUT, and DELETE, and how to test REST API endpoints using Hoppscotch. ## Platform Hoppscotch has a built-in REST platform that can be used to execute REST API requests. The REST platform can be accessed by clicking on the `REST` tab in the menu. The REST platform has the following features: * **Request editor** - The request editor can be used to write REST API requests. The editor has syntax highlighting and auto-completion support for REST API requests. * **Collections** - The REST platform supports collections. You can save your REST API requests in a collection and execute them later. * **Variables** - The REST client supports variables. You can define variables in the REST API request and pass the values of the variables in the variables section. * **Headers** - The REST platform supports headers. You can add custom headers to the REST API request. * **Authentication** - The REST platform supports authentication. You can add authentication to the REST API request. * **Pre-request scripts** - The REST platform supports pre-request scripts. You can write pre-request scripts to modify the request before it is sent to the server. * **Tests** - The REST platform supports tests. You can write tests to verify the response of the REST API request. * **Response viewer** - The REST platform has a response viewer. You can use the response viewer to view the response of the REST API request. * **Environments** - The REST platform supports environments. You can create multiple environments and switch between them. Representational State Transfer (REST) API is a software interface that enables two systems to communicate on the Internet. A REST API can do operations like creating, deleting, and modifying data. REST APIs are built on top of the HTTP protocol and have dedicated HTTP methods to perform operations. REST APIs are stateless, which means that the server does not store any information about the client. This makes REST APIs scalable and easy to maintain. ## API Testing Hoppscotch's REST API platform provides you with a fast and seamless experience to test and debug your API endpoints. It's primarily divided into two sections along with other features to help you build better APIs. ## Request The request section provides you the capability to define your API endpoint and initiate the communication. You can select from a range of HTTP methods such as `GET`, `POST`, `PUT` etc. You can read more about HTTP methods in [RESTful protocol](/documentation/protocols/rest). You can also add dynamic behaviors to your requests by specifying `Headers`, `Request Body`, `Authorization Headers`, `Parameters`, and `Pre-request scripts`. Hoppscotch also provides the capability to run `Tests` on the responses you receive. ## Response This is where you see the responses to your API endpoints. You can download and copy the returned responses for further use. ## HTTP Methods REST APIs use HTTP methods to perform operations. The most common HTTP methods are: | HTTP Method | Usage | | ----------- | ------------------------------------------------ | | GET | Retrieve information about the REST API resource | | POST | Create a REST API resource | | PUT | Update a REST API resource | | DELETE | Delete a REST API resource or related component | Other methods like `HEAD`, `CONNECT`, `OPTIONS`, `TRACE`, `PATCH` and other `CUSTOM` methods can also be used. ## HTTP Status Codes HTTP status codes are used to indicate the status of the HTTP request. The most common HTTP status codes are: | Status Code | Description | | ----------- | --------------------- | | 200 | OK | | 201 | Created | | 204 | No Content | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found | | 405 | Method Not Allowed | | 500 | Internal Server Error | Other status codes like `301`, `302`, `304`, `307`, `308`, and other `5XX` codes can also be used. ## Other features The REST API platform also houses other features like: * [Environments](/documentation/features/environments) * [Collections](/documentation/features/collections) * [History](/documentation/features/history) # Community Edition admin dashboard Source: https://docs.hoppscotch.io/documentation/self-host/community-edition/admin-dashboard Manage users, invitations, and teams from the Hoppscotch Community Edition admin dashboard. Configure settings and monitor your instance. The Admin Dashboard serves as the central hub for managing your workspaces and user-related activities. From here, you can efficiently oversee and control various aspects of your platform. * Insights Dashboard: Gain valuable insights into platform usage. * Manage Users: Handle user-related actions, such as inviting, elevating admins, and deleting users. * Manage Workspaces: Create, edit, and delete workspaces while managing workspace-specific details and user memberships. ## Dashboard The Dashboard section provides an overview of essential metrics and statistics regarding users, workspaces, and activity. This snapshot allows you to track the usage and performance of your platform. Get insights into your organization's usage of Hoppscotch. * Number of Users: Monitor the count of registered users. * Number of Workspaces: Keep track of the total number of workspaces. * Number of Requests: Measure the volume of requests made by your organization. * Number of Collections: Track the quantity of collections within the platform. ## Manage users The Users section empowers you to effectively control user-related actions. It streamlines the process of user management, making it simple to oversee the user base. In Hoppscotch Community Edition, any user can create an account and use the platform. * User List: View a comprehensive list of all users on your platform. * Invite Users: Send invitations to new users, welcoming them to the platform. * Admin Privileges: Elevate users to administrative roles for increased permissions. * User Deletion: Delete users when necessary. ### Invite Users Admins can invite new users to their Hoppscotch instance. Depending on whether SMTP is configured, the process differs slightly. #### With SMTP When SMTP is enabled from the Admin Dashboard and the required SMTP configurations are correctly set, follow these steps to invite a new user: 1. Go to the **Users** section within the Admin Dashboard. 2. Select the **Invite User** button to open the invitation modal. 3. Enter the email address of the user you want to invite and click **Add User** to send an invitation. 4. An email containing an invite link (`http://localhost:3000`) will be sent to the invitee. They can use this link to log in to the Hoppscotch web app. 5. Alternatively, you can copy the invite link and share it through other platforms with the new user. Make sure the user signs in using the email address specified during the invitation process. #### Without SMTP If SMTP is disabled from the Admin Dashboard, the invitation process is slightly different: 1. Go to the **Users** section within the Admin Dashboard. 2. Select the **Invite User** button to open the invitation modal. 3. Enter the email address of the user you want to invite and click **Add User**. 4. An invite link (`http://localhost:3000`) will be generated and displayed. Copy this link and share it with the user via your preferred communication channel. Make sure the user signs in to Hoppscotch using the same email address you provided during the invitation. ### Pending Invites Within the **Users** section, admins can view a list of all users who have been invited but have not yet joined the organization. To access this list, simply click on the **Pending Invites** button next to "Invite User". Here, you'll see all the invitations you've sent, along with details such as: * **Invitee Email:** The email address to which the invite was sent. * **Invited By:** The email address of the user who sent the invitation * **Invited on:** The date and time when the invitation was sent. **You can also consider the following actions:** * **Copy Invite Link:** If you need to resend the invitation, you can easily `copy` the invite link and share it with the user via any communication platform. * **Revoke Invitation:** If you wish to cancel an invitation, click the `Revoke Invitation` button next to the specific user invite in the **Action** column. This will remove the pending invite from the list and prevent the user from accessing your Hoppscotch instance using that link. ## Manage Workspaces In the Manage Workspace section, you can efficiently handle workspace-related operations, ensuring that collaborations and projects run smoothly. * Workspace Creation: Establish new workspaces tailored to specific projects or departments. * Workspace Editing: Modify workspace details and configurations as needed. * Workspace Deletion: Disband workspaces that are no longer relevant. * User Memberships: View and manage the users associated with each workspace. ## Infra-tokens InfraTokens are special UUID tokens that provide a secure way for admins to interface with Self-Hosted APIs. They are exclusively accessible to admins, ensuring that only authorized personnel can manage sensitive operations. Unlike Personal Access Tokens, which are tied to individual users, InfraTokens are scoped at the instance level, granting access to all admins within the instance. #### Generate an InfraToken Follow these steps to create a new InfraToken: 1. After logging into your Self-Hosted instance using your admin credentials, go to **Settings > Infra Tokens** in your Admin Dashboard. 2. Click **Generate new token**. 3. Enter a title for the token and select an expiration date. Available options include 7 days, 30 days, 60 days, 90 days, or no expiry. 4. Confirm creation. **The new InfraToken will be displayed once — copy it securely** to your clipboard for immediate use. 5. To delete a token, return to the **Infra Tokens** section and remove it. The details of the admin who created the InfraToken are stored for audit purposes. All admins can view and manage these tokens. #### How to use InfraTokens InfraTokens are used as **Bearer tokens**. When making requests to the User Management APIs, include the `InfraToken` in the `Authorization` header as follows: ```bash theme={null} Bearer ``` #### APIs for User Management The RESTful APIs designed for User Management enable admins to perform a wide range of user-related actions, such as inviting new users, deleting existing ones, and updating user details. These APIs provide admins with the ability to efficiently manage user accounts and permissions. The table below introduces nine key APIs that give admins greater control over user management. | User Activity | Description | Method | Endpoint | | -------------------------------------- | ----------------------------------------------------------------------------- | ------ | ---------------------------------------------- | | Invite a New User | Allows admins to invite a new user to the instance. | POST | `/v1/infra/user-invitations` | | View Pending Invites | Retrieves a list of all pending invites sent to new users. | GET | `/v1/infra/user-invitations` | | Delete Pending Invites | Enables admins to delete specific pending invites using their Email ID. | DELETE | `/v1/infra/user-invitations` | | View All Users | Provides a list of all users in the instance. | GET | `/v1/infra/users` | | View a Particular User | Fetches details of a specific user in the instance by their User ID. | GET | `/v1/infra/users/{uid}` | | Delete an existing User | Enables admins to delete an existing user from the instance by their User ID. | DELETE | `/v1/infra/users/{uid}` | | Update User Details | Allows admins to update the details of an existing user. | PATCH | `/v1/infra/users/{uid}` | | Manage Admin Status | Enables admins to add or remove admin status for an existing user. | PATCH | `/v1/infra/users/{uid}/admin-status` | | Fetch User's involvement in Workspaces | Retrieves workspace details that a user is part of, including their role. | GET | `/v1/infra/users/{uid}/workspaces` | To interact with the User Management APIs, ensure that your backend service is running, either on your local machine or on a server. The API documentation is accessible at the `/api-docs` endpoint relative to your backend service URL. For example, if your backend is running locally, you can access the API docs at [http://localhost:3170/api-docs](http://localhost:3170/api-docs). You can also retrieve the OpenAPI v3 JSON format at [http://localhost:3170/api-docs-json](http://localhost:3170/api-docs-json). ## Server Settings User provisioning with SCIM is available in Hoppscotch Enterprise Edition. See [SCIM Integration for User and Group Provisioning](/documentation/self-host/enterprise-edition/user-provisioning) for setup and supported provisioning flows. In the **Server Settings** section, you have the ability to both view and edit the environment variables that were configured during the setup of your self-hosted instance. ### Configurations 1. **Configure Authentication Providers:** Customize authentication providers, including Google, Microsoft, GitHub, and email, directly from the settings page. 2. **Configure SMTP Settings:** Set up your SMTP settings for seamless email integration. 3. **History Configurations:** Control the logging of request history for all users with a simple toggle option. * **When enabled:** Request history is visible in the Hoppscotch app, and new entries are actively logged and stored in the database. * **When disabled:** Request history is hidden from the Hoppscotch app, and no new request logs are written to the database. You can also optionally choose to purge all existing history from the database, ensuring complete removal of previously logged request data. 4. **Data sharing:** Enable or disable anonymous data sharing to help improve Hoppscotch. [Learn more about the metrics collected](./telemetry). 5. **Reset Configurations:** If needed, reset your configurations back to their original state. After making any configuration updates, be sure to save the changes. The server will automatically restart to apply the modifications. ## Hard Reset Configurations If you need to perform a hard reset of the server configurations, execute the following command in your terminal to reset all your environment variables: ```bash theme={null} docker exec -it psql -d hoppscotch -c "TRUNCATE \"InfraConfig\";" ``` You can replace `` with the actual ID of your Docker container. # Deploy and upgrade Community Edition Source: https://docs.hoppscotch.io/documentation/self-host/community-edition/deploy-and-upgrade Deploy Hoppscotch Community Edition to production and upgrade to newer versions. Includes guides for Docker, subpath access, and migrations. This section contains instructions for deploying and upgrading Hoppscotch Community Edition. ## Deploy Deploy Hoppscotch Community Edition on your infrastructure. Instructions for deploying Hoppscotch on your infrastructure are coming soon. ## Upgrade Upgrading Hoppscotch Community Edition is a simple process. Follow the instructions below to upgrade your Hoppscotch Community Edition instance. ### Using individual containers for the services 1. Check if there is a new version available by running the following command: ```bash theme={null} docker images ``` 2. Update the image to the latest version by running the following command: ```bash theme={null} docker pull hoppscotch/hoppscotch-frontend:latest docker pull hoppscotch/hoppscotch-backend:latest docker pull hoppscotch/hoppscotch-admin:latest ``` If you want to update to a specific version, run the following command: ```bash theme={null} docker pull hoppscotch/hoppscotch-frontend: docker pull hoppscotch/hoppscotch-backend: docker pull hoppscotch/hoppscotch-admin: ``` 3. Start the new container by following the instructions in the [Install and build](/documentation/self-host/community-edition/install-and-build#docker) section. For minor version upgrades, you might not need to run the database migrations. However, for major version upgrades, you will need to run the database migrations. Refer to the [Database migrations](/documentation/self-host/community-edition/install-and-build#migrations) section for more information. ### Using the AIO container 1. Check if there is a new version available by running the following command: ```bash theme={null} docker images ``` 2. Update the image to the latest version by running the following command: ```bash theme={null} docker pull hoppscotch/hoppscotch:latest ``` If you want to update to a specific version, run the following command: ```bash theme={null} docker pull hoppscotch/hoppscotch: ``` 3. Start the new container by following the instructions in the [Install and build](/documentation/self-host/community-edition/install-and-build#docker) section. For minor version upgrades, you might not need to run the database migrations. However, for major version upgrades, you will need to run the database migrations. Refer to the [Database migrations](/documentation/self-host/community-edition/install-and-build#migrations) section for more information. # Getting started with Community Edition Source: https://docs.hoppscotch.io/documentation/self-host/community-edition/getting-started Get started self-hosting Hoppscotch Community Edition. Review the steps for prerequisites, installation, configuration, and deployment. Community Edition is the perfect starting point for individual developers or small teams looking to integrate Hoppscotch into their workflow without additional costs. It's open-source, meaning you can modify it as needed, though you'll manage updates and maintenance yourself. With Self Host Community edition you get access to Admin Dashboard which acts as a central hub for managing your workspaces and overseeing user-related activities. Prerequisites to self-host Hoppscotch Community Edition on your infrastructure. Install and build Hoppscotch Community Edition on your infrastructure. Manage your Hoppscotch Community Edition instance with the Admin dashboard. # Install and build Community Edition Source: https://docs.hoppscotch.io/documentation/self-host/community-edition/install-and-build Install and build Hoppscotch Community Edition using Docker. Configure environment variables, authentication providers, and SMTP settings. If you're interested in deploying Hoppscotch on Kubernetes, you can conveniently skip this guide and proceed directly to the [Helm chart deployment guide](/documentation/self-host/helm-chart-deployment/getting-started). ## Configuring the environment Before you get started with the installation, you need to configure the environment variables. Create a `.env` file in the root directory of the project and add the following environment variables: **Ensure that the environment values are not enclosed within quotes \[""].** To enable desktop app support for self-hosted instances, make sure you've enabled [subpath based access](#subpath-based-access). ```yaml theme={null} #-----------------------Backend Config------------------------------# # Prisma Config DATABASE_URL=postgresql://username:password@url:5432/dbname # or replace with your database URL # Sensitive Data Encryption Key while storing in Database (32 characters) DATA_ENCRYPTION_KEY=******************************** # Whitelisted origins for the Hoppscotch App. # This list controls which origins can interact with the app through cross-origin comms. # - localhost ports (3170, 3000, 3100): app, backend, development servers and services # - app://localhost_3200: Bundle server origin identifier # NOTE: `3200` here refers to the bundle server (port 3200) that provides the bundles, # NOT where the app runs. The app itself uses the `app://` protocol with dynamic # bundle names like `app://{bundle-name}/` WHITELISTED_ORIGINS=http://localhost:3170,http://localhost:3000,http://localhost:3100,app://localhost_3200,app://hoppscotch #-----------------------Frontend Config------------------------------# # Base URLs VITE_BASE_URL=http://localhost:3000 VITE_SHORTCODE_BASE_URL=http://localhost:3000 VITE_ADMIN_URL=http://localhost:3100 # Backend URLs VITE_BACKEND_GQL_URL=http://localhost:3170/graphql VITE_BACKEND_WS_URL=wss://localhost:3170/graphql VITE_BACKEND_API_URL=http://localhost:3170/v1 # Terms Of Service And Privacy Policy Links (Optional) VITE_APP_TOS_LINK=https://docs.hoppscotch.io/support/terms VITE_APP_PRIVACY_POLICY_LINK=https://docs.hoppscotch.io/support/privacy # Set to `true` for subpath based access ENABLE_SUBPATH_BASED_ACCESS=false #-----------------------Container Runtime Config---------------------# # (Optional) Caddy's in-container HTTP port. Defaults to 80 when unset. # Set a free port (for example 8000) to run the container under a non-root UID. # HOPP_ALTERNATE_PORT=8000 ``` Let's understand the major environment variables: 1. `DATABASE_URL`: This is where you add your Postgres database URL. 2. `DATA_ENCRYPTION_KEY`: A 32-character key used for encrypting sensitive data stored in the database. 3. `WHITELISTED_ORIGINS`: URLs of Hoppscotch backend, admin dashboard, frontend app and the bundle server that are allowed to interact with the desktop app. 4. `VITE_BASE_URL`: This is the URL where your deployment will be accessible from. 5. `VITE_SHORTCODE_BASE_URL`: A URL to generate shortcodes for sharing, can be the same as `VITE_BASE_URL`. 6. `VITE_BACKEND_GQL_URL`: The URL for GraphQL within the instance. 7. `VITE_BACKEND_WS_URL`: The URL for WebSockets within the instance. 8. `VITE_BACKEND_API_URL`: The URL for REST APIs within the instance. 9. `VITE_APP_TOS_LINK` and `VITE_APP_PRIVACY_POLICY_LINK` are optional and are used to configure the links to the Terms & Conditions and Privacy Policy. 10. `HOPP_ALTERNATE_PORT`: An optional variable that changes the HTTP port Caddy listens on inside the container, which is `80` by default. Set it to run under a non-root user, or when port `80` is already taken. See [running under a non-root user](#running-under-a-non-root-user). Third-party auth configs have to be obtained from the respective providers. You can choose and configure the auth providers by following the [configuring OAuth guide](/documentation/self-host/community-edition/prerequisites#oauth). ## Docker Once the environment variables are configured, you may proceed to the next step of setting up the Hoppscotch instance. Currently, there are two ways to set up Hoppscotch: 1. Using individual containers for the services. 2. Using the AIO container. * Before proceeding further, ensure that you have a running instance of Postgres. ### Using individual containers for the services To self-host Hoppscotch Community Edition, you will need the following services running via Docker: * Hoppscotch frontend * Hoppscotch backend * Hoppscotch admin dashboard Pull the containers from DockerHub with the following command: ```bash theme={null} docker pull hoppscotch/hoppscotch-frontend docker pull hoppscotch/hoppscotch-backend docker pull hoppscotch/hoppscotch-admin ``` After pulling the containers, start Hoppscotch by running all three services: ```bash theme={null} docker run -p 3000:3000 --env-file .env --restart unless-stopped hoppscotch/hoppscotch-frontend docker run -p 3170:3170 --env-file .env --restart unless-stopped hoppscotch/hoppscotch-backend docker run -p 3100:3100 --env-file .env --restart unless-stopped hoppscotch/hoppscotch-admin ``` Ensure that the environment variables are configured in the `.env` file and the restart policy is mentioned. To enable desktop app support for your self-hosted Hoppscotch instance, make sure you expose the web app server which is a part of the frontend container. You can do this by running the following command: ```bash theme={null} docker run -p 3000:3000 -p 3200:3200 --env-file .env --restart unless-stopped hoppscotch/hoppscotch-frontend ``` Open [admin dashboard](http://localhost:3100) or [`PORT 3100`](http://localhost:3100) in the browser to [setup and access](/documentation/self-host/community-edition/setup-and-access) the Hoppscotch instance. ### Using the AIO container The All-In-One (AIO) container is a single container that provides all the services required to run Hoppscotch. Pull the container from DockerHub with the following command: ```bash theme={null} docker pull hoppscotch/hoppscotch ``` After pulling the container, start Hoppscotch by running the container: ```bash theme={null} docker run -p 3000:3000 -p 3100:3100 -p 3170:3170 --env-file .env --restart unless-stopped hoppscotch/hoppscotch ``` Ensure that the environment variables are configured in the `.env` file and the restart policy is mentioned. Open [admin dashboard](http://localhost:3100) or [`PORT 3100`](http://localhost:3100) in the browser to [setup and access](/documentation/self-host/community-edition/setup-and-access) the Hoppscotch instance. ## Subpath Based Access To enable subpath based access the following `.env` variable must be set to true, it is set to false by default. ``` ENABLE_SUBPATH_BASED_ACCESS=true ``` To enable desktop app support for your self-hosted Hoppscotch instance, make sure to set `ENABLE_SUBPATH_BASED_ACCESS` to `true` in your `.env` file. When set to true the following is the expected behavior: ### Using individual containers for the services When using the individual containers it is up to the users to configure a reverse proxy to allow requests made to a specific route to be rerouted to the relevant containers. ### Using the AIO container When using AIO, when subpath access is set to true the services can be accessed from the following routes | Service | Route | | -------------------- | ---------- | | Hoppscotch App | `/` | | Hoppscotch Admin App | `/admin` | | Hoppscotch Backend | `/backend` | By default, the AIO container serves the app on port `80`. Ports below `1024` are privileged, so a non-root user can't bind them — a common restriction in rootless Docker, Podman, and hardened environments like OpenShift. On those setups, set `HOPP_ALTERNATE_PORT` to bind the app to a port at or above `1024`. See [running under a non-root user](#running-under-a-non-root-user). ## Running under a non-root user By default the images serve on port `80` inside the container (the HTTP port Caddy binds), which a non-root user can't bind since ports below `1024` are privileged. To run under a non-root UID — OpenShift's restricted SCC, rootless Docker, Podman — set `HOPP_ALTERNATE_PORT` to a free port at or above `1024`, run the container with GID `0`, and update your published port mapping to match: ```bash theme={null} docker run --user 1000:0 -p 3000:8000 -e HOPP_ALTERNATE_PORT=8000 --env-file .env --restart unless-stopped hoppscotch/hoppscotch ``` On OpenShift the restricted SCC assigns the UID and GID `0` for you; just set the variable and point your Service and Route at the port you chose. If you deploy with the provided `docker-compose.yml`, the container side of the port mapping already follows `HOPP_ALTERNATE_PORT`. The port must not collide with one the image already uses, or the container exits at startup naming the conflict: | Image | Reserved ports | | ------------------------- | -------------- | | AIO (subpath access mode) | `8080`, `3200` | | Frontend | `3000`, `3200` | | Backend | `3170`, `8080` | | Admin | `3100` | The container needs a writable root filesystem, and the non-root UID must belong to GID `0`. ## Migrations Once the instance of Hoppscotch is up, you need to run migrations on the database to ensure that it has the relevant tables. Depending on how Hoppscotch was set up, the method to run the migrations changes. ### Using individual containers for the services Run the following command to copy the ID of the **backend container**: ```bash theme={null} docker ps ``` ### Using the AIO container Run the following command to copy the ID of the **AIO container**: ```bash theme={null} docker ps ``` ### Running migrations Once the respective container ID is copied, execute the following command to open an interactive shell within the container to execute the migration command: ```bash theme={null} docker exec -it /bin/sh ``` Once inside the container, run the migration using: ```bash theme={null} pnpm exec prisma migrate deploy ``` Should the user ever encounter the following error: ```bash theme={null} Database migration not found. Please check the documentation for assistance: https://docs.hoppscotch.io/documentation/self-host/community-edition/install-and-build#running-migrations ``` It means the user is trying to start the backend (or AIO) service before the database has all the relevant tables in it. In order to run the migration to populate the database run the following command. ```bash theme={null} docker run -it --entrypoint sh --env-file .env ``` Making sure to pass in the `.env` file containing the right `.env` variables for the instance. Executing the aforementioned command will result in a shell being opened inside an instance of the container, following which the user can execute a database migration normally with ```bash theme={null} pnpm exec prisma migrate deploy ``` Once the migration has been successfully run and the database populated with tables, the backend containers (or AIO container) can be started normally. Note: If user is using `docker compose` to run the services the following command can be used to open a shell inside the backend (or AIO) service. ```bash theme={null} docker compose run --entrypoint sh ``` # Community Edition prerequisites Source: https://docs.hoppscotch.io/documentation/self-host/community-edition/prerequisites Review the system requirements, OAuth provider setup, and SMTP configuration needed before installing Hoppscotch Community Edition. Hoppscotch is a self-hosted API development platform, packaged as a set of Docker containers. You can install and run Hoppscotch on any operating system that can run a [Docker Engine](https://docs.docker.com/engine). You can use Hoppscotch on your local machine or a cloud provider of your choice. ## System Requirements Hoppscotch is designed to run well on both small and large deployments. The minimum requirements to run Hoppscotch are an operating system that supports Docker and 4 CPU cores + 4GB of RAM to generate the build image and as little as 1 CPU core + 2GB of RAM to host the generated output files. ## Install Node.js, npm, pnpm ### Node.js + npm Install [`Node.js`](https://nodejs.org/en) (v18+) and [`npm`](https://www.npmjs.com) (v9+). * [Node.js + npm installation guide](https://nodejs.org/en/download) Verify Node.js and npm installation by running the following commands in your terminal: ```bash theme={null} node -v ``` ```bash theme={null} npm -v ``` ### pnpm Install [`pnpm`](https://pnpm.io) (v6+). * [pnpm installation guide](https://pnpm.io/installation) Verify pnpm installation by running the following command in your terminal: ```bash theme={null} pnpm -v ``` ## Docker Install [`Docker`](https://www.docker.com) (v20+). * [Docker installation guide](https://docs.docker.com/engine/install) Verify Docker installation by running the following command in your terminal: ```bash theme={null} docker -v ``` It is recommended to use Compose V2. To switch to Compose V2, use the `docker compose` CLI plugin or activate the **Use Docker Compose V2** setting in Docker Desktop. For more information, see the [Evolution of Compose](https://docs.docker.com/compose/compose-v2). ## Git Install [`Git`](https://git-scm.com) (v2+). * [Git installation guide](https://git-scm.com/download) Verify Git installation by running the following command in your terminal: ```bash theme={null} git --version ``` ## Email delivery (optional) Hoppscotch comes with support for easy integrations with 3rd party SMTP providers. You will need emails so that you can invite your team to use Hoppscotch and for emails to work, you will need to set up proper SMTP configuration as described below. To enable email delivery, you will need to generate a valid SMTP URL in the below format: ``` smtps://user@domain.com:pass@smtp.domain.com ``` For example, if you are using Gmail as your SMTP server your SMTP URL will look like something shown below: ``` smtps://user@gmail.com:pass@smtp.gmail.com ``` You can also use [mailcatcher](https://mailcatcher.me/) as a simple SMTP server. ### Custom SMTP configuration For more advanced needs, such as production-level email delivery or gaining more control over your email configurations, you can set up a custom SMTP server. To enable the custom mailer configuration, in addition to setting the `MAILER_USE_CUSTOM_CONFIGS` to `true`, you'll also need the following details in the specified format: | Requirement | Description | Format | | ------------- | -------------------------------------------- | -------------------------------------- | | SMTP Host | Address of your SMTP server | `smtp.customdomain.com` | | SMTP Port | Communication port used by your SMTP server | `587` for **TLS** or `465` for **SSL** | | SMTP User | Username for your SMTP account | `user@customdomain.com` | | SMTP Password | Corresponding password for your SMTP account | `custompass` | You can use services like [SendGrid](https://sendgrid.com/), [Amazon SES](https://aws.amazon.com/ses/), or your own SMTP server to set up custom email delivery with Hoppscotch. ## Postgres database Hoppscotch uses a Postgres database to store all the data. You can use any Postgres database provider of your choice - hosted locally or on a cloud provider. Make sure you have a valid Postgres database URL in the below format: ``` postgresql://username:password@url:5432/dbname ``` ## OAuth You also need to configure an OAuth provider to enable third-party authentication. Hoppscotch supports the following OAuth providers: 1. Email 2. GitHub 3. Google 4. Microsoft ### Choosing OAuth Providers Hoppscotch allows you to choose which authentication providers to enable for your workspace during the onboarding flow in the admin dashboard. You can easily select from options like Google, GitHub, Microsoft, and Email directly through the setup interface. ```yaml theme={null} VITE_ALLOWED_AUTH_PROVIDERS=GOOGLE,GITHUB,MICROSOFT,EMAIL ``` ### Configuring third-party providers To configure the third-party authentication, you will need to generate a valid OAuth client ID and client secret for the OAuth provider of your choice. You will also need to provide a valid callback URL for the OAuth provider. For example, if you are using GitHub as your OAuth provider, you will need to generate a valid OAuth client ID and client secret for GitHub. You will also need to provide a valid callback URL for GitHub. The credentials for the GitHub OAuth provider can be entered during onboarding in the admin dashboard, and will look like the following: ```yaml theme={null} GITHUB_CLIENT_ID=***** GITHUB_CLIENT_SECRET=***** GITHUB_CALLBACK_URL=http://localhost:3170/v1/auth/github/callback GITHUB_SCOPE=user:email ``` The `CALLBACK_URL` variable is the URL that is invoked after the authorization is done and it follows the pattern `http://localhost:3170/v1/auth/[auth_provider_name]/callback`. The `SCOPE` variable defines the scope of the data that the OAuth provider passes on to Hoppscotch. The links to configure OAuth for various providers are given below: 1. [**GitHub**](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) (scope: email) 2. [**Google**](https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid#get_your_google_api_client_id) (scope: email, profile) 3. [**Microsoft**](https://learn.microsoft.com/en-us/azure/active-directory/develop/scenario-web-app-sign-user-app-registration?tabs=nodejs#register-an-app-by-using-the-azure-portal) (scope: user with read permission) It is recommended that you secure your deployments by issuing TLS certificates and using **HTTPS** since we use **secure HTTP cookies** for authenticating users. ## Support for standard `HTTP/s` ports From the December 2023 release onwards containers now support ingress via standard HTTP/S ports on port `80` and `443` by default, moving forward it is recommended users switch to using these ports. We currently do still support the services being exposed from ports `3000`, `3100` and `3170` respectively but support for this will be dropped in the future and all containers will work over standard HTTP/s ports. # Set up and access Community Edition Source: https://docs.hoppscotch.io/documentation/self-host/community-edition/setup-and-access Complete the initial setup of Hoppscotch Community Edition by creating an admin account, configuring access, and verifying your installation. After successfully running the necessary containers, the next step involves creating an administrator account to manage Hoppscotch. The system automatically designates the first user who logs in through the admin dashboard as the administrator. ## Creating an administrator account 1. Open a new browser tab and visit [`http://localhost:3100`](http://localhost:3100). 2. This will grant you access to the admin dashboard. 3. Login using your credentials or create a new account. 4. The first user to log in will be given administrator privileges. Learn how to manage your Hoppscotch instance using the admin dashboard. ## Accessing the Hoppscotch app With the administrator account set up, you can now start using the Hoppscotch app for API testing and development. 1. Open a new browser tab and visit [`http://localhost:3000`](http://localhost:3000). 2. Begin testing and developing your APIs seamlessly with Hoppscotch. Hoppscotch Enterprise Edition is available for on-premise deployment with priority support. [Contact Hoppscotch Support](/support/getting-started/contact) # Community Edition telemetry Source: https://docs.hoppscotch.io/documentation/self-host/community-edition/telemetry Understand what telemetry data Hoppscotch Community Edition collects, how it is used, and how to opt out of anonymous usage analytics. Telemetry in Hoppscotch Self-Host refers to anonymous data shared with Hoppscotch. This helps identify the usage patterns of Hoppscotch. # Data Collected by Hoppscotch Hoppscotch does not capture any data from your APIs. All captured data is anonymous and pertains to instance usage. ## Instance Usage The instance usage ping is sent once a week to indicate that the instance is operational. You can disable this event by navigating to the settings page and turning off data sharing settings. ```json theme={null} { "uuid": "976fcae1-4079-4e83-881a-48723f694475", "event": "sh_instance", "properties": { "type": "COMMUNITY", "total_user_count": 10, "total_workspace_count": 2, "version": "2024.3.0", "$lib": "posthog-node", "$lib_version": "3.6.3", "$geoip_disable": true, "$ip": "127.0.0.1", "$sent_at": "2024-02-20T06:14:20.041000+00:00", "$plugins_succeeded": [ "GeoIP (8000)" ], "$plugins_failed": [], "$plugins_deferred": [] }, "timestamp": "2024-02-20T06:14:20.591000Z", "team_id": 15871, "distinct_id": "9bdec3aae9330af51ba91313d3de99b46ae928da", "elements_chain": "", "created_at": "2024-02-20T06:14:20.835000Z" } ``` # Turning off data sharing You can turn off your data sharing preferences from your Hoppscotch admin dashboard by heading over to the Data Sharing section in the settings page. # Activity logs Source: https://docs.hoppscotch.io/documentation/self-host/enterprise-edition/activity-logs Track changes to collections and requests within workspaces using Activity Logs in Hoppscotch Enterprise. Monitor user interactions. **Activity Logs** provide a clear record of actions performed within a workspace, including changes to collections, requests, and user interactions. These logs help maintain visibility and traceability of modifications across the workspace. ## Configuring Activity Logs Activity Logs are controlled via a unified toggle in the Admin Dashboard. 1. Go to **Admin Dashboard → Logging Configurations.** 2. **Enable the toggle** in this section to start recording Activity Logs. Activity Logs operate independently and do not require ClickHouse credentials. However, if Audit Logs are needed, [ClickHouse credentials must be configured](/documentation/self-host/enterprise-edition/prerequisites#clickhouse). ## Accessing Activity Logs To access Activity Logs in a workspace: 1. Navigate to the specific workspace from the workspace switcher present in the top right corner of the app. 2. Locate and click on the **clock** icon in the right sidebar. 3. In the `History` tab, you will find a chronological timeline of all changes made to collections and requests. 4. Logs are ordered from the latest to the oldest for easier navigation, with entries grouped by date. ## Permissions * **OWNER** and **EDITOR** roles: Actions performed by users with these roles are logged. * **VIEWER** role: Viewers cannot make changes, but they can view the activity logs of changes made by others. ## **Logged Actions** Activity Logs track the following actions within the workspace: ### **Workspace-Level Events** | **Action** | **Logged Activity Example** | | ----------------------------------- | ------------------------------------------------------- | | Creating a new workspace | `Created` new workspace `Staging` | | Renaming a Workspace | `Renamed` workspace from `Staging` to `Production` | | Adding a user to the workspace | John Doe was `added` to the workspace as `Viewer` | | Updating a user's role in workspace | John Doe's role was `updated` from `Viewer` to `Editor` | | Removing a user from the workspace | John Doe was `removed` from the workspace | ### **Collection-Level Events** | **Action** | **Logged Activity Example** | | ------------------------- | ---------------------------------------------------------------- | | Creating a new collection | `Created` new collection `Authentication APIs` | | Renaming a collection | `Renamed` collection from `User Management` to `Role Management` | | Importing a collection | `Imported` collection `Payment Gateway APIs` | | Duplicating a collection | `Duplicated` collection `Microservices APIs` | | Deleting a collection | `Deleted` collection `Authentication APIs` | ### **Request-Level Events** | **Action** | **Logged Activity Example** | | ---------------------- | --------------------------------------- | | Creating a new request | `Created` new request `Fetch User Data` | | Deleting a request | `Deleted` request `Fetch User Data` | Users with the **OWNER** role have the authority to `DELETE` activity logs. ## **Log Entry Details** Each log entry provides detailed information about the recorded action, including: * **Timestamp:** The exact time when the action occurred. * **Action Summary:** A summary of changes made in the operation. * **User Information:** The name of the user who performed the action. # Enterprise Edition admin dashboard Source: https://docs.hoppscotch.io/documentation/self-host/enterprise-edition/admin-dashboard Manage users, teams, SCIM provisioning, and license settings from the Hoppscotch Enterprise Edition admin dashboard and its configuration. The Admin Dashboard serves as the central hub for managing your workspace and user-related activities. From here, you can efficiently oversee and control various aspects of your platform. * Insights Dashboard: Gain valuable insights into platform usage. * Manage Users: Handle user-related actions, such as inviting, elevating admins, and deleting users. * Manage Workspaces: Create, edit, and delete workspaces while managing workspace-specific details and user memberships. ## Dashboard The Dashboard section provides an overview of essential metrics and statistics regarding users, workspaces, and activity. This snapshot allows you to track the usage and performance of your platform. Get insights into your organization's usage of Hoppscotch. * Number of Users: Monitor the count of registered users. * Number of Workspaces: Keep track of the total number of workspaces. * Number of Requests: Measure the volume of requests made by your organization. * Number of Collections: Track the quantity of collections within the platform. ## Manage users In Hoppscotch Enterprise Edition, a user needs to be explicitly invited by the admin to create an account on the platform. The Users section empowers you to effectively control user-related actions. It streamlines the process of user management, making it simple to oversee the user base. * User List: View a comprehensive list of all users and their activity on your platform * Invite Users: Send invitations to new users, welcoming them to the platform. * Admin Privileges: Elevate users to administrative roles for increased permissions. * User Deletion: Delete users when necessary. ### Invite Users Admins can easily bring new users to their Hoppscotch instance by sending them invitations. Depending on whether SMTP is configured, the process differs slightly. Here's how you can invite users: #### With SMTP When SMTP is enabled from the admin dashboard and the required SMTP configurations are correctly set, follow these steps to invite a new user: 1. Go to the **Users** section within the Admin Dashboard. 2. Select the **Invite User** button to open the invitation modal. 3. Input the email address of the user you want to invite and click **Add User** to send an invitation. 4. An email containing an invite link (`http://localhost:3000`) will be sent to the invitee. They can use this link to log in to Hoppscotch web app. 5. Alternatively, you can copy the invite link and share it through other platforms with the new user, but make sure the user signs in using the email address specified during the invitation process. #### Without SMTP If SMTP is disabled from the admin dashboard, the invitation process is slightly different: 1. Go to the **Users** section within the Admin Dashboard. 2. Select the **Invite User** button to open the invitation modal. 3. Input the email address of the user you want to invite and click **Add User**. 4. An invite link (`http://localhost:3000`) will be generated and displayed before you. Copy this link and share it with the user via your preferred communication channel. Make sure that the user signs in to Hoppscotch using the same email address you provided during the invitation. ### Pending Invites Within the **Users** section, admins can view a list of all users who have been invited but have not yet joined the organization. To access this list, simply click on the **Pending Invites** button next to "Invite User". Here, you'll see all the invitations you've sent, along with details such as: * **Invitee Email:** The email address to which the invite was sent. * **Invited By:** The email address of the user who sent the invitation * **Invited on:** The date and time when the invitation was sent. **You can also consider the following actions:** * **Copy Invite Link:** If you need to resend the invitation, you can easily `copy` the invite link and share it with the user via any communication platform. * **Revoke Invitation:** If you wish to cancel an invitation, simply click the `Revoke Invitation` button next to the specific user invite in the **Action** column. This will remove the pending invite from the list and prevent the user from accessing your Hoppscotch instance using that link. ## Manage Workspaces In the Manage Workspace section, you can efficiently handle workspace-related operations, ensuring that collaborations and projects run smoothly. * Workspace Creation: Establish new workspaces tailored to specific projects or departments. * Workspace Editing: Modify workspace details and configurations as needed. * Workspace Deletion: Disband workspaces that are no longer relevant. * User Memberships: View and manage the users associated with each workspace. ## Infra-tokens InfraTokens are special UUID tokens that provide a secure way for admins to interface with Self-Hosted APIs. They are exclusively accessible to admins, ensuring that only authorized personnel can manage sensitive operations. Unlike Personal Access Tokens, which are tied to individual users, InfraTokens are scoped at the instance level, granting access to all admins within the instance. #### Generate an InfraToken Follow these steps to create a new InfraToken: 1. After logging into your Self-Hosted instance using your admin credentials, you can access the **“Infra Tokens”** under the “Settings” section from your admin dashboard. 2. Click on **"Generate new token."** 3. Enter a title for the token and select an expiration date. Available options include 7 days, 30 days, 60 days, 90 days, or no expiry. 4. After providing the necessary details, confirm the creation. **The new InfraToken will be displayed once, make sure to copy it securely** to your clipboard for immediate use. 5. If you decide that you no longer need the token, you can delete it by navigating back to **“Infra Tokens"** section. The details of the admin who created the InfraToken are stored for audit purposes. All admins can view and manage these tokens. #### How to use InfraTokens InfraTokens are to be used as **Bearer tokens**. When making requests to the User Management APIs, include the `InfraToken` in the `Authorization` header as follows: ```bash theme={null} Bearer ``` #### APIs for User Management The RESTful APIs designed for User Management enable admins to perform a wide range of user-related actions, such as inviting new users, deleting existing ones, and updating user details. These APIs provide admins with the ability to efficiently manage user accounts and permissions. The table below introduces nine key APIs that give admins greater control over user management. | User Activity | Description | Method | Endpoint | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------ | ---------------------------------------------- | | Invite a New User | Allows admins to invite a new user to the instance. | POST | `/v1/infra/user-invitations` | | View Pending Invites | Retrieves a list of all pending invites sent to new users. | GET | `/v1/infra/user-invitations` | | Delete Pending Invites | Enables admins to delete specific pending invites using their Email ID. | DELETE | `/v1/infra/user-invitations` | | View All Users | Provides a list of all users in the instance. | GET | `/v1/infra/users` | | View a Particular User | Fetches details of a specific user in the instance by their User ID. | GET | `/v1/infra/users/{uid}` | | Delete an existing User | Enables admins to delete an existing user from the instance by their User ID. | DELETE | `/v1/infra/users/{uid}` | | Update User Details | Allows admins to update the details of an existing user. | PATCH | `/v1/infra/users/{uid}` | | Manage Admin Status | Enables admins to add or remove admin status for an existing user. | PATCH | `/v1/infra/users/{uid}/admin-status` | | Fetch User's involvement in Workspaces | Retrieves workspace details that a user is part of, including their role. | GET | `/v1/infra/users/{uid}/workspaces` | | Deactivate User Account | Allows admins to deactivate a user account, preventing them from accessing the instance until reactivated. | POST | `/v1/infra/users/{uid}/deactivate` | | Reactivate User Account | Allows admins to activate a user account that was previously deactivated. | POST | `/v1/infra/users/{uid}/reactivate` | To interact with the **User Management APIs**, ensure that your backend service is running, either on your local machine or on a server. The API documentation is accessible at the `/api-docs` endpoint relative to your backend service URL. For example, if your backend is running locally, you can access the API docs at [http://localhost:3170/api-docs](http://localhost:3170/api-docs). You can also retrieve the OpenAPI v3 JSON format at [http://localhost:3170/api-docs-json](http://localhost:3170/api-docs-json). #### APIs for Workspace Management We've introduced new **APIs** to make **workspace management** and **collaboration** easier for **admins**. These APIs enable quick actions like creating new workspaces, updating existing workspace details, and deleting workspaces as needed. Check out the table below for **fourteen** APIs that give admins a greater control over managing Hoppscotch workspaces. | **Workspace Activity** | **Description** | **Method** | **Endpoint** | | ----------------------------------------- | --------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------- | | Create a Workspace | Create a new workspace within the instance. | POST | `/v1/infra/workspaces` | | View All Workspaces | Retrieves a list of all workspaces available. | GET | `/v1/infra/workspaces` | | View Workspace Details | List details about a specific workspace like name, members, roles, and pending invites. | GET | `/v1/infra/workspaces/{id}` | | Delete a workspace | Remove an existing workspace using its ID. | DELETE | `/v1/infra/workspaces/{id}` | | Update details for an existing workspace. | Modify settings and preferences for an existing workspace. | PATCH | `/v1/infra/workspaces/{id}` | | List Members of a Workspace | Retrieves a list of all members in a specific workspace. | GET | `/v1/infra/workspaces/{id}/members` | | Get Workspace Owners count | Fetches number of Workspace members with "OWNER" permissions | GET | `/v1/infra/workspaces/{id}/owners-count` | | Get Workspace Editors count | Fetches number of Workspace members with "EDITOR" permissions | GET | `/v1/infra/workspaces/{id}/editors-count` | | Get Workspace Viewers count | Fetches number of Workspace members with "VIEWER" permissions | GET | `/v1/infra/workspaces/{id}/viewers-count` | | Add User to a workspace | Add a user and assign roles (Owner, Editor, and Viewer) in a workspace. | POST | `/v1/infra/workspaces/{id}/user` | | Change User roles in a workspace | Update the role (Owner, Editor, and Viewer) of a user within a workspace | PATCH | `/v1/infra/workspaces/{id}/user/{uid}/role` | | Remove User from a workspace | Remove a user from a workspace using their ID | DELETE | `/v1/infra/workspaces/{id}/user/{uid}` | | View all pending workspace invites. | List all pending invites for workspace access. | GET | `/v1/infra/workspaces/{id}/invitations` | | Delete pending workspace invites. | Revoke Workspace invitations using invitation IDs. | DELETE | `/v1/infra/workspaces/{id}/invitations/{invitation_id}` | To interact with the **Workspace Management APIs**, ensure that your backend service is running, either on your local machine or on a server. The API documentation is accessible at the `/api-docs` endpoint relative to your backend service URL. For example, if your backend is running locally, you can access the API docs at [http://localhost:3170/api-docs](http://localhost:3170/api-docs). You can also retrieve the OpenAPI v3 JSON format at [http://localhost:3170/api-docs-json](http://localhost:3170/api-docs-json). ## Server Settings In the **Server Settings** section, you have the ability to both view and edit the environment variables that were configured during the setup of your self-hosted instance. ### Configurations 1. **Access Control Settings:** Manage and restrict user access to ensure only authorized users can interact with your Hoppscotch instance. * **Site Protection:** When site protection is activated, all visitors to your Hoppscotch instance will be prompted to create an account and log in to use Hoppscotch. Site protection is enabled by default on Hoppscotch Enterprise and can be disabled as needed. * **Domain Whitelisting:** Domain Whitelisting enables organization admins to grant access to users with email addresses under the organization's domain without explicit approval. To enable domain whitelisting, activate the "Enable Whitelisted Domains" option and simply add the domains used by your organization for email addresses. 2. **Configure Authentication Providers:** Customize authentication providers, including Google, Microsoft, GitHub, and email, directly from the settings page. 3. **Configure SMTP Settings:** Configure your SMTP settings for seamless email integration. 4. **Configure SAML Settings:** Configure your SAML settings for your SAML based Single Sign-On. 5. **Configure OIDC Settings:** Configure your OIDC Settings for Single Sign-On based authentication. 6. **User Provisioning:** Enable SCIM provisioning to manage user and group creation, updates, membership sync, and deprovisioning directly from your Identity Provider (IdP). [Learn how to set up SCIM provisioning in Hoppscotch](/documentation/self-host/enterprise-edition/user-provisioning). 7. **Configure Logging Settings:** Manage activity and audit logging configurations for your Hoppscotch instance. Enable or disable logs through a unified setting, configure ClickHouse credentials, and download audit logs in CSV format. 8. **History Configurations:** Control the logging of request history for all users with a simple toggle option. * **When enabled:** Request history is visible in the Hoppscotch app, and new entries are actively logged and stored in the database. * **When disabled:** Request history is hidden from the Hoppscotch app, and no new request logs are written to the database. You can also optionally choose to purge all existing history from the database, ensuring complete removal of previously logged request data. 9. **Data sharing:** Enable or disable anonymous data sharing to help improve Hoppscotch. [Learn more about the metrics collected](./telemetry). 10. **Reset Configurations:** If needed, reset your configurations back to their original state. ### Custom Banner **Custom banners** allow self-host admin to share important announcements such as a scheduled maintenance or instance upgrade with the rest of your team. * **Create Announcements:** Navigate to the `Banners` tab and toggle the **"Show Banner"** action. Select the **type of banner** (Information, Warning, or Danger), craft and preview the **message** content, and `save` it to activate announcement immediately. * **Edit Announcements:** You can modify the announcements directly by editing the message or changing the banner type and further saving the changes to implement them. * **Delete Announcements:** Manually end an announcement by toggling the **"Show Banner"** action **OFF**. ### License Settings The **License Settings** enable you to both configure and view your enterprise license information. You have the following options: * **Edit and Configure License Key:** You can modify and configure your license key as needed. * **View License Status:** Obtain insights into the current status of your license. This includes details such as License Status, Issued to, Number of seats purchased, and expiry date. ## Hard Reset Configurations If you need to perform a hard reset of the server configurations, execute the following command in your terminal to reset all your environment variables: ```bash theme={null} docker exec -it psql -d hoppscotch -c "TRUNCATE \"InfraConfig\";" ``` You can replace `` with the actual ID of your Docker container. # Deploy and upgrade Enterprise Edition Source: https://docs.hoppscotch.io/documentation/self-host/enterprise-edition/deploy-and-upgrade Deploy Hoppscotch Enterprise Edition to production and upgrade to newer versions. Includes Docker guides, subpath access, and migrations. This section contains instructions for deploying and upgrading Hoppscotch Enterprise Edition. ## Deploy Deploy Hoppscotch Enterprise Edition on your infrastructure. * Instructions for deploying Hoppscotch on your infrastructure are coming soon. ## Upgrade Upgrading Hoppscotch Enterprise Edition is a simple process. Follow the instructions below to upgrade your Hoppscotch Enterprise Edition instance. ### Using individual containers for the services 1. Check if there is a new version available by running the following command: ```bash theme={null} docker images ``` 2. Update the image to the latest version by running the following command: ```bash theme={null} docker pull hoppscotch/hoppscotch-enterprise-frontend:latest docker pull hoppscotch/hoppscotch-enterprise-backend:latest docker pull hoppscotch/hoppscotch-enterprise-admin:latest ``` If you want to update to a specific version, run the following command: ```bash theme={null} docker pull hoppscotch/hoppscotch-enterprise-frontend: docker pull hoppscotch/hoppscotch-enterprise-backend: docker pull hoppscotch/hoppscotch-enterprise-admin: ``` 3. Start the new container by following the instructions in the [Install and build](/documentation/self-host/enterprise-edition/install-and-build#docker) section. For minor version upgrades, you might not need to run the database migrations. However, for major version upgrades, you will need to run the database migrations. Refer to the [Database migrations](/documentation/self-host/enterprise-edition/install-and-build#migrations) section for more information. ### Using the AIO container 1. Check if there is a new version available by running the following command: ```bash theme={null} docker images ``` 2. Update the image to the latest version by running the following command: ```bash theme={null} docker pull hoppscotch/hoppscotch-enterprise:latest ``` If you want to update to a specific version, run the following command: ```bash theme={null} docker pull hoppscotch/hoppscotch-enterprise: ``` 3. Start the new container by following the instructions in the [Install and build](/documentation/self-host/enterprise-edition/install-and-build#docker) section. For minor version upgrades, you might not need to run the database migrations. However, for major version upgrades, you will need to run the database migrations. Refer to the [Database migrations](/documentation/self-host/enterprise-edition/install-and-build#migrations) section for more information. # Getting started with Enterprise Edition Source: https://docs.hoppscotch.io/documentation/self-host/enterprise-edition/getting-started Get started self-hosting Hoppscotch Enterprise Edition. Review the steps for license activation, prerequisites, installation, and setup. Enterprise Edition builds on top of the Community Edition foundation by adding powerful features designed for larger organizations that require robust security measures like SAML-based SSO, OIDC, audit logs, and on-premise deployment options. It also comes with dedicated support to help adapt Hoppscotch to your company's specific needs. The self-hosted enterprise version is open-core in nature, meaning it is accompanied by a set of advanced features that are only available through a commercial license. Prerequisites to self-host Hoppscotch Enterprise Edition on your infrastructure. Install and build Hoppscotch Enterprise Edition on your infrastructure. Manage your Hoppscotch Enterprise Edition instance with the Admin dashboard. # Install and build Enterprise Edition Source: https://docs.hoppscotch.io/documentation/self-host/enterprise-edition/install-and-build Install and build Hoppscotch Enterprise Edition using Docker. Configure environment variables, auth providers, SMTP, and license keys. If you're interested in deploying Hoppscotch on Kubernetes, you can conveniently skip this guide and proceed directly to the [Helm chart deployment guide](/documentation/self-host/helm-chart-deployment/getting-started). ## Configuring the environment Before you get started with the installation, you need to configure the environment variables. Create a `.env` file in the root directory of the project and add the following environment variables: **Ensure that the environment values are not enclosed within quotes \[""].** To enable desktop app support for self-hosted instances, make sure you've enabled [subpath based access](#subpath-based-access). ```yaml theme={null} #-----------------------Backend Config------------------------------# # Enterprise License Key # Get your license key from https://enterprise.hoppscotch.com ENTERPRISE_LICENSE_KEY=*************************************** # Prisma Config DATABASE_URL=postgresql://username:password@url:5432/dbname # or replace with your database URL # Enable/Disable Horizontal Scaling # Set to 'true' to enable horizontal scaling across multiple backend instances # When enabled, Redis is required for session management and data synchronization HORIZONTAL_SCALING=false # Redis Config # Note: Configure Redis only if HORIZONTAL_SCALING is set to true REDIS_URL=redis://username:password@host:6379/0 # Sensitive Data Encryption Key while storing in Database (32 characters) DATA_ENCRYPTION_KEY=******************************** # Whitelisted origins for the Hoppscotch App. # This list controls which origins can interact with the app through cross-origin comms. # - localhost ports (3170, 3000, 3100): app, backend, development servers and services # - app://localhost_3200: Bundle server origin identifier # NOTE: `3200` here refers to the bundle server (port 3200) that provides the bundles, # NOT where the app runs. The app itself uses the `app://` protocol with dynamic # bundle names like `app://{bundle-name}/` WHITELISTED_ORIGINS=http://localhost:3170,http://localhost:3000,http://localhost:3100,app://localhost_3200,app://hoppscotch #-----------------------Frontend Config------------------------------# # Base URLs VITE_BASE_URL=http://localhost:3000 VITE_SHORTCODE_BASE_URL=http://localhost:3000 VITE_ADMIN_URL=http://localhost:3100 # Backend URLs VITE_BACKEND_GQL_URL=http://localhost:3170/graphql VITE_BACKEND_WS_URL=wss://localhost:3170/graphql VITE_BACKEND_API_URL=http://localhost:3170/v1 # Terms Of Service And Privacy Policy Links (Optional) VITE_APP_TOS_LINK=https://docs.hoppscotch.io/support/terms VITE_APP_PRIVACY_POLICY_LINK=https://docs.hoppscotch.io/support/privacy # Set to `true` for subpath based access ENABLE_SUBPATH_BASED_ACCESS=false # Optional: Local Proxy Server Config # Enables a local proxy server for routing API requests. # This will only work if ENABLE_SUBPATH_BASED_ACCESS is set to `true`. LOCAL_PROXY_SERVER_ENABLE=false # Optional: Route all API requests via a proxy server for added security. # Set your proxy server URL here, or remove this variable to send requests directly. PROXY_APP_URL=https://proxy.hoppscotch.io #-----------------------Container Runtime Config---------------------# # (Optional) Caddy's in-container HTTP port. Defaults to 80 when unset. # Set a free port (for example 8000) to run the container under a non-root UID. # HOPP_ALTERNATE_PORT=8000 ``` Let's understand the major environment variables: 1. `ENTERPRISE_LICENSE_KEY`: The license key required to use Hoppscotch Enterprise. 2. `DATABASE_URL`: This is where you add your Postgres database URL. 3. `HORIZONTAL_SCALING`: Set to true to enable horizontal scaling, which uses Redis for managing pub-sub and state across instances. 4. `DATA_ENCRYPTION_KEY`: A 32-character key used for encrypting sensitive data stored in the database. 5. `WHITELISTED_ORIGINS`: URLs of Hoppscotch backend, admin dashboard, frontend app and the bundle server that are allowed to interact with the desktop app. 6. `VITE_BASE_URL`: This is the URL where your deployment will be accessible from. 7. `VITE_SHORTCODE_BASE_URL`: A URL to generate shortcodes for sharing, can be the same as `VITE_BASE_URL`. 8. `VITE_BACKEND_GQL_URL`: The URL for GraphQL within the instance. 9. `VITE_BACKEND_WS_URL`: The URL for WebSockets within the instance. 10. `VITE_BACKEND_API_URL`: The URL for REST APIs within the instance. 11. `VITE_APP_TOS_LINK` and `VITE_APP_PRIVACY_POLICY_LINK` are optional and are used to configure the links to the Terms & Conditions and Privacy Policy. 12. `HOPP_ALTERNATE_PORT`: An optional variable that changes the HTTP port Caddy listens on inside the container, which is `80` by default. Set it to run under a non-root user, or when port `80` is already taken. See [running under a non-root user](#running-under-a-non-root-user). Third-party auth configs have to be obtained from the respective providers. You can choose and configure the auth providers by following the [configuring OAuth guide](/documentation/self-host/enterprise-edition/prerequisites#oauth). ## Docker Once the environment variables are configured, you may proceed to the next step of setting up the Hoppscotch instance. Currently, there are two ways to set up Hoppscotch: * Using individual containers for the services * Using the AIO container * Before proceeding further, ensure that you have a running instance of Postgres. ### Using individual containers for the services To self-host Hoppscotch Enterprise Edition, you will need the following services running via Docker: * Hoppscotch enterprise frontend * Hoppscotch enterprise backend * Hoppscotch enterprise admin dashboard Pull the containers from DockerHub with the following command: ```bash theme={null} docker pull hoppscotch/hoppscotch-enterprise-frontend docker pull hoppscotch/hoppscotch-enterprise-backend docker pull hoppscotch/hoppscotch-enterprise-admin ``` After pulling the containers, start Hoppscotch by running all three services: ```bash theme={null} docker run -p 3000:3000 --env-file .env --restart unless-stopped hoppscotch/hoppscotch-enterprise-frontend docker run -p 3170:3170 --env-file .env --restart unless-stopped hoppscotch/hoppscotch-enterprise-backend docker run -p 3100:3100 --env-file .env --restart unless-stopped hoppscotch/hoppscotch-enterprise-admin ``` Ensure that the environment variables are configured in the `.env` file and the restart policy is mentioned. To enable desktop app support for your self-hosted Hoppscotch instance, make sure you expose the web app server which is a part of the frontend container. You can do this by running the following command: ```bash theme={null} docker run -p 3000:3000 -p 3200:3200 --env-file .env --restart unless-stopped hoppscotch/hoppscotch-frontend ``` Open [admin dashboard](http://localhost:3100) or [`PORT 3100`](http://localhost:3100) in the browser to [setup and access](/documentation/self-host/enterprise-edition/setup-and-access) the Hoppscotch instance. ### Using the AIO container The All-In-One (AIO) container is a single container that provides all the services required to run Hoppscotch. Pull the container from DockerHub with the following command: ```bash theme={null} docker pull hoppscotch/hoppscotch-enterprise ``` After pulling the container, start Hoppscotch by running the container: ```bash theme={null} docker run -p 3000:3000 -p 3100:3100 -p 3170:3170 --env-file .env --restart unless-stopped hoppscotch/hoppscotch-enterprise ``` Ensure that the environment variables are configured in the `.env` file and the restart policy is mentioned. Open [admin dashboard](http://localhost:3100) or [`PORT 3100`](http://localhost:3100) in the browser to [setup and access](/documentation/self-host/community-edition/setup-and-access) the Hoppscotch instance. ## Subpath Based Access To enable subpath based access the following `.env` variable must be set to true, it is set to false by default. ``` ENABLE_SUBPATH_BASED_ACCESS=true ``` To enable desktop app support for your self-hosted Hoppscotch instance, make sure to set `ENABLE_SUBPATH_BASED_ACCESS` to `true` in your `.env` file. When set to true the following is the expected behavior: ### Using individual containers for the services When using the individual containers it is up to the users to configure a reverse proxy to allow requests made to a specific route to be rerouted to the relevant containers. ### Using the AIO container When using AIO, when subpath access is set to true the services can be accessed from the following routes | Service | Route | | -------------------- | ---------- | | Hoppscotch App | `/` | | Hoppscotch Admin App | `/admin` | | Hoppscotch Backend | `/backend` | By default, the AIO container serves the app on port `80`. Ports below `1024` are privileged, so a non-root user can't bind them — a common restriction in rootless Docker, Podman, and hardened environments like OpenShift. On those setups, set `HOPP_ALTERNATE_PORT` to bind the app to a port at or above `1024`. See [running under a non-root user](#running-under-a-non-root-user). ## Running under a non-root user By default the images serve on port `80` inside the container (the HTTP port Caddy binds), which a non-root user can't bind since ports below `1024` are privileged. To run under a non-root UID — OpenShift's restricted SCC, rootless Docker, Podman — set `HOPP_ALTERNATE_PORT` to a free port at or above `1024`, run the container with GID `0`, and update your published port mapping to match: ```bash theme={null} docker run --user 1000:0 -p 3000:8000 -e HOPP_ALTERNATE_PORT=8000 --env-file .env --restart unless-stopped hoppscotch/hoppscotch-enterprise ``` On OpenShift the restricted SCC assigns the UID and GID `0` for you; just set the variable and point your Service and Route at the port you chose. If you deploy with the provided `docker-compose.yml`, the container side of the port mapping already follows `HOPP_ALTERNATE_PORT`. The port must not collide with one the image already uses, or the container exits at startup naming the conflict. Port `9159` is the local proxy server, which the backend starts when `LOCAL_PROXY_SERVER_ENABLE` is `true`: | Image | Reserved ports | | ------------------------- | ---------------------- | | AIO (subpath access mode) | `8080`, `3200`, `9159` | | Frontend | `3000`, `3200` | | Backend | `3170`, `8080`, `9159` | | Admin | `3100` | The container needs a writable root filesystem, and the non-root UID must belong to GID `0`. The ClickHouse container used for [audit logs](/guides/articles/audit-logs) is the official `clickhouse/clickhouse-server` image, which expects to run as its own UID and is not arbitrary-UID safe. On OpenShift, use a managed or externally hosted ClickHouse instead of running it alongside Hoppscotch under the restricted SCC. ## Migrations Once the instance of Hoppscotch is up, you need to run migrations on the database to ensure that it has the relevant tables. Depending on how Hoppscotch was set up, the method to run the migrations changes. ### Using individual containers for the services Run the following command to copy the ID of the **backend container**: ```bash theme={null} docker ps ``` ### Using the AIO container Run the following command to copy the ID of the **AIO container**: ```bash theme={null} docker ps ``` ### Running migrations Once the respective container ID is copied, execute the following command to open an interactive shell within the AIO container to execute the migration command: ```bash theme={null} docker exec -it /bin/sh ``` Once inside the container, run the migration using: ```bash theme={null} pnpm exec prisma migrate deploy ``` Should the user ever encounter the following error: ```bash theme={null} Database migration not found. Please check the documentation for assistance: https://docs.hoppscotch.io/documentation/self-host/community-edition/install-and-build#running-migrations ``` It means the user is trying to start the backend (or AIO) service before the database has all the relevant tables in it. In order to run the migration to populate the database run the following command. ```bash theme={null} docker run -it --entrypoint sh --env-file .env ``` Making sure to pass in the `.env` file containing the right `.env` variables for the instance. Executing the aforementioned command will result in a shell being opened inside an instance of the container, following which the user can execute a database migration normally with ```bash theme={null} pnpm exec prisma migrate deploy ``` Once the migration has been successfully run and the database populated with tables, the backend containers (or AIO container) can be started normally. Note: If user is using `docker compose` to run the services the following command can be used to open a shell inside the backend (or AIO) service. ```bash theme={null} docker compose run --entrypoint sh ``` ## ClickHouse setup To start saving the [audit logs](/guides/articles/audit-logs) into ClickHouse, first you need to create the relevant databases with the relevant tables in them. Follow the following instructions to set up ClickHouse to start saving logs: 1. Ensure that all the relevant containers are running. 2. Run the following command to get the ID of the ClickHouse container: ```bash theme={null} docker ps ``` 3. Once the ClickHouse container is also running, open an interactive bash into it using the `clickhouse-client`: ```bash theme={null} docker exec -it clickhouse-client ``` 4. Once inside the container, execute the following SQL commands: ```sql theme={null} # Create a database called logs CREATE DATABASE logs # Create a table called audit_logs in the logs database CREATE TABLE IF NOT EXISTS logs.audit_logs ( `event` String, `timestamp` DateTime, `user` Tuple(id String, email String, name String), `group` Tuple(type LowCardinality(String), id String), `resource` Tuple(type LowCardinality(String), metadata String), `statusCode` Int16, `errorMessage` String, `result` LowCardinality(String), `server_version` String ) ENGINE = MergeTree ORDER BY timestamp ``` ## SAML Configuration When you use SAML authentication, by default Hoppscotch only pulls the email of the user as the platform uses it as the unique identifier to verify the user. Starting from `v2024.9.2` onwards, Hoppscotch Enterprise Edition instances support pulling the following attributes from the SAML response to fill in additional user details: * `displayName`: The name of the user which is displayed within the Hoppscotch platform. * `photoURL`: The URL where to find the user's profile picture. **Do not** set this attribute if a profile picture doesn't exist. * `isAdmin` (optional): A boolean attribute (true or false) that automatically assigns the Admin role to users who belong to a designated group in the configured Identity Provider (e.g., Okta). The `isAdmin` attribute is evaluated only during the user's first login or signup. Subsequent logins or signups will not re-evaluate this flag. | Name | Name Format | Value | | ----------- | ----------- | ----------------------------------------------------------- | | displayName | Basic | user.displayName | | photoURL | Basic | user.profileURL | | isAdmin | Basic | isMemberOfGroupName("Hoppscotch Admins") ? "true" : "false" | You have to configure your **SAML IdP (Identity Provider)** to include these attributes *exactly* in the response. For example, for Okta, you can follow [this guide](https://support.okta.com/help/s/article/How-to-define-and-configure-a-custom-SAML-attribute-statement?language=en_US) to configure the attributes. # Observability Source: https://docs.hoppscotch.io/documentation/self-host/enterprise-edition/observability Set up OpenTelemetry observability for Hoppscotch Enterprise to monitor traces, metrics, and logs. Integrate with Grafana, Jaeger, and more. Observability support helps you understand what's happening inside your self-hosted Hoppscotch instance. With OpenTelemetry integration, you can track performance, diagnose issues faster, and gain insights into how your APIs are being used. This feature provides real-time visibility into your application's health, making it easier to maintain a reliable service for your team. ## What is Observability? Observability gives you the ability to understand your system's internal state by analyzing the data it produces. Instead of guessing why something went wrong, you can see exactly what happened and when. With Hoppscotch's observability integration, you get access to: * **Traces**: Follow the complete journey of each API request through your system * **Metrics**: Monitor performance indicators like response times and request volumes * **Logs**: Access detailed records of events with full context ## Why Use Observability? Implementing observability in your Hoppscotch instance helps you: * **Spot Issues Quickly**: Identify performance bottlenecks and errors as they happen * **Reduce Downtime**: Cut the time it takes to find and fix problems * **Understand Usage**: See how your team uses the platform and which APIs are most active * **Improve Performance**: Make data-driven decisions about optimizing your instance * **Debug with Confidence**: Get complete context when investigating issues ## How It Works Hoppscotch uses OpenTelemetry, an industry-standard framework for collecting observability data. OpenTelemetry is vendor-neutral, meaning you can use it with your preferred monitoring tools. Here's how the data flows: 1. **Your Hoppscotch instance** generates observability data as users make API requests 2. **OpenTelemetry Collector** receives and processes this data 3. **Storage backends** like Jaeger (traces) and Prometheus (metrics) store the data 4. **Visualization tools** like Grafana display dashboards and insights This setup gives you complete visibility without vendor lock-in. ## Key Features ### Distributed Tracing Track every API request from start to finish, even as it moves through different parts of your system. See exactly how long each step takes and where delays occur. * View the complete path of every request * Identify slow database queries or external API calls * Understand dependencies between different services ### Real-Time Metrics Monitor your instance's health with up-to-the-minute performance data: * Request rates and response times * Error rates and success percentages * System resource usage (CPU, memory) * Database performance indicators * Custom business metrics that matter to your team ### Contextual Logging Access detailed logs that include trace IDs, making it easy to find all related information when investigating an issue: * Searchable structured logs * Automatic correlation with traces and metrics * Configurable log levels for different environments * Long-term retention for compliance and analysis ### Intelligent Alerting Set up alerts to notify you when something needs attention: * Define thresholds for key metrics * Receive notifications through your preferred channels * Create custom alert rules based on your needs * Prevent alert fatigue with smart grouping ## Getting Started ### Prerequisites Before enabling observability, make sure you have: * Hoppscotch Enterprise Edition deployed * Admin access to your instance * Basic familiarity with Docker or Kubernetes (depending on your deployment) ### Setup Options You can deploy the observability stack in two ways: #### Option 1: Docker Deployment Best for smaller instances or teams getting started. This approach is quick to set up and works well for most use cases. * Simple configuration * Fast deployment * Lower resource requirements * Ideal for single-server setups Check out our detailed guide: [Set Up OpenTelemetry Stack with Docker](/guides/articles/set-up-opentelemetry-stack-with-docker) #### Option 2: Kubernetes Deployment Recommended for larger organizations with high-traffic instances requiring high availability and automatic scaling. * Automatic scaling based on load * High availability and fault tolerance * Advanced monitoring capabilities * Better suited for production environments ### Configuration Steps 1. **Deploy the OpenTelemetry Collector** Set up the Collector to receive data from your Hoppscotch instance. You can use our example configuration or customize it for your needs. 2. **Connect Storage Backends** Choose where to store your observability data: * Jaeger for distributed traces * Prometheus for metrics * Your preferred log management solution 3. **Configure Hoppscotch** From the Admin Dashboard, navigate to the Observability settings and enter your Collector endpoint details. 4. **Set Up Visualization** Deploy Grafana or your preferred tool to create dashboards and visualize your data. ## Understanding Your Data ### Traces Traces show you the complete story of each request: * **Request Entry**: When the request arrived at Hoppscotch * **Processing Steps**: Each operation performed (authentication, validation, etc.) * **External Calls**: Requests to databases or other APIs * **Response**: When and how the request completed Each step includes timing information, making it easy to spot slow operations. ### Metrics Metrics give you quantitative insights: * **HTTP Metrics**: Request counts, status codes, response times * **System Metrics**: CPU usage, memory consumption, disk I/O * **Database Metrics**: Query performance, connection pool status * **Business Metrics**: Active users, API calls per workspace, collection sizes ### Correlation All observability data is linked together. When you're investigating an issue, you can: * Start with a metric spike and drill down to individual traces * Click on a trace to see all related logs * Follow connections between different services ## Best Practices ### Start Simple Don't try to monitor everything at once. Begin with: 1. HTTP request metrics 2. Error tracking 3. Basic system health indicators Add more advanced monitoring as you become comfortable with the basics. ### Set Meaningful Thresholds Create alerts based on what matters to your team: * Response times exceeding your SLA * Error rates above acceptable levels * Resource utilization that could impact performance ### Regular Review Schedule time to review your observability data: * Weekly: Check for trends in usage and performance * Monthly: Review and adjust alert thresholds * Quarterly: Assess what metrics are most valuable ### Optimize Performance Observability itself uses resources. Balance insight with overhead: * Use sampling for high-volume traces * Set appropriate retention periods * Monitor the monitoring infrastructure ## Privacy and Security Your observability data may contain sensitive information. Hoppscotch automatically: * Sanitizes authentication tokens and credentials * Encrypts data in transit * Supports access controls for observability tools * Maintains audit trails of who accessed what data You can further customize what data is collected and retained based on your privacy requirements. ## Performance Impact The observability features are designed to have minimal impact on your instance: * Less than 5% increase in request latency * Approximately 3% additional CPU usage * Around 50MB extra memory per service These overheads are typically insignificant compared to the benefits of having comprehensive monitoring. ## Data Retention Configure how long to keep observability data: * **Traces**: Typically 7-30 days (detailed request information) * **Metrics**: Usually 30-90 days (aggregated performance data) * **Logs**: 30-90 days or longer for compliance needs Adjust these based on your storage capacity and regulatory requirements. ## Troubleshooting ### Data Not Appearing If you don't see data in your observability tools: 1. Verify the Collector is running and accessible 2. Check the endpoint configuration in Admin Dashboard 3. Review Collector logs for connection errors 4. Ensure firewall rules allow traffic between components ### High Resource Usage If the observability stack is using too many resources: 1. Reduce trace sampling rate 2. Adjust batch sizes in the Collector configuration 3. Consider deploying the Collector on dedicated infrastructure 4. Review and optimize retention policies ### Missing Traces If some traces are incomplete: 1. Verify all services are configured correctly 2. Check for network issues between components 3. Review sampling configuration 4. Ensure trace context is properly propagated ## Getting Help If you need assistance with observability: * Review the [OpenTelemetry Stack Setup Guide](/guides/articles/set-up-opentelemetry-stack-with-docker) * Contact Hoppscotch Enterprise Support for dedicated help * Join our community forums to discuss with other users Observability is available exclusively in Hoppscotch Enterprise Edition. [Learn more about Enterprise Edition](/documentation/self-host/enterprise-edition/getting-started) or [contact us](/support/getting-started/contact) for a demo. ## Next Steps Now that you understand observability, you can: * Set up the OpenTelemetry stack for your instance * Create custom dashboards for your team's needs * Configure alerts for critical metrics * Explore advanced features like performance profiling Monitor your instance effectively and maintain a reliable, high-performance API development platform for your organization. # Enterprise Edition prerequisites Source: https://docs.hoppscotch.io/documentation/self-host/enterprise-edition/prerequisites Review system requirements, OAuth provider setup, SMTP, and license key configuration needed before installing Hoppscotch Enterprise. Hoppscotch is a self-hosted API development platform, packaged as a set of Docker containers. You can install and run Hoppscotch on any operating system that can run a [Docker Engine](https://docs.docker.com/engine). You can use Hoppscotch on your local machine or a cloud provider of your choice. ## Enterprise License Key To start using Hoppscotch Enterprise, you will need to purchase a license from the [Hoppscotch Enterprise Store](https://enterprise.hoppscotch.com). Once you have purchased a license, you will receive an email with the license key. You can also find the license key in your [Hoppscotch Enterprise Dashboard](https://enterprise.hoppscotch.com/dashboard). * [Guide: Manage an Enterprise License Key](/guides/articles/manage-an-enterprise-license-key) ## System Requirements Hoppscotch is designed to run well on both small and large deployments. The minimum requirements to run Hoppscotch are an operating system that supports Docker and 4 CPU cores + 4GB of RAM to generate the build image and as little as 1 CPU core + 2GB of RAM to host the generated output files. * For support regarding horizontal scaling, please reach out to [support@hoppscotch.io](mailto:support@hoppscotch.io). ## Install Node.js, npm, pnpm ### Node.js + npm Install [`Node.js`](https://nodejs.org/en) (v18+) and [`npm`](https://www.npmjs.com) (v9+). * [Node.js + npm installation guide](https://nodejs.org/en/download) Verify Node.js and npm installation by running the following commands in your terminal: ```bash theme={null} node -v ``` ```bash theme={null} npm -v ``` ### pnpm Install [`pnpm`](https://pnpm.io) (v6+). * [pnpm installation guide](https://pnpm.io/installation) Verify pnpm installation by running the following command in your terminal: ```bash theme={null} pnpm -v ``` ## Docker Install [`Docker`](https://www.docker.com) (v20+). * [Docker installation guide](https://docs.docker.com/engine/install) Verify Docker installation by running the following command in your terminal: ```bash theme={null} docker -v ``` It is recommended to use Compose V2. To switch to Compose V2, use the `docker compose` CLI plugin or activate the **Use Docker Compose V2** setting in Docker Desktop. For more information, see the [Evolution of Compose](https://docs.docker.com/compose/compose-v2). ## Git Install [`Git`](https://git-scm.com) (v2+). * [Git installation guide](https://git-scm.com/download) Verify Git installation by running the following command in your terminal: ```bash theme={null} git --version ``` ## Email delivery (optional) Hoppscotch comes with support for easy integrations with 3rd party SMTP providers. You will need emails so that you can invite your team to use Hoppscotch and for emails to work, you will need to set up proper SMTP configuration as described below. To enable email delivery, you will need to generate a valid SMTP URL in the below format: ``` smtps://user@domain.com:pass@smtp.domain.com ``` For example, if you are using Gmail as your SMTP server your SMTP URL will look like something shown below: ``` smtps://user@gmail.com:pass@smtp.gmail.com ``` You can also use [mailcatcher](https://mailcatcher.me/) as a simple SMTP server. ### Custom SMTP configuration For more advanced needs, such as production-level email delivery or gaining more control over your email configurations, you can set up a custom SMTP server. To enable the custom mailer configuration, in addition to setting the `MAILER_USE_CUSTOM_CONFIGS` to `true`, you'll also need the following details in the specified format: | Requirement | Description | Format | | ------------- | -------------------------------------------- | -------------------------------------- | | SMTP Host | Address of your SMTP server | `smtp.customdomain.com` | | SMTP Port | Communication port used by your SMTP server | `587` for **TLS** or `465` for **SSL** | | SMTP User | Username for your SMTP account | `user@customdomain.com` | | SMTP Password | Corresponding password for your SMTP account | `custompass` | You can use services like [SendGrid](https://sendgrid.com/), [Amazon SES](https://aws.amazon.com/ses/), or your own SMTP server to set up custom email delivery with Hoppscotch. ## Postgres database Hoppscotch uses a Postgres database to store all the data. You can use any Postgres database provider of your choice - hosted locally or on a cloud provider. Make sure you have a valid Postgres database URL in the below format: ``` postgresql://username:password@url:5432/dbname ``` ## ClickHouse Hoppscotch uses ClickHouse to store all audit logs. You can use a locally hosted ClickHouse instance via [Docker](https://hub.docker.com/r/clickhouse/clickhouse-server) or a [managed instance](https://clickhouse.com/cloud). Ensure that the values for the following are assigned properly in admin dashboard. ```bash theme={null} #ClickHouse Config CLICKHOUSE_HOST=************** CLICKHOUSE_USER=default CLICKHOUSE_PASSWORD='' ``` You can enable/disable audit logging from your instance of Hoppscotch from admin dashboard. You can read more about audit logs [here](/guides/articles/audit-logs). ## OAuth You also need to configure an OAuth provider to enable third-party authentication. Hoppscotch supports the following OAuth providers: 1. Email 2. GitHub 3. Google 4. Microsoft 5. SAML SSO 6. Open ID Connect ### Choosing OAuth Providers Hoppscotch allows you to choose which authentication providers to enable for your workspace during the onboarding flow in the admin dashboard. You can easily select from options like Google, GitHub, Microsoft, SAML, Open ID Connect and Email directly through the setup interface. ```yaml theme={null} VITE_ALLOWED_AUTH_PROVIDERS=GOOGLE,GITHUB,MICROSOFT,EMAIL,SAML,OIDC ``` ### Configuring SAML You may use services like [OneLogin](https://www.onelogin.com/) or [Okta](https://www.okta.com/) or other services to fetch the following parameters for SAML. ```yaml theme={null} SAML_ISSUER=********** SAML_AUDIENCE=nestjs-saml SAML_CALLBACK_URL=http://localhost:3170/v1/auth/saml/callback SAML_CERT=********** SAML_ENTRY_POINT=********** SAML_WANT_ASSERTIONS_SIGNED=true SAML_WANT_RESPONSE_SIGNED=false ``` ### Configuring OpenID Connect You may use services like [OneLogin](https://www.onelogin.com/) or [Okta](https://www.okta.com/) or other services to fetch the following parameters for OIDC. ```yaml theme={null} OIDC_PROVIDER_NAME=************************************************ OIDC_ISSUER=************************************************ OIDC_AUTH_URL=************************************************ OIDC_TOKEN_URL=************************************************ OIDC_USER_INFO_URL=************************************************ OIDC_CLIENT_ID=************************************************ OIDC_CLIENT_SECRET=************************************************ OIDC_CALLBACK_URL=http://localhost:3170/v1/auth/oidc/callback OIDC_SCOPE=openid profile email ``` ### Configuring third-party providers To configure the third-party authentication, you will need to generate a valid OAuth client ID and client secret for the OAuth provider of your choice. You will also need to provide a valid callback URL for the OAuth provider. For example, if you are using GitHub as your OAuth provider, you will need to generate a valid OAuth client ID and client secret for GitHub. You will also need to provide a valid callback URL for GitHub. The credentials for the GitHub OAuth provider can be entered during onboarding in the admin dashboard, and will look like the following: ```yaml theme={null} GITHUB_CLIENT_ID=***** GITHUB_CLIENT_SECRET=***** GITHUB_CALLBACK_URL=http://localhost:3170/v1/auth/github/callback GITHUB_SCOPE=user:email # Set to 'true' if you are using github enterprise IS_GITHUB_ENTERPRISE_ENABLED=false # Change domain to respective org domain, if using Github Enterprise Cloud use github.com as domain GITHUB_AUTHORIZATION_URL=https://{domain}/login/oauth/authorize GITHUB_TOKEN_URL=https://{domain}/login/oauth/access_token # If using Github Enterprise Cloud use api.github.com as domain for 2 fields below GITHUB_USER_PROFILE_URL=https://{domain}/users GITHUB_USER_EMAIL_URL=https://{domain}/user/emails ``` The `CALLBACK_URL` variable is the URL that is invoked after the authorization is done and it follows the pattern `http://localhost:3170/v1/auth/[auth_provider_name]/callback`. The `SCOPE` variable defines the scope of the data that the OAuth provider passes on to Hoppscotch. The links to configure OAuth for various providers are given below: 1. [**GitHub**](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app) (scope: email) 2. [**Google**](https://developers.google.com/identity/gsi/web/guides/get-google-api-clientid#get_your_google_api_client_id) (scope: email, profile) 3. [**Microsoft**](https://learn.microsoft.com/en-us/azure/active-directory/develop/scenario-web-app-sign-user-app-registration?tabs=nodejs#register-an-app-by-using-the-azure-portal) (scope: user with read permission) It is recommended that you secure your deployments by issuing TLS certificates and using **HTTPS** since we use **secure HTTP cookies** for authenticating users. ## Support for standard `HTTP/s` ports From the December 2023 release onwards containers now support ingress via standard HTTP/S ports on port `80` and `443` by default, moving forward it is recommended users switch to using these ports. We currently do still support the services being exposed from ports `3000`, `3100` and `3170` respectively but support for this will be dropped in the future and all containers will work over standard HTTP/s ports. # Set up and access Enterprise Edition Source: https://docs.hoppscotch.io/documentation/self-host/enterprise-edition/setup-and-access Complete the initial setup of Hoppscotch Enterprise Edition by creating an admin account, activating your license, and configuring access. After successfully running the necessary containers, the next step involves creating an administrator account to manage Hoppscotch. The system automatically designates the first user who logs in through the admin dashboard as the administrator. ## Creating an administrator account 1. Open a new browser tab and visit [`http://localhost:3100`](http://localhost:3100). 2. This will grant you access to the admin dashboard. 3. Login using your credentials or create a new account. 4. The first user to log in will be given administrator privileges. Learn how to manage your Hoppscotch instance using the admin dashboard. ## Accessing the Hoppscotch app With the administrator account set up, you can now start using the Hoppscotch app for API testing and development. 1. Open a new browser tab and visit [`http://localhost:3000`](http://localhost:3000). 2. Begin testing and developing your APIs seamlessly with Hoppscotch. Hoppscotch Enterprise Edition is available for on-premise deployment with priority support. [Contact Hoppscotch Support](/support/getting-started/contact) # Enterprise Edition telemetry Source: https://docs.hoppscotch.io/documentation/self-host/enterprise-edition/telemetry Understand what telemetry data Hoppscotch Enterprise Edition collects, how it is used, and how to manage anonymous usage analytics. Telemetry in Hoppscotch Self-Host refers to anonymous data shared with Hoppscotch. This helps identify the usage patterns of Hoppscotch. # Data collected by Hoppscotch Hoppscotch does not capture any data from your APIs. All captured data is anonymous and pertains to instance usage. ## Instance usage The instance usage ping is sent once a week to indicate that the instance is operational. You can disable this event by navigating to the settings page and turning off data sharing settings. ```json theme={null} { "uuid": "976fcae1-4079-4e83-881a-48723f694475", "event": "sh_instance", "properties": { "type": "ENTERPRISE", "total_user_count": 10, "total_workspace_count": 2, "version": "2024.3.0", "$lib": "posthog-node", "$lib_version": "3.6.3", "$geoip_disable": true, "$ip": "127.0.0.1", "$sent_at": "2024-02-20T06:14:20.041000+00:00", "$plugins_succeeded": [ "GeoIP (8000)" ], "$plugins_failed": [], "$plugins_deferred": [] }, "timestamp": "2024-02-20T06:14:20.591000Z", "team_id": 15871, "distinct_id": "9bdec3aae9330af51ba91313d3de99b46ae928da", "elements_chain": "", "created_at": "2024-02-20T06:14:20.835000Z" } ``` ## Instance usage for billing The Hoppscotch Enterprise edition sends an additional event to our licensing server to assist with billing. This event is triggered every 12 hours. The licensing server verifies the instance's license and we send the license status and number of seats used as query parameters. Once the license key is validated, the server returns a signed/encrypted text, which the enterprise instance uses to verify the source of the validation and converts it and stores it as a JSON similar to the one below. ```json theme={null} { "status": "valid", "issuedTo": "AYQHAG$T1", "seats": 10 } ``` If you require offline license verification, you can request an offline license key by contacting us at [support@hoppscotch.io](mailto:support@hoppscotch.io). # Turning off data sharing You can turn off your data sharing preferences from your Hoppscotch admin dashboard by heading over to the Data Sharing section in the settings page. # User groups Source: https://docs.hoppscotch.io/documentation/self-host/enterprise-edition/user-groups Create and manage user groups to control permissions and roles in shared workspaces. Assign members to groups for structured access control. User groups are a powerful feature that enables admins to manage user permissions and roles within a shared workspace. This structured approach allows for efficient control over access and actions, ensuring that users can only perform tasks relevant to their roles. ## Creating a User Group 1. Navigate to the **Admin Dashboard**. 2. Click on the **User** page > **User Groups** tab. 3. Click on the **Create Group** button. 4. Enter a **name** for the group. 5. Optionally, add a **description** to clarify the group's purpose. 6. Click on the **Create** button to finalize the group creation. ## Adding Users to a Group 1. In the **User Groups** tab, select the group you want to add users to. 2. Click on the **Add Users** button. 3. In the pop-up window, search for and select the users you want to add. 4. Click on the **Add** button to confirm your selection. ## Group Permissions User groups can have different permissions based on their roles. Common permissions include: * **Viewer**: Can view workspace data but cannot make changes. * **Editor**: Can view and edit workspace data, but cannot manage user permissions. * **Owner**: Has full control over the workspace, including managing users and permissions. When creating or editing a group, admins can assign these roles to users within the group to ensure they have the appropriate level of access. ## Managing User Groups User groups can be managed by admins to ensure that the right users have the appropriate permissions. This includes: * **Editing Group Details**: Admins can modify the group's name and description by selecting the group and clicking on the **Edit** button. * **Removing Users**: To remove users from a group, select the group, click on the **Manage Users** button, and then remove users as needed. * **Deleting Groups**: If a group is no longer needed, admins can delete it by selecting the group and clicking on the **Delete Group** button. ## Best Practices * **Define Clear Roles**: Establish clear roles and responsibilities for each user group to avoid confusion and ensure accountability. * **Regularly Review Groups**: Periodically review user groups to ensure they still align with the organization's needs and that users have the appropriate permissions. * **Use Descriptions**: Utilize the description field to provide context for each group, making it easier for admins to understand the purpose of each group at a glance. * **Limit Group Size**: Keep user groups manageable in size to facilitate easier management and communication. # SCIM Integration for User and Group Provisioning Source: https://docs.hoppscotch.io/documentation/self-host/enterprise-edition/user-provisioning Set up SCIM integration in Hoppscotch Enterprise to automate user and group provisioning, deprovisioning, and membership sync with identity providers. Identity and access management can become overwhelming as your organization scales. **SCIM (System for Cross-domain Identity Management)** offers a standardized way to handle user and group provisioning, updates, and deprovisioning. With SCIM integration, Hoppscotch connects directly to your Identity Provider (IdP), helping you manage users and group memberships in one place and reflect those changes across systems. ## SCIM support in Hoppscotch Hoppscotch supports SCIM 2.0 push provisioning for the following resources: * **Users** (`/scim/v2/Users`) for creating, updating, and deprovisioning users. * **Groups** (`/scim/v2/Groups`) for creating, updating, and deleting groups, and syncing group membership. ## Setting Up SCIM Provisioning Follow the steps below to configure SCIM-based user provisioning in Hoppscotch and integrate it with your Identity Provider (IdP). ### 1. Enable SCIM in Hoppscotch * Open the **Admin Dashboard** and navigate to the **Configurations** section. * Find the **SCIM Provisioning** option under **User Provisioning** block and enable it. * Copy the **SCIM Base URL (`http(s):///scim/v2`)** provided after activation, as it will be needed for the integration. ### 2. Generate an InfraToken * Go to the **[InfraTokens](/documentation/self-host/enterprise-edition/admin-dashboard#infra-tokens)** section of the dashboard. * Create a new token for SCIM-related operations. * Copy the InfraToken and store it securely, as it will be used to authenticate SCIM requests from your IdP. ### 3. Configure SCIM in your Identity Provider (example: Okta) * Log in to your [Okta](https://www.okta.com/) dashboard, select your application, and navigate to the application's settings. * Enable SCIM provisioning under the **General** tab. * Go to the **Provisioning > Integration** section: * Paste the **SCIM Base URL** you copied from Hoppscotch. * Specify the unique identifier field for users (e.g., `email`) and configure provisioning actions (e.g., Import New Users, Profile Updates, Push New Users, Push Profile Updates) according to your requirements. * Use the `InfraToken` generated in the Hoppscotch Admin Dashboard as the **Authorization Token** and save the configuration. * Under **Provisioning > To App**, enable the following actions: * **Create Users** * **Update User Attributes** * **Deactivate Users** * **Push Groups** Save the settings once done. ## SCIM Group push provisioning SCIM Group push lets your IdP (such as Okta or Azure AD) provision Hoppscotch `UserGroups` and their members through `/scim/v2/Groups`. ### Supported Group endpoints * `GET /Groups/:id` * `GET /Groups?filter=displayName eq "..."` * `POST /Groups` (idempotent; existing groups are reused by `displayName`) * `PATCH /Groups/:id` (RFC 7644 PatchOp for member add/remove/replace and group rename) * `PUT /Groups/:id` (full replace of `displayName` and members) * `DELETE /Groups/:id` ### Member resolution behavior * Group members are matched by the returned SCIM user `id` when available. * If a member user is unknown, Hoppscotch finds or creates the user using the email in the member `display` field. * This ensures group push can create missing users and then attach them to the provisioned group. ### Notes and scope * Group identity is synced using the SCIM resource `id` and unique `displayName`. * Linking a provisioned user group to a Team remains a manual admin action. * SCIM feature gating and token auth follow the same setup used for user provisioning. ## Add a custom attribute SCIM supports extending the user schema to include custom fields to meet your organization's specific requirements: * In Okta, head to **Directory > Profile Editor** and locate the SCIM application. * Click **Add Attribute** to create a custom attribute you wish to include in the provisioning process. * Fill in the required fields and assign a valid **External namespace**. For SCIM 2.0, the following namespaces are supported in Okta: ```bash theme={null} # Use this for basic user attributes urn:ietf:params:scim:schemas:core:2.0:User # Use this for enterprise-specific user extensions urn:ietf:params:scim:schemas:extension:enterprise:2.0:User ``` * Once finished, click **Save Attribute** to apply the changes. The **custom attribute** will now be automatically synchronized during user creation or updates. Once configured, assigning users and groups to the application triggers provisioning in Hoppscotch. Users can be created or updated automatically, groups can be pushed with membership sync, and unassigned users can be deprovisioned from your instance. # Getting started with self-hosting Source: https://docs.hoppscotch.io/documentation/self-host/getting-started Self-host Hoppscotch on your own infrastructure with full data ownership. Choose between Community Edition and Enterprise Edition. This section will help you get started with self-hosting your instance of Hoppscotch. If you are looking to self-host your instance of [Hoppscotch](https://github.com/hoppscotch/hoppscotch) you will need to have to install a few other dependencies. Go through our prerequisite guide below to install all the required dependencies and have the required information ready. Hoppscotch Community Edition is free and open-source. It is licensed under the MIT License. You can use it for personal and commercial projects. It is a great choice for individuals and small teams. SAML-based SSO, on-prem deployment, audit logs, and more. Hoppscotch Enterprise Edition is a self-hosted version of Hoppscotch Cloud with enterprise-ready features for teams and organizations. Hoppscotch Enterprise Edition is available for on-premise deployment with priority support. [Contact Hoppscotch Support](/support/getting-started/contact) *** ## Hoppscotch Self-Host is available in two editions 1. Community Edition 2. Enterprise Edition Here's a quick comparison of the two editions: | **Self-Host** | **Community Edition** (CE) | **Enterprise Edition** (EE) | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | We build software in the open, with permissive licenses and thriving communities because we believe investing in open source will help leave the world a little better than we found it. | Deploy Hoppscotch on-premise with our support. Securely manage, organize, and accelerate API-first development at scale. Hoppscotch Self-Host is the one-stop solution to own control over your APIs, data, and privacy. | | Distribution | Open-source. | Open-core. | | Installation | Install, administer, and maintain on your own. | Install, administer, and maintain on your own with our **priority support**. | | Upgrades and maintenance | Update it yourself. Quarterly releases. | Guaranteed quarterly updates. Take advantage of the priority support for **early birds**. | | Hosting and Deployment | Self-managed so you can deploy in your own data center or cloud capacity. | Self-managed so you can deploy in your own data center or cloud capacity. | | OAuth Providers | Configure OAuth providers such as Email, GitHub, Google, and Microsoft for third-party authentication. | Configure advanced OAuth providers like **SAML-based SSO and OpenID Connect**, along with Email, GitHub, Google, and Microsoft, to enable comprehensive third-party authentication options. | | Workspace Management | Invite Workspace Members, Assign roles and remove members with Owner rights. | Invite Workspace Members, Assign roles and remove members with Owner rights. | | Advanced admin tools | Not included. | Access **advanced admin tools** to govern, audit, and secure user permissions and data. Includes features like user permissions, audit logs, and more. | | Access Controls | Not included. | Implement robust access controls, including **domain whitelisting and site protection**, to enhance security and restrict access to authorized users only. | | Support | Community forums. | **Dedicated support from the Hoppscotch team** to provide critical response, help establish best practices, and be an on-demand resource for ongoing questions. | | Pricing | Free. | \$19/user/mo
Billed monthly.
[Book a demo for a free trial](https://cal.com/hoppscotch/enterprise-demo). | Jump to the [**Community Edition**](/documentation/self-host/community-edition/getting-started) or [**Enterprise Edition**](/documentation/self-host/enterprise-edition/getting-started) guide to get started. # Index Source: https://docs.hoppscotch.io/guides/articles Browse all Hoppscotch guides and tutorials covering API testing, self-hosting, GraphQL, OpenTelemetry, enterprise features, and more. Interested in writing an article about Hoppscotch? Contact us at `support@hoppscotch.io`. Representational State Transfer (REST) APIs are a core part of communication between a web/mobile client and a server... Hoppscotch provides you with a minimal and blazing platform to design, develop and test your APIs... The GraphQL schema is at the core of any GraphQL server. It defines the capabilities of the API and specifies how clients can access that data... If an update causes issues with Hoppscotch Desktop, you can downgrade to a previous version and restore your data from an automatic backup... # Community Articles Widgets are interactive components that can be embedded in HTML pages to enhance user experience... We're looking for more articles! If you have written an article about Hoppscotch, please [open a pull request](https://github.com/hoppscotch/docs) on our documentation repository. We'll be happy to add it to this list. # Audit Logs in Hoppscotch Source: https://docs.hoppscotch.io/guides/articles/audit-logs Enable and use audit logs in Hoppscotch Enterprise to track workspace activity, collection changes, and user actions for compliance. In Enterprise Hoppscotch, a record of all actions taken on the platform is saved which can be used to know what events happened, who performed them, and when they occurred. With the information present users may be able to draw insights related to the platform. ### Log Format Every event that occurred on the platform is saved in the following format. ```json theme={null} { "event": "", "timestamp": "", "user": { "id": "", "email": "", "name": "" }, "group": { "type": "TEAM | USER | ADMIN", "id": "", "name": "" }, "resource": { "id": "", "type": "", "name": "", "metadata": "" }, "statusCode": "", "errorMessage": "", "result": "", "server_version": "" } ``` | Data | Description | Details | | --------------- | ----------------------------------------------------- | -------------------------------- | | event | Action performed | | | timestamp | The date and time of a logged event | | | user | The user who performed an event | `id`, `email`, `name` | | group | Where the user belongs to in the context of the event | `type`, `id` | | resource | Upon what the action is being carried out | `id`, `type`, `name`, `metadata` | | statusCode | Status code for the action response | | | errorMessage | Error description if action failed | | | result | Status of the action | | | server\_version | Server version being run currently | | An example of an audit log: ```json theme={null} { "event": "admin.team.create", "timestamp": "2023-08-30 07:03:05", "user": { "id": "cllxa1zqt000gp91zaq6tj93d", "email": "John@hoppscotch.io", "name": "John Doe" }, "group": { "type": "ADMIN", "id": "cllxa1zqt000gp91zaq6tj93d" }, "resource": { "type": "TEAM", "metadata": "{\"id\":\"cllxe4ji4000op91zucsbwazj\",\"name\":\"Fellowship of the Hopp\"}" }, "statusCode": 200, "errorMessage": "", "result": "SUCCESS", "server_version": "2023.4.8" } ``` ### Tracked Events The following table contains all the events that are logged currently. | EVENT | EVENT DESCRIPTION | | --------------------------------- | ------------------------------------------------------------------------------------ | | admin.users.invite | Event for inviting multiple users to join the platform | | admin.user.invite | Event for inviting a single user to join the platform | | admin.user.remove | Event for removing a user from the platform | | admin.user.makeAdmin | Event for elevating a user to admin status | | admin.user.makeNormal | Event for demoting an admin user to normal user status | | admin.team.create | Event for creating a new team | | admin.team.user.changeRole | Event for changing the role of a user in a team | | admin.team.user.remove | Event for removing a user from a team | | admin.team.user.add | Event for adding a user to a team | | admin.team.rename | Event for renaming a team | | admin.team.delete | Event for deleting a team | | admin.user.revoke | Event for revoking a user's team invitation | | user.auth.magicLinkSent | Event for when a magic link is sent to a user | | user.auth.loggedIn | Event for when a user logs in | | user.auth.tokenRefresh | Event for when a user's auth token is refreshed | | user.auth.loggedOut | Event for when a user logs out | | user.auth.adminVerify | Event for when we verify if a user is an admin | | user.session.update | Event for updating a user's app session | | user.account.delete | Event for deleting a user's account | | user.shortcode.create | Event for creating a shortcode | | user.shortcode.revoked | Event for deleting a shortcode | | team.create | Event for creating a new team | | team.user.leave | Event for when a user leaves a team | | team.user.remove | Event for removing a user from a team | | team.rename | Event for renaming a team | | team.delete | Event for deleting a team | | team.member.roleUpdate | Event for changing a user's role in a team | | team.check | Event for checking if a team exists | | team.member.check | Event for checking if a user is a member of a team | | team.collection.createRoot | Event for creating a root team collection | | team.collection.import | Event for importing a collection from a JSON string | | team.collection.replace | Event for replacing an existing collection with new data | | team.collection.createChild | Event for creating a child collection | | team.collection.rename | Event for renaming a collection | | team.collection.delete | Event for deleting a collection | | team.collection.move | Event for moving a collection | | team.collection.updateOrder | Event for updating the order of collections | | team.collection.collectionCheck | Event for checking if a collection exists in a team | | team.environment.environmentCheck | Event for checking if an environment exists in a team | | team.environment.create | Event for creating an environment | | team.environment.delete | Event for deleting an environment | | team.environment.update | Event for updating an environment | | team.environment.clear | Event for clearing the contents of an environment | | team.environment.duplicate | Event for duplicating an environment | | team.invitation.create | Event for creating a team invitation | | team.invitation.revoke | Event for revoking a team invitation | | team.invitation.accept | Event for accepting a team invitation | | team.invitation.inviteCheck | Event for checking if an invitation exists | | team.request.create | Event for creating a team request | | team.request.update | Event for updating a team request | | team.request.delete | Event for deleting a team request | | team.request.updateOrder | Event for updating the order of team requests | | team.request.move | Event for moving a team request | | team.request.requestCheck | Event for checking if a request exists in a team | | team.request.roleCheck | Event for checking if a user has the relevant role to perform an action in a request | | user.session.update | Event for updating a user's app session | | user.delete | Event for deleting a user | | user.collection.createRoot | Event for creating a root user collection | | user.collection.createChild | Event for creating a child user collection | | user.collection.rename | Event for renaming a user collection | | user.collection.delete | Event for deleting a user collection | | user.collection.move | Event for moving a user collection | | user.collection.updateOrder | Event for updating the order of user collections | | user.collection.import | Event for importing a collection | | user.environment.create | Event for creating a user environment | | user.environment.update | Event for updating a user environment | | user.environment.delete | Event for deleting a user environment | | user.environment.deleteAll | Event for deleting all personal environments of a user | | user.environment.clearGlobal | Event for clearing the global environments for a user | | user.history.create | Event for creating a user history | | user.history.toggleStar | Event for toggling the star on a user history | | user.history.delete | Event for deleting a user history | | user.history.deleteAll | Event for deleting all user histories | | user.request.create | Event for creating a user request | | user.request.update | Event for updating a user request | | user.request.deleted | Event for deleting a user request | | user.request.move | Event for moving a user request | | user.settings.create | Event for creating user settings | | user.settings.update | Event for updating user settings | # Improving your API workflow Source: https://docs.hoppscotch.io/guides/articles/improving-your-api-workflow Streamline your API development workflow with Hoppscotch using collections, environments, scripts, and team collaboration features. Hoppscotch provides you with a minimal and blazing platform to design, develop and test your APIs. Hoppscotch enables you to quickly get started and even helps you to organize your work to help you improve your workflow. Hoppscotch provides you with three major ways for you to manage your APIs and enhance your development workflow: * Collections * Environments * Workspaces ## Collections Collections help you save and organize your API requests. You can create collections and add requests to them to share with your team or to use later. You can also import and export collections from Hoppscotch, OpenAPI, and Postman. ## Environments Environments provide you the functionality to create key-value pairs that can be used as variables in your request URL, headers, and even as auth tokens. You can create several such key-value pairs and group them under a single environment. Environments are self-isolated from each other and an active environment needs to be selected if you have multiple environments created. ## Workspaces Workspaces help you organize your requests, collections, and environments for specific purposes and project stages. You can create unlimited Workspaces and invite as many collaborators as needed in Hoppscotch. Whether you're working solo or with a team, you can choose between **Personal and Team Workspaces** to fit your needs. A Personal Workspace is a private area exclusively for you, where collaboration isn't possible. Within a Personal Workspace, you can choose to sync your collections and environment data either with the [Hoppscotch cloud](https://hoppscotch.io) or **keep it stored locally**. To learn more about setting up new Workspaces and collaborating with your team on APIs, head over to our [documentation for Workspaces](https://docs.hoppscotch.io/documentation/features/workspaces). # Managing your Enterprise License Key Source: https://docs.hoppscotch.io/guides/articles/manage-an-enterprise-license-key Activate, renew, and manage your Hoppscotch Enterprise Edition license key. Troubleshoot license issues and understand key expiration. This guide provides step-by-step instructions for managing your Hoppscotch Enterprise Edition license key. If you plan to self-host the Hoppscotch Enterprise Edition, you must obtain a License Key. ## Creating an account To initiate the process, you need to create an account on the Hoppscotch Enterprise Dashboard. 1. Visit [enterprise.hoppscotch.com](https://enterprise.hoppscotch.com) and provide your email. 2. A magic link will be sent to your email address. 3. Click on the magic link to log in, and you will be redirected to a screen to input your organization's information. Continue by clicking "Next" and enter information about the organization. Continue by clicking "Next" and enter the personal information of the individual responsible for the purchase on behalf of the organization. To proceed with the purchase, review and accept the end user license agreement. ## Booking a demo After agreeing to the license terms, you can schedule a demo with our team. Click the "Book a Demo" button. ## Making the purchase While you can directly purchase by clicking the "Subscribe" button, we recommend scheduling a call with us for personalized assistance. 1. Click the "Subscribe" button. 2. Enter the number of seats required for the license. 3. Click the **Create** button to proceed to checkout and complete the payment. Upon successful payment, your License Key will be available on the dashboard. Copy it and paste it into the `.env` file in your project's root directory. You can now start utilizing Hoppscotch Enterprise Edition. ## Updating your license With a valid license, you can manage it to update the seat count or generate a new license under the same account through the enterprise dashboard. ## Offline license verification If you require offline license verification, you can request an offline license key by contacting us at [support@hoppscotch.io](mailto:support@hoppscotch.io). For more information on self-hosting Hoppscotch Enterprise Edition, consult the guide on [Self-Hosting Hoppscotch Enterprise Edition](/documentation/self-host/enterprise-edition/getting-started). # RESTful API testing with Hoppscotch Source: https://docs.hoppscotch.io/guides/articles/restful-api-testing-with-hoppscotch Follow a hands-on tutorial to test RESTful APIs with Hoppscotch. Send GET and POST requests, add headers, and inspect JSON responses. Representational State Transfer (REST) APIs are a core part of communication between a web/mobile client and a server. The majority of web-based applications depend on REST APIs to fetch and modify data thus separating the data processing part from the front-end. Hoppscotch provides a fast and intuitive platform to develop and test REST APIs making it easier for developers worldwide to work efficiently. ## Understanding REST REST usually uses the Hypertext Transfer Protocol (HTTP) to set up communication between the client and the server. REST APIs ensure that the server transfers information in a standard format. A REST API call generally contains the following steps - 1. The client sends a request to the server. 2. The server authenticates the client and ensures that the client is authorized to request the information. 3. The server accepts the requests and processes them. 4. The server responds with a code to tell the client if the request was successful or not and sends the requested information if the request was successful. Whenever a client requests information, the server always sends back a status code to indicate the status of the request. These are called HTTP status codes and are grouped into five types. | Status Code | Response Type | | ------------- | ------------- | | 1xx (100-199) | Informational | | 2xx (200-299) | Success | | 3xx (300-399) | Redirection | | 4xx (400-499) | Client error | | 5xx (500-599) | Server error | REST APIs also support HTTP methods to do operations on data. Hoppscotch supports the following methods out of the box. | HTTP Method | Usage | | ----------- | ------------------------------------------------------------------ | | GET | Retrieve resource from a server | | POST | Create or send new resource | | PUT | Updating resource, can also be used for creating resource | | PATCH | Similar to PUT, can be used to modify resources | | DELETE | Delete resource from the server | | HEAD | Read HTTP header information | | CONNECT | To start a two-way communication with resource | | OPTIONS | Requests permitted communication options for a given URL or server | | TRACE | Used to debug the path to the target resource | | CUSTOM | Create custom methods as per your need | ## Using Hoppscotch to test your REST APIs Hoppscotch provides you with a minimal yet robust platform to test your REST APIs. The REST platform is the default platform you see when you open Hoppscotch. You can enter the API endpoint and choose the HTTP method according to your needs from the dropdown menu. Once it is configured, click on the "**Send**" button and you will see the response returned by the server. It's that simple. Now try it yourself, copy the below API endpoint, and create a request. ``` https://echo.hoppscotch.io ``` ### Locally served APIs If you are planning to use Hoppscotch to test your locally served APIs, it is recommended that you install the Hoppscotch Browser Extension. Once installed, switch the interceptor on Hoppscotch to Browser Extension from the settings page or bottom bar to add support for [localhost](http://localhost) protocols. ### Adding parameters to your request You can also parameterize your URLs by specifying parameters in the URL itself or adding parameters manually in the parameters tab. To add a parameter in the URL, append `?` at the end of the URL and add a parameter in `key=value` format. ### Working with environment variables Environment variables allow you to store and reuse values in your requests and scripts. You can create a new environment by clicking the environments icon on the sidebar and clicking the `new` button. If you have more than one environment, select the environment whose variables you want to access. You can access the variables in the request section by referencing the variable in the following format `<>`. ### Authentication tokens Hoppscotch has support for various types of authentication mechanisms such as Basic Auth, Bearer Token, OAuth 2.0, and API Key. You can configure this using the Authorization tab on the request section of Hoppscotch. These are just a few of the amazing set of features that Hoppscotch provides you to make your life easier as a developer. In addition to this, Hoppscotch supports features such as collections to save your requests, pre-requests to add dynamic behavior to your requests and so much more. # Self-Host Hoppscotch on your own servers Source: https://docs.hoppscotch.io/guides/articles/self-host-hoppscotch-on-your-own-servers Self-host Hoppscotch on your own servers with Docker. Configure OAuth providers, SMTP, environment variables, and deploy step by step. Self-hosting Hoppscotch gives you complete control over your API development workflow and allows you to deploy Hoppscotch in your own data center or cloud, giving you greater control over data and security. Self-hosted Hoppscotch comes in two variants - [Community](https://docs.hoppscotch.io/documentation/self-host/community-edition/getting-started) and [Enterprise Edition](https://docs.hoppscotch.io/documentation/self-host/enterprise-edition/getting-started), both of which can be deployed on systems that support Docker. You can host Hoppscotch on your servers, providing a private workspace for the individuals or teams using it. This guide covers the basics of self-hosting Hoppscotch, including the configurations and settings needed to get started. ## Pre-requisites Before you start ensure that your system or environment meets the following requirements: * [Node.js (v18+) and npm (v9+)](https://nodejs.org/en/download/package-manager) - Ensure that both Node.js and npm are up-to-date to support the latest features and security patches. * [pnpm](https://pnpm.io/installation) (v6+) - Recommended for efficient package management and faster installations. * [Docker](https://docs.docker.com/engine/install) (v20+) - Docker should be properly installed and configured for containerization of your Hoppscotch instance. * [Git](https://git-scm.com/download) - Required for version control and managing Hoppscotch source code. Visit our [documentation](https://docs.hoppscotch.io/documentation/self-host/community-edition/prerequisites) for a detailed guide on installing the prerequisite software. ## Configuring the Environment Create a `.env` file in your working directory, copy the example environment variable configurations provided below into it, and then replace the example values with your actual values. Ensure that there are **NO QUOTES** encapsulating the values of the environment variables and **NO SPACES** around the equals sign (`=`). ```yaml theme={null} #-----------------------Backend Config------------------------------# # Prisma Config DATABASE_URL=postgresql://postgres:testpass@hoppscotch-db:5432/hoppscotch # Sensitive Data Encryption Key while storing in Database (32 characters) DATA_ENCRYPTION_KEY=******************************** # Whitelisted origins for the Hoppscotch App. # This list controls which origins can interact with the app through cross-origin comms. # - localhost ports (3170, 3000, 3100): app, backend, development servers and services # - app://localhost_3200: Bundle server origin identifier # NOTE: `3200` here refers to the bundle server (port 3200) that provides the bundles, # NOT where the app runs. The app itself uses the `app://` protocol with dynamic # bundle names like `app://{bundle-name}/` WHITELISTED_ORIGINS="http://localhost:3170,http://localhost:3000,http://localhost:3100,app://localhost_3200,app://hoppscotch" #-----------------------Frontend Config------------------------------# # Base URLs VITE_BASE_URL=http://localhost:3000 VITE_SHORTCODE_BASE_URL=http://localhost:3000 VITE_ADMIN_URL=http://localhost:3100 # Backend URLs VITE_BACKEND_GQL_URL=http://localhost:3170/graphql VITE_BACKEND_WS_URL=wss://localhost:3170/graphql VITE_BACKEND_API_URL=http://localhost:3170/v1 # Terms Of Service And Privacy Policy Links (Optional) VITE_APP_TOS_LINK=https://docs.hoppscotch.io/support/terms VITE_APP_PRIVACY_POLICY_LINK=https://docs.hoppscotch.io/support/privacy # Set to `true` for subpath based access ENABLE_SUBPATH_BASED_ACCESS=false #-----------------------Container Runtime Config---------------------# # (Optional) Caddy's in-container HTTP port. Defaults to 80 when unset. # Set a free port (for example 8000) to run the container under a non-root UID. # HOPP_ALTERNATE_PORT=8000 ``` ### 1. Database Configuration Hoppscotch uses a Postgres database to store all the data. You can use any Postgres database provider of your choice, hosted locally or on a cloud. Update the `DATABASE_URL` variable in your `.env` file with your custom database connection string, which should include the username, password, and database name. ```jsx theme={null} DATABASE_URL=postgresql://username:password@url:5432/dbname ``` ### 2. **SMTP Configuration** To invite your team to use Hoppscotch and enable email delivery, you'll need to configure SMTP settings properly. #### **2.1 Basic SMTP Configuration** For basic SMTP configuration, you can use [mailcatcher](https://mailcatcher.me). It runs a super simple SMTP server which catches any message sent to it to display in a web interface. You can set up mailcatcher using Docker with 2 below easy steps: 1. Pull the [Mailcatcher Image](https://hub.docker.com/r/dockage/mailcatcher) from Docker Hub, ```jsx theme={null} docker pull dockage/mailcatcher:0.9.0 ``` 2. With Mailcatcher set up on your machine, start the Mailcatcher container using `docker run` with the appropriate port mappings (`1080` for the web interface and `1025` for SMTP). > Docker containers are isolated from the host by default. When using localhost inside a Docker container, it refers to the container itself, and not the host machine. Since Hoppscotch runs inside a Docker container while Mailcatcher runs on the host machine, you'll need to use the **Docker bridge network IP** instead of `localhost` to ensure that the containerized application can communicate with the Mailcatcher service on the host. To find this IP address, run: > > ```jsx theme={null} > ip addr show docker0 > ``` > > Look for the inet address associated with the docker0 interface. It's typically in the **172.17.0.0/16** range but may vary based on your Docker network configuration. And If you're using **Docker Desktop**, you can use `host.docker.internal` instead of `localhost`. ```bash theme={null} docker run --name='mailcatcher' -d \ --publish=:1080:1080 \ --publish=:1025:1025 \ dockage/mailcatcher:0.9.0 ``` Visit `http://:1080` to access the Mailcatcher web interface and view email communications. Further, configure the below environment variables in your `.env` file: ```jsx theme={null} MAILER_SMTP_ENABLE=true MAILER_USE_CUSTOM_CONFIGS=false MAILER_ADDRESS_FROM=from@example.com MAILER_SMTP_URL=smtp://:1025 ``` #### **2.2 Custom Mailer Configuration** For advanced email delivery needs, such as for production environments, you can configure a custom email service by setting `MAILER_USE_CUSTOM_CONFIGS=true`. You can choose from services like [SendGrid](https://sendgrid.com/), [Amazon SES](https://aws.amazon.com/ses/), or your own SMTP server. Once you've set up your chosen service, update your `.env` file with the following details: ```jsx theme={null} MAILER_SMTP_HOST=smtp.domain.com MAILER_SMTP_PORT=587 MAILER_SMTP_SECURE=true MAILER_SMTP_USER=user@domain.com MAILER_SMTP_PASSWORD=pass MAILER_TLS_REJECT_UNAUTHORIZED=true ``` ### 3. OAuth Configuration To access the admin dashboard, you'll need to configure an OAuth provider. In the Community Edition, Hoppscotch supports: 1. Google 2. GitHub 3. Microsoft In the Enterprise Edition, support also includes **SAML SSO, OpenID Connect, and GitHub Enterprise**. Here's a quick guide to registering an OAuth application with GitHub: 1. Click your profile photo in the upper-right corner and select **Settings**. 2. In the left sidebar, scroll down and click **Developer Settings**. 3. Click **OAuth Apps** in the sidebar. 4. Click **New OAuth App**. 5. Enter the required information and specify the callback URL as indicated in your configuration. 6. After registering the application, copy the Client ID and Client Secret, and add them to your environment file. Similarly, you can follow the specific setup instructions for other OAuth providers to complete your configuration. ### 4. Subpath Access Subpath access allows you to host multiple services under a single domain by assigning each service a specific subpath. When `ENABLE_SUBPATH_BASED_ACCESS=true`, you can access all three services (Hoppscotch App, Admin Dashboard, Hoppscotch Backend) on the same domain using different routes. If subpath access is disabled **(`ENABLE_SUBPATH_BASED_ACCESS=false`)**, you will need to access the services on different ports. By default, the AIO container serves the app on port `80`. Ports below `1024` are privileged, so a non-root user can't bind them — a common restriction in rootless Docker, Podman, and hardened environments like OpenShift. On those setups, set `HOPP_ALTERNATE_PORT` to bind the app to a port at or above `1024` — see [running under a non-root user](/documentation/self-host/community-edition/install-and-build#running-under-a-non-root-user) for the full details. ## Installing dependencies, running migrations & building the image Once the environment variables are configured, you may now proceed to the next step of setting up the Hoppscotch instance. Ensure that the database instance is active and running at the `DATABASE_URL` specified in your `.env` file. ```jsx theme={null} docker ps ``` There are two ways to set up Hoppscotch: 1. **Using individual containers for the services** - Hoppscotch Backend, Hoppscotch Frontend and Hoppscotch Admin Dashboard. 2. **Using the AIO container** - a single container that provides all the services required to run Hoppscotch. For a streamlined setup, let's proceed with the AIO container. If you'd like to set up individual containers instead, [refer to the documentation](https://docs.hoppscotch.io/documentation/self-host/community-edition/install-and-build#using-individual-containers-for-the-services). Pull the container from DockerHub with the following command. If a specific version isn't provided, it will automatically pull the latest version: ```jsx theme={null} docker pull hoppscotch/hoppscotch ``` After pulling the Hoppscotch image from DockerHub, you need to run database migrations to set up the necessary tables. Use the following commands: ```jsx theme={null} docker run -it --entrypoint sh --env-file .env hoppscotch/hoppscotch # pnpm exec prisma migrate deploy ``` To launch Hoppscotch, run the container with the following command: ```jsx theme={null} docker run -p 3000:3000 -p 3100:3100 -p 3170:3170 --env-file .env --restart unless-stopped hoppscotch/hoppscotch ``` ## Accessing Admin Dashboard and Application * **Accessing the Admin Dashboard** * After successfully running the required containers, the next step is to create an **Admin** account. * To access the Admin Dashboard, visit [**`http://localhost:3100`**](http://localhost:3100/) if `ENABLE_SUBPATH_BASED_ACCESS=false`. * Log in with your credentials or create a new account to obtain admin privileges. * Once logged in, you'll find the Dashboard as your central hub for managing workspaces, overseeing user activities, and configuring OAuth environment variables directly from the Settings page. * **Accessing the Hoppscotch Application** * You can access the Hoppscotch application itself at `http://localhost:3000`. *** In conclusion, this guide has covered how to self-host Hoppscotch, helping you set everything up in one go. If you prefer visual guidance, check out the video below for a detailed walkthrough that complements the instructions provided here. For additional details on each step of self-hosting Hoppscotch, refer to our [documentation](https://docs.hoppscotch.io/documentation/self-host/getting-started).