Skip to main content
Version: 2.0.0

Beeceptor API

This documentation describes the Beeceptor Mock Server Management APIs. It is used to programmatically configure, inspect, and operate Beeceptor mock servers.

What is Beeceptor?​

Beeceptor is a developer-focused API simulation platform. It is a behavioral API simulator designed for mocking, service virtualization, contract testing, and controlled failure simulation.

Beeceptor provides:

  • HTTP, Rest, SOAP, gRPC and GraphQL API mocking
  • Stateful API prototyping (CRUD, counters, lists)
  • Failure, latency, and chaos testing
  • Proxying and controlled callouts to real upstream services

Beeceptor operates by matching incoming requests against declarative rules and emitting predefined or dynamically generated responses. It guarantees:

  • Deterministic rule evaluation order
  • Isolation between endpoints
  • Explicit behavior only, no hidden defaults

Beeceptor is not an API gateway, backend framework, or production runtime. It does not attempt to infer business rules or validate domain correctness unless explicitly configured.

Entities​

Endpoint​

An Endpoint is an isolated mock server identified by a unique subdomain.

  • Owns its own configuration, rules, and state
  • Receives all incoming HTTP or traffic for that subdomain
  • Acts as the root execution boundary

All requests are evaluated strictly within the context of the endpoint they arrive on.

Mock Rule​

A Mock Rule is an ordered, declarative instruction that defines:

  • How to match an incoming request
  • What response to emit when matched
  • Optional delays, randomness, or state conditions

These rules are evaluated top-to-bottom. The first matching rule is selected and executed. Once matched, no further rules are evaluated after a match. A rule has one or more conditions under which a rule applies This matching can evalute:

  • HTTP method
  • URL path or regex
  • Headers
  • Request body content
  • Stateful conditions (counters, lists, datastore values)

All the conditions must evaluate to true for a rule to match or win for the response generation.

Response Generation​

A response definition specifies what Beeceptor returns when a rule is matched.

A response may include:

  • HTTP status code
  • Headers
  • Static payloads
  • Templated payloads
  • Weighted random responses

The responses are emitted exactly as defined in the mock rule. Beeceptor does not modify payloads beyond explicit templating instructions.

Template Engine​

The template engine serves as an optional response processor, enabling the creation of dynamic and context-aware payloads.

When this feature is enabled, responses can:

  • Reference data from the incoming request, such as headers, query parameters, and the body.
  • Generate synthetic or randomized values using built-in functions.
  • Apply conditional logic and iterative loops for complex response structures.
  • Integrate with stateful storage to maintain persistence across calls.

These templates are evaluated dynamically at the time of the request, following the identification of a matching rule.

Stateful Storage​

Beeceptor provides a suite of lightweight, endpoint-scoped state primitives designed to facilitate dynamic response behavior and simulate stateful API interactions.

The following storage types are supported:

  • CRUD Datastore: A flexible storage mechanism for JSON objects, supporting standard create, read, update, and delete operations.
  • Counters: Numeric primitives suitable for maintaining sequence-based or incremental state.
  • Lists: Ordered collections that allow for both append operations and structured querying.
  • Key-Value Store: A fundamental storage type for persisting simple data pairs.

All state is strictly isolated to its respective endpoint context. The data is managed as transient simulation state and is not intended for high-durability or long-term storage.

HTTP Callout​

Beeceptor can be configured as a programmable intermediary to forward incoming traffic to specified upstream services.

These rules support several advanced integration patterns:

  • Synchronous Forwarding: Inbound requests are transmitted to the target service, and the resulting response is relayed back to the client.
  • Payload Transformation: The system can dynamically modify both request and response data while in transit.
  • Latency Simulation: Artificial delays can be introduced to model various network conditions or service dependencies.
  • Asynchronous Callouts: Operations can be executed in a fire-and-forget mode, which is ideal for triggering background webhooks without delaying the client response.

Primary Use Cases​

Automated Testing and CI/CD Integration

  • Configure and update mock behaviors dynamically through the Beeceptor Management API.
  • Substitute external dependencies with consistent mock endpoints during automated test suites.
  • Enable deterministic environment setup and teardown for reliable continuous integration.

Accelerating Frontend Development

  • Implement mock rules to simulate specific edge cases and error scenarios.
  • Proceed with user interface development independently of backend progress.
  • Utilize OpenAPI, GraphQL, gRPC, WSDL specifications and predefined examples to generate functional response payloads.

Performance and Resilience Evaluation

  • Introduce artificial network latency and weighted response distribution to test system limits.
  • Reproduce timeouts, server-side errors, and intermittent service unavailability.
  • Validate application stability and retry logic without impacting live infrastructure.

Rapid Stateful Prototyping

  • Design complex, state-dependent API workflows using built-in CRUD and storage primitives.
  • Iterate on application logic and data flows without the overhead of database management.
  • Programmatically manage and reset simulation state to maintain test consistency.

Authentication​

Security Scheme Type:

apiKey

Header parameter name:

Authorization