Beeceptor Getting Started: Mock APIs & Intercept Requests (2026)

Getting started overview

Beeceptor facilitates the interception, inspection, and modification of HTTP requests and responses without requiring code changes to the target API or client application. The core workflow involves creating a unique Beeceptor endpoint, configuring it to handle specific request patterns or return predefined mock responses, and then directing your application's API traffic to this endpoint.

This guide details the steps to initiate Beeceptor usage, from account creation to executing and verifying your first intercepted request. It covers the necessary actions to establish a functional mock or proxy endpoint, enabling developers to quickly set up testing environments for API integrations or webhook implementations. Beeceptor supports various HTTP methods and response types, making it applicable for diverse testing scenarios like simulating network errors or delayed responses.

Before proceeding, ensure you have access to a web browser and a tool capable of making HTTP requests, such as curl, Postman, or a programming language's HTTP client library.

Create an account and get keys

Accessing Beeceptor’s features, including creating proxy endpoints and inspecting traffic, requires a registered account. Beeceptor does not use API keys for authenticating requests to its proxy endpoints directly; instead, access to your specific Beeceptor endpoints is controlled via the unique subdomain you create and your account login for the web interface.

1. Navigate to the Beeceptor homepage: Open your web browser and go to the official Beeceptor website.
2. Sign up or log in: Click on the 'Sign Up' or 'Get Started' button. You can register using your email address, or through third-party authentication providers like Google or GitHub. Complete the registration process by providing the required information and verifying your email if prompted.
3. Create a new endpoint: After logging in, you will be directed to the dashboard. Click on the 'Create Endpoint' or similar button to set up a new Beeceptor endpoint.
4. Choose a subdomain: You will be prompted to enter a unique subdomain for your Beeceptor endpoint (e.g., my-test-app). This will form your unique endpoint URL, such as https://my-test-app.proxy.beeceptor.com. Select a descriptive and memorable subdomain.
5. Confirm creation: Once the subdomain is chosen, confirm the creation. Beeceptor will provision your new endpoint, and you will be redirected to its inspection panel. This panel serves as your primary interface for viewing incoming requests and configuring mock responses.

Beeceptor's system does not issue traditional API keys or secret keys for direct API access to the proxy endpoints. Instead, the uniqueness of your endpoint's subdomain acts as the primary identifier, and all management and inspection are performed through the web-based control panel, secured by your account credentials. For advanced API interaction, the Beeceptor management API might require API tokens, but this falls outside the scope of basic endpoint usage.

Your first request

With your Beeceptor endpoint established, you can now direct HTTP traffic to it. This section demonstrates how to send a simple GET request and observe it within the Beeceptor interface.

Identify your endpoint URL

After creating your endpoint, its unique URL will be displayed prominently on the endpoint's dashboard. It will follow the format https://[your-subdomain].proxy.beeceptor.com. Copy this URL, as you will use it as the target for your API calls.

Send a request using cURL

Using curl is a common method for making HTTP requests from the command line:

1. Open your terminal or command prompt.
2. Execute the following curl command, replacing [YOUR_BEECEPTOR_SUBDOMAIN] with your actual subdomain:

   curl -X GET "https://[YOUR_BEECEPTOR_SUBDOMAIN].proxy.beeceptor.com/test-path?param1=value1" -H "User-Agent: BeeceptorFirstTest"

   This command sends a GET request to your Beeceptor endpoint with a query parameter and a custom User-Agent header. The -X GET explicitly sets the HTTP method to GET, though it's often the default for curl in simple cases.

Send a request using JavaScript (Fetch API)

For web development contexts, the Fetch API is commonly used:

1. Create an HTML file or use your browser's developer console.
2. Execute the following JavaScript code, replacing [YOUR_BEECEPTOR_SUBDOMAIN]:

   fetch('https://[YOUR_BEECEPTOR_SUBDOMAIN].proxy.beeceptor.com/js-test', {
     method: 'GET',
     headers: {
       'User-Agent': 'BeeceptorJSFetch'
     }
   })
   .then(response => response.text())
   .then(data => console.log(data))
   .catch(error => console.error('Error:', error));

   This sends a GET request to your endpoint and logs the response to the console.

Verify the request in Beeceptor

1. Return to your Beeceptor endpoint's dashboard in your web browser.
2. Observe the incoming requests: You should see the request you just sent appear in the 'Requests' list on the left side of the dashboard. Each entry represents an intercepted HTTP call.
3. Inspect the request details: Click on the newly arrived request. The main panel will update to show detailed information, including:
   • Request Headers: Verify the User-Agent header (e.g., BeeceptorFirstTest or BeeceptorJSFetch) and other standard headers.
   • Request Body: For POST/PUT requests, this would contain the payload.
   • Query Parameters: Confirm param1=value1 for the curl example.
   • Path: Verify /test-path or /js-test.

By successfully observing your request, you have confirmed that your Beeceptor endpoint is active and correctly intercepting traffic.

Common next steps

After successfully intercepting your first request, Beeceptor offers several functionalities to extend your testing and development workflows:

• Mocking Responses: Configure your Beeceptor endpoint to return specific, predefined responses for certain requests. This is useful for simulating API behavior, including success, error, or data validation scenarios, without needing a live backend. Navigating to the 'Rules' tab within your endpoint's dashboard allows you to define these mock responses based on request path, headers, or body content.
• Debugging and Inspection: Continue using Beeceptor to inspect all HTTP traffic. This is particularly valuable when integrating with third-party APIs or debugging webhook callbacks, as it provides a transparent view of all requests and responses. Tools like Chrome DevTools can also be used in conjunction with Beeceptor to inspect client-side network activity.
• Webhook Testing: Beeceptor is designed for testing webhooks. By providing your Beeceptor endpoint URL to a service that sends webhooks (e.g., Stripe, Twilio), you can capture and inspect the incoming webhook payloads, ensuring they are correctly formatted and delivered. Read more about Stripe's webhook integration guide for an example.
• Request Modification: Beyond simple inspection, Beeceptor allows you to modify requests and responses on the fly. You can add, remove, or change headers, alter response bodies, or introduce delays to simulate network latency directly from the web interface.
• Team Collaboration: For multi-developer projects, Beeceptor's paid plans offer features for team collaboration, allowing multiple users to share and manage endpoints. This ensures consistent testing environments across a development team. Refer to the Beeceptor pricing page for details on team features.

Troubleshooting the first call

If your first request does not appear in Beeceptor, consider the following common issues and troubleshooting steps:

• Incorrect Endpoint URL: Double-check that the URL used in your curl command or application code exactly matches your Beeceptor endpoint URL. Pay close attention to the subdomain and ensure there are no typos.
• Network Connectivity: Verify that your machine has an active internet connection and can reach external domains. A simple test is to ping google.com from your terminal.
• Firewall or Proxy Restrictions: Corporate networks or local firewalls might block outgoing HTTP requests to new or unknown domains. If you are on a restricted network, consult your IT department or try making the request from a less restrictive environment.
• HTTP vs. HTTPS: Ensure you are using the correct protocol (HTTPS) in your Beeceptor endpoint URL. Beeceptor endpoints primarily operate over HTTPS.
• DNS Resolution Issues: While less common, issues with DNS resolution can prevent your system from finding the Beeceptor server. You can try flushing your DNS cache or using a public DNS server like Google DNS (8.8.8.8).
• Beeceptor Endpoint Status: Log back into your Beeceptor account and confirm that your endpoint is active in your dashboard. If an endpoint is deleted or expired (for free tier, endpoints have a specific history retention and request limit), it won't receive requests.
• Client-Side Errors: If using a programming language or browser's Fetch API, check your application's console for any JavaScript errors or network-related exceptions that might prevent the request from being sent.
• Request Method: While Beeceptor supports all HTTP methods, ensure the method you are sending (e.g., GET, POST) is what you expect and that your client is correctly specifying it.

If issues persist, consult the official Beeceptor documentation for more in-depth troubleshooting guides or contact their support.