openapi: 3.1.0 info: title: Beeceptor API description: | This documentation describes the **Beeceptor Mock Server Management APIs**. It is used to programmatically configure, inspect, and operate Beeceptor mock servers. **You can find the OpenAPI specification here:** [Beeceptor Management APIs (OpenAPI Spec)](https://beeceptor.com/docs/openapi/beeceptor-openapi-v2.yaml) ## 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. version: 2.0.0 x-release-status: testing x-internal: true servers: - url: https://api.beeceptor.com/api description: Production API Server components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization parameters: EndpointName: name: endpoint description: The name of Beeceptor endpoint. E.g., you should pick `my-endpoint` from your mock server base URL `https://my-endpoint.proxy.beeceptor.com`) in: path required: true schema: type: string default: "{{endpoint}}" example: "order-service" schemas: # ========================================================================== # V2 SCHEMAS # ========================================================================== Rule: type: object description: | A Rule defines the behavior for an incoming request. It consists of a set of conditions and a resulting action. Beeceptor matches requests against rules in the order they are defined. required: - enabled - conditions - action properties: enabled: type: boolean description: Toggle rule on/off. Disabled rules are ignored during matching. example: true method: type: string enum: [GET, POST, PUT, PATCH, DELETE, OPTIONS, TRACE, '*'] description: | The HTTP method to match. Use '*' to match any method. Note: For CRUD and gRPC rules, this is typically set to '*'. example: POST description: type: string description: Optional human-readable description for managing rules. example: My simple mock rule conditions: type: array minItems: 1 maxItems: 5 items: $ref: '#/components/schemas/Condition' description: | An array of conditions that must all match (AND logic) for the rule to trigger. Rules are evaluated in order; the first fully matched rule executes. action: description: The action to perform (e.g., Mock, Proxy, CRUD) when conditions match. allOf: - $ref: '#/components/schemas/Action' RuleWithId: description: | A Rule object that includes a unique identifier, typically returned in responses. allOf: - $ref: '#/components/schemas/Rule' - type: object required: - id properties: id: type: string description: The unique identifier for the rule. Condition: oneOf: - $ref: '#/components/schemas/PathCondition' - $ref: '#/components/schemas/HeaderCondition' - $ref: '#/components/schemas/BodyCondition' - $ref: '#/components/schemas/BodyParamCondition' - $ref: '#/components/schemas/StateCondition' - $ref: '#/components/schemas/GraphQLCondition' - $ref: '#/components/schemas/SoapActionCondition' - $ref: '#/components/schemas/GrpcMethodCondition' discriminator: propertyName: type mapping: path: '#/components/schemas/PathCondition' header: '#/components/schemas/HeaderCondition' body: '#/components/schemas/BodyCondition' body_param: '#/components/schemas/BodyParamCondition' state: '#/components/schemas/StateCondition' graphql: '#/components/schemas/GraphQLCondition' soap_action: '#/components/schemas/SoapActionCondition' grpc_method: '#/components/schemas/GrpcMethodCondition' BaseCondition: type: object required: - type properties: type: type: string PathCondition: allOf: - $ref: '#/components/schemas/BaseCondition' - type: object properties: type: type: string enum: [path] example: path operator: type: string enum: [equals, starts_with, contains, regex, template] description: | Matching operator. 'template' allows Express.js-style path syntax (e.g., /users/:id) to capture variables. example: equals value: type: string description: The path string or pattern to match against. example: /api/login required: [operator, value] HeaderCondition: description: Inspects the value of a specific HTTP header in the incoming request. allOf: - $ref: '#/components/schemas/BaseCondition' - type: object properties: type: type: string enum: [header] example: header key: type: string description: The name of the HTTP header (e.g., 'User-Agent', 'X-Custom-Header'). example: Content-Type operator: type: string enum: [equals, contains, regex] description: Matching operator for the header value. example: equals value: type: string description: The expected string, substring, or regular expression pattern. example: application/json required: [key, operator, value] BodyCondition: description: Performs a search or pattern match against the raw HTTP request body. allOf: - $ref: '#/components/schemas/BaseCondition' - type: object properties: type: type: string enum: [body] example: body operator: type: string enum: [contains, regex] description: Matching operator for the raw body content. example: contains value: type: string description: The text or regex pattern to look for in the body. example: username required: [operator, value] BodyParamCondition: description: | Matches against parsed body parameters. This is applicable for JSON payloads, XML, or Form-Data where Beeceptor can extract named fields. allOf: - $ref: '#/components/schemas/BaseCondition' - type: object properties: type: type: string enum: [body_param] example: body_param key: type: string description: The key or path to the field in the request body (e.g., 'user.id'). example: user.email operator: type: string enum: [equals, not_equals, contains, not_contains, is_null, is_not_null] example: equals value: type: string description: The value to compare against. Not required for 'is_null' or 'is_not_null'. example: test@example.com required: [key, operator, value] StateCondition: description: | Matches against persistent state variables (Counters, Data Stores, or Lists) stored in your endpoint. This allows for stateful mock transitions. allOf: - $ref: '#/components/schemas/BaseCondition' - type: object properties: type: type: string enum: [state] example: state key: type: string description: The name of the state variable. example: login_attempts stateType: type: string enum: [string, counter, list] description: | 'string': General key-value store. 'counter': Numeric value supporting math operations. 'list': Collection of values supporting LIFO/FIFO operations. example: counter operator: type: string enum: [equals, not_equals, contains, not_contains, greater_than, less_than, greater_than_equal, less_than_equal] example: greater_than value: type: string description: The value to compare the current state against. example: "3" required: [key, stateType, operator, value] GraphQLCondition: description: | Matches against incoming GraphQL queries. Beeceptor parses the GraphQL operation name or query structure to determine a match. allOf: - $ref: '#/components/schemas/BaseCondition' - type: object properties: type: type: string enum: [graphql] example: graphql operator: type: string enum: [equals, contains, regex] example: equals value: type: string description: The GraphQL operation name or query snippet to match. example: GetUserEmail required: [operator, value] SoapActionCondition: description: Targets SOAP-based web services by matching against the 'SOAPAction' header. allOf: - $ref: '#/components/schemas/BaseCondition' - type: object properties: type: type: string enum: [soap_action] example: soap_action operator: type: string enum: [equals] example: equals value: type: string description: The exact SOAPAction URI or string to match. example: http://www.example.org/GetUser required: [operator, value] GrpcMethodCondition: description: | Primary condition for gRPC rules. Matches the full gRPC method path (e.g., 'package.Service/MethodName'). allOf: - $ref: '#/components/schemas/BaseCondition' - type: object properties: type: type: string enum: [grpc_method] example: grpc_method value: type: string description: The fully qualified gRPC method name. example: user.UserService/GetUser required: [value] Action: oneOf: - $ref: '#/components/schemas/MockAction' - $ref: '#/components/schemas/WeightedAction' - $ref: '#/components/schemas/CalloutAction' - $ref: '#/components/schemas/CrudAction' - $ref: '#/components/schemas/GrpcAction' discriminator: propertyName: type mapping: mock: '#/components/schemas/MockAction' weighted: '#/components/schemas/WeightedAction' callout: '#/components/schemas/CalloutAction' crud: '#/components/schemas/CrudAction' grpc: '#/components/schemas/GrpcAction' MockAction: type: object description: Returns a predefined HTTP response to the caller. properties: type: type: string enum: [mock] example: mock delay: type: number description: Response delay in milliseconds (0-600,000). minimum: 0 maximum: 600000 example: 200 status: type: number description: HTTP status code to return. minimum: 100 maximum: 599 example: 200 headers: type: array description: Custom HTTP headers to include in the response. items: type: object properties: key: type: string example: Content-Type value: type: string example: application/json templated: type: boolean description: Enable template engine for this header value. example: false templated: type: boolean description: | If enabled, Beeceptor processes the body using its powerful template engine, allowing for dynamic response generation and data injection. example: true oneOf: - title: BodyResponse required: - body properties: body: type: string description: | The response body. Can include Handlebars templates if 'templated' is true. Use this to generate dynamic data like '{{faker "person.firstName"}}'. example: '{"status": "success", "user": "{{faker \"person.firstName\"}}"}' - title: BlobPathResponse required: - blobPath properties: blobPath: type: string description: | Reference to a file stored in Beeceptor's storage. Use the `POST /v2/endpoints/{endpoint}/blobs` API to upload files and retrieve this path. example: res-body-20260121042538-e53mertosm.json required: [type, status, headers] WeightedAction: type: object description: | Distributes incoming requests across multiple responses based on assigned weights. The combined weights of all responses must equal exactly 100. properties: type: type: string enum: [weighted] example: weighted responses: type: array description: A list of potential responses and their probability weights. items: $ref: '#/components/schemas/WeightedResponse' required: [type, responses] WeightedResponse: type: object properties: name: type: string description: A label for identifying this response in logs. example: Success Response weight: type: number description: Percentage probability (0-100). Total must sum to 100 per action. example: 80 delay: type: number example: 0 status: type: number minimum: 100 maximum: 599 example: 200 headers: type: array items: type: object properties: key: type: string example: Content-Type value: type: string example: application/json templated: type: boolean example: false body: type: string example: '{"status": "ok"}' templated: type: boolean example: false required: [name, weight, status, headers, body] CalloutAction: type: object description: | Triggers an external HTTP request (Callout) when the rule matches. This is useful for proxying traffic, transforming payloads, or notifying webhooks. properties: type: type: string enum: [callout] example: callout behavior: type: string enum: [sync, async] description: | 'sync': The original request waits for the target service's response (Proxy behavior). 'async': Beeceptor sends an immediate response to the client and triggers the callout as a background process (Webhook behavior). example: sync callout: type: object description: Detailed configuration for the outgoing request. properties: url: type: string description: The destination URL (Target) for the callout. example: https://echo.beeceptor.com method: type: string enum: [GET, POST, PUT, PATCH, DELETE, OPTIONS, TRACE, '*'] example: POST transform: type: string enum: [forward, custom] description: | 'forward': Pass the target's response back to the client as-is. 'custom': Return a pre-defined mock response to the client instead of the target's response. example: forward headers: type: array items: type: object properties: key: type: string example: X-Forwarded-For value: type: string example: beeceptor templated: type: boolean example: false body: type: string example: '{"action": "proxy"}' templated: type: boolean example: false connectionId: type: string description: | Reference ID of an API Connection (configured in Beeceptor) to handle OAuth 2.0 or other authentication methods automatically. example: conn_12345 delay: type: object properties: min: type: number example: 100 max: type: number example: 500 # Flattened Response Fields (for async behavior) status: type: number description: HTTP status for the immediate mock response (async behavior only). minimum: 100 maximum: 599 example: 202 headers: type: array description: HTTP headers for the immediate mock response (async behavior only). items: type: object properties: key: type: string example: Content-Type value: type: string example: application/json templated: type: boolean example: false body: type: string description: HTTP body for the immediate mock response (async behavior only). example: '{"status": "accepted"}' templated: type: boolean example: false required: [type, behavior, callout] CrudAction: type: object description: | Enables stateful CRUD behavior for a resource path. Beeceptor will automatically handle POST (Create), GET (Read), PUT (Update), and DELETE operations for JSON objects. properties: type: type: string enum: [crud] example: crud idField: type: string description: The field name in the JSON object used as a unique identifier (e.g., 'id' or 'uuid'). example: id required: [type, idField] GrpcAction: type: object description: Defines the mock behavior for gRPC calls, supporting unary and streaming communication. properties: type: type: string enum: [grpc] example: grpc callType: type: string enum: [unary, server_streaming, client_streaming, bidirectional_streaming] description: gRPC communication pattern. example: unary status: type: number minimum: 0 description: Standard gRPC status code (0 for OK, 1-16 for errors). example: 0 statusMessage: type: string description: Human-readable status message for gRPC errors, only applicable for non-zero status codes. example: something went wrong delay: type: number minimum: 0 maximum: 600000 description: Delay before sending the first response in milliseconds. example: 0 responses: type: array minItems: 1 maxItems: 4 description: | A list of responses to send back. For streaming calls, these are sent sequentially. If 'singleResponseRepeated' is true, only the first response is used for all streams. items: $ref: '#/components/schemas/GrpcResponse' streamCount: type: object description: | For server_streaming or bidirectional patterns, controls how many times the server will push messages before finishing. properties: min: type: number minimum: 1 description: Minimum number of stream messages to send. example: 1 max: type: number minimum: 1 description: Maximum number of stream messages to send. example: 5 singleResponseRepeated: type: boolean description: | If true, the server repeats the first response item for the entire duration of the stream. If false, you must provide a list of unique responses. example: true required: [type, callType, responses] GrpcResponse: type: object properties: body: type: string example: '{"message": "Hello from Beeceptor"}' metadata: type: string example: '{"some-key": "some-value"}' EndpointSettings: type: object description: Configuration settings for the mock endpoint, including security, CORS, and rate limits. properties: security: type: object description: | Secure your endpoint using mandatory header-based authentication. Requests missing the secret header will be rejected without affecting your quota. properties: enabled: type: boolean example: false headerKey: type: string description: The name of the header (e.g., 'Authorization' or 'x-api-key'). example: Authorization headerValue: type: string description: The secret value required for access. example: Bearer secret-token cors: type: object description: Configure Cross-Origin Resource Sharing (CORS) whitelists. properties: origins: type: array items: type: string example: "test.example.com" locale: type: string enum: [en, en_GB, en_IN, en_US, fr, id_ID, ja, pt_BR, es, es_MX, zh_CN] description: The locale used by the template engine for generating random (faker) data. example: en rateLimit: type: object description: Restrict the volume of incoming traffic to prevent abuse or simulate throttling. properties: enabled: type: boolean example: true rate: type: integer example: 10 period: type: string enum: [Second, Minute, Hour] example: Second crud: type: object description: Settings for stateful CRUD routes. properties: autoDelete: type: boolean description: | When enabled, Beeceptor automatically purges older records when the storage limit is reached to accommodate new data. example: true customDomain: type: object properties: enabled: type: boolean example: false domain: type: string example: api.example.com mtls: type: object description: Mutual TLS settings for certificate-based client authentication. properties: enabled: type: boolean example: false # Cert management removed from V2 scope localTunnel: type: boolean description: | If enabled, this endpoint routes all traffic to your localhost via the Beeceptor CLI. Documentation: https://beeceptor.com/docs/local-tunneling-by-exposing-service-port/ example: false proxy: type: object properties: targetUrl: type: string description: Global destination for forwarding requests that don't match any rules. example: https://echo.beeceptor.com ignoreSSLErrors: type: boolean example: true rules: type: object properties: enabled: type: boolean description: Master toggle for the mock rules engine. example: true Error: type: object description: Standard error response structure. properties: error: type: object properties: code: type: string enum: [validation_error, not_found, unauthorized_api_key, missing_authentication, internal_error] example: validation_error message: type: string example: Request validation failed details: type: array items: type: object properties: path: type: string example: /rules[0]/action/status message: type: string example: must be greater than or equal to 100 received: type: string example: "50" Job: type: object description: Represents an asynchronous background task, such as processing a large API specification file. properties: jobId: type: string description: Unique identifier for tracking the job status. example: job_9876543210 type: type: string enum: [oas, wsdl, grpc, graphql] description: The type of specification being processed. example: oas status: type: string enum: [QUEUED, PROCESSING, COMPLETED, FAILED] description: Current lifecycle state of the job. example: PROCESSING message: type: string description: Detail or error message related to the job's progress. example: Validating OpenAPI specification file. progress: type: integer minimum: 0 maximum: 100 description: Progress completion percentage. example: 45 currentStage: type: string description: The current processing stage (e.g., 'Validating', 'Mapping', 'Generating Rules'). example: Mapping result: type: object description: The result data of the job, available upon completion. completedAt: type: string format: date-time description: Timestamp when the job was completed. example: "2026-01-28T10:00:00Z" failedAt: type: string format: date-time description: Timestamp when the job failed. Certificate: type: object description: Details of an mTLS client certificate managed within Beeceptor. properties: id: type: string description: internal certificate identifier. example: cert_abc123 name: type: string description: User-defined label for the certificate. example: My Client Cert cert: type: string description: Public certificate in PEM format. example: "-----BEGIN CERTIFICATE-----\nMIIDDTCCAfWgAwIBAgIJAJ...\n-----END CERTIFICATE-----" key: type: string description: Private key in PEM format (Redacted in list views). example: "-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0B...\n-----END PRIVATE KEY-----" expiry: type: string format: date-time description: Certificate expiration timestamp. example: "2027-01-28T10:00:00Z" createdAt: type: string format: date-time example: "2026-01-28T10:00:00Z" Pagination: type: object description: Standard pagination metadata for list responses. properties: total: type: number description: Total number of items available across all pages. example: 150 limit: type: number description: Maximum number of items requested per page. example: 20 offset: type: number description: Number of items skipped from the beginning. example: 0 hasMore: type: boolean description: Indicates if another page of data is available. example: true PaginationNew: type: object description: Cursor-based pagination metadata for history and state items. properties: cursor: type: string description: The cursor for the next set of results. example: "bmV4dF9jdXJzb3JfMTIz" hasMore: type: boolean description: Indicates if more records are available. example: true limit: type: integer description: The page size limit used. example: 50 RequestLog: oneOf: - $ref: '#/components/schemas/RequestLogCompact' - $ref: '#/components/schemas/RequestLogVerbose' description: | An audit log of an incoming request received by the mock server. The response format depends on the `mode` query parameter: - **Default (compact mode)**: Returns basic request information (id, date, method, path, status, timeTaken, rule, behavior) - **Verbose mode** (when `mode=verbose` or fetching a specific request): Includes full request and response details with headers and body content. RequestLogCompact: type: object description: Compact request log with basic information only. required: - id - date - method - path - status - timeTaken - rule - behavior properties: id: type: string description: Unique request identifier. date: type: string format: date-time description: Timestamp when the request was received. method: type: string description: HTTP method used (e.g., GET, POST, PUT, DELETE, PATCH, OPTIONS). path: type: string description: Full request path including query parameters. status: type: integer description: HTTP response status code returned by Beeceptor. timeTaken: type: integer description: Processing time in milliseconds. rule: type: object description: Rule matching information. properties: matched: type: boolean description: True if the request matched a user-defined mock rule. ruleId: type: string description: The identifier of the matching rule. Present only when matched is true. behavior: type: string enum: [mock-rule, proxy, crud, grpc] description: The behavior mode used to handle this request. RequestLogVerbose: allOf: - $ref: '#/components/schemas/RequestLogCompact' - type: object description: Verbose request log with full request and response details. required: - request - response properties: request: type: object description: Full incoming request details. properties: body: type: string nullable: true description: Request body content, or null if no body was sent. headers: type: object additionalProperties: type: string description: HTTP headers sent in the request. httpVersion: type: string description: HTTP version used (e.g., "HTTP/1.1", "HTTP/2"). redacted: type: boolean description: True if sensitive fields were redacted from the request. response: type: object description: Full response details sent back to the client. properties: body: type: string description: Response body content. headers: type: object additionalProperties: type: string description: HTTP headers sent in the response. httpVersion: type: string description: HTTP version used (e.g., "HTTP/1.1", "HTTP/2"). redacted: type: boolean description: True if sensitive fields were redacted from the response. StateItem: type: object description: A single entry in the endpoint's persistent state store. properties: type: type: string enum: [string, counter, list] example: list key: type: string description: The name/identifier of the state variable. example: cart_items value: oneOf: - type: string - type: array - type: integer minimum: 0 description: The current value. For lists, this is an array; for strings, this is a string; for counters, this is a non-negative integer. example: ["item_1", "item_2"] lastModified: type: number description: Timestamp of the last time the state item was accessed. example: 1738054800000 responses: BadRequest: description: Bad Request - Payload validation failed. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthenticated - API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Unauthorized - You don't have access to this endpoint. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Not Found - The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: Internal Server Error - An unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/Error' paths: # ========================================================================== # V2 ENDPOINTS # ========================================================================== /v2/endpoints/{endpoint}/rules: get: summary: Get all rules description: | Retrieves all mock rules configured for the specified endpoint. Rules define how Beeceptor processes incoming HTTP requests and generates responses. **How Rules Work:** - Rules are evaluated in a **top-to-bottom order** (first match wins) - Each rule contains **conditions** (request matching criteria) and an **action** (response behavior) - When a request arrives, Beeceptor evaluates rules sequentially until the first matching rule is found - Once matched, the rule's action is executed and no further rules are evaluated - If no rules match, Beeceptor falls back to: Local Tunnel → HTTP Proxy → OpenAPI Spec → Default 200 OK response **Response Format:** - Returns all rules (entire rule set) - Rules are returned in their execution order (top-to-bottom priority) tags: [Mock Rules] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' responses: '200': description: List of rules content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/RuleWithId' example: data: - id: 1ua4j6kb1e2 enabled: true method: GET description: "my simple rule" conditions: - type: path operator: equals value: /simple-rule action: type: mock delay: 0 status: 200 headers: - key: Content-Type value: "application/json;charset=utf-8" body: "{\n \"status\": \"Awesome!\"\n}" templated: false - id: v1ljtxmtiz enabled: true method: GET description: "my weighted rule" conditions: - type: path operator: equals value: /weighted-rule action: type: weighted responses: - name: Response 1 weight: 50 delay: 0 status: 200 headers: - key: Content-Type value: "application/json;charset=utf-8" body: "{\n \"status\": \"Sucess Response!\"\n}" templated: false - name: Response 2 weight: 50 delay: 0 status: 200 headers: - key: Content-Type value: "application/json;charset=utf-8" body: "{\n \"status\": \"Failed response!\"\n}" templated: false '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' post: summary: Create a new rule description: | Creates a new mock rule and appends it to the **end of the rule list** (lowest priority). The rule will be evaluated last in the execution order. **Purpose:** A mock rule encapsulates conditions (request matching criteria) and actions (response behavior). Rules are the core building blocks that define how your mock server responds to incoming requests. **How It Works:** 1. **Rule Structure**: Each rule consists of: - `enabled`: Boolean flag to activate/deactivate the rule - `method`: HTTP method to match (GET, POST, PUT, DELETE, etc., or '*' for any) - `conditions`: Array of 1-5 matching criteria (ALL must match for the rule to trigger) - `action`: The behavior to execute when conditions match (mock response, proxy, CRUD, etc.) - `description`: Optional human-readable label for rule management 2. **Condition Matching (AND Logic)**: - All conditions in a rule must match for the rule to qualify - Supported condition types: equals, starts_with, contains, regex, template, header, body, body_param, state, graphql, soap_action - Conditions can match against request data or state store variables - Path conditions support regex with named groups for extracting path parameters 3. **Rule Execution Order**: - Rules are evaluated **top-to-bottom** (first match wins) - New rules created via this API are inserted at the **bottom** (lowest priority) - To change priority, use the reorder endpoint or drag-and-drop in the UI - Once a rule matches, its action executes and no further rules are evaluated 4. **Action Types**: - `mock`: Return a predefined HTTP response (static or templated) - `weighted`: Randomly select from multiple responses based on probability weights - `callout`: Forward request to external API (sync proxy or async webhook) - `crud`: Enable automatic CRUD operations for a resource - `grpc`: Mock gRPC responses (unary or streaming) **Limitations:** - Maximum 5 conditions per rule - For OR logic, create multiple rules with different conditions - Rule IDs are auto-generated and cannot be specified - Rules cannot be inserted at a specific position (always appended to the end) **Best Practices:** - Place specific/narrow rules at the top (higher priority) - Place broad/catch-all rules at the bottom (lower priority) - Use descriptive names in the `description` field for easier management - Test rule matching using the dashboard's request history API - Use state conditions for stateful mock scenarios (e.g., login flows) **Response:** Returns the created rule with its auto-generated `id` field. tags: [Mock Rules] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Rule' responses: '201': description: Rule created content: application/json: schema: $ref: '#/components/schemas/RuleWithId' example: id: vshn31wteh enabled: true method: GET description: "my simple rule" conditions: - type: path operator: equals value: /simple-rule action: type: mock delay: 0 status: 200 headers: - key: Content-Type value: "application/json;charset=utf-8" body: "{\n \"status\": \"Awesome!\"\n}" templated: false '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' put: summary: Bulk replace all rules description: | Atomically replaces **all existing rules** with a new set of rules. This is a destructive operation that completely overwrites the current rule configuration. **Purpose:** - Sync rules from version control or external systems - Restore rules from backup - Deploy rule configurations across multiple environments - Perform bulk rule updates without individual API calls **How It Works:** 1. **Atomic Replacement**: All existing rules are deleted and replaced in a single transaction 2. **Rule Order Preservation**: Rules are stored and executed in the order provided in the array 3. **Validation**: All rules are validated before replacement (if any rule is invalid, the entire operation fails) **Validation Rules:** - Each rule must have valid `enabled`, `conditions`, and `action` fields - Conditions array must contain 1-5 items - All condition types must be valid (path, header, body, etc.) - Action type must be one of: mock, weighted, callout, crud, grpc - For weighted actions, response weights must sum to exactly 100 **Limitations:** - Maximum rules per endpoint: 500 - Request body size limit: 1MB **Use Cases:** - **CI/CD Integration**: Deploy rules as part of automated pipelines - **Environment Sync**: Copy production rules to staging/dev environments - **Backup/Restore**: Periodically backup rules and restore when needed - **Bulk Updates**: Modify multiple rules offline and push all changes at once **Response:** Returns the count of replaced rules on success. tags: [Mock Rules] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' requestBody: required: true content: application/json: schema: type: object properties: rules: type: array items: $ref: '#/components/schemas/Rule' responses: '200': description: Rules replaced content: application/json: schema: type: object properties: replaced: type: integer example: replaced: 2 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' delete: summary: Delete all rules description: | Permanently deletes **all mock rules** configured for the endpoint. This is a destructive operation that cannot be undone. **Purpose:** - Reset endpoint to default state (no custom rules) - Clean up before importing new rule configurations - Remove all mocking behavior and rely on fallback mechanisms **Post-Deletion Behavior:** After all rules are deleted, incoming requests will follow the fallback chain: 1. **Local Tunnel**: If enabled, requests are forwarded to localhost 2. **HTTP Proxy**: If configured, requests are proxied to the target URL 3. **OpenAPI Spec**: If uploaded, responses are generated from the spec 4. **Default Response**: Returns `200 OK` with a default message **Limitations:** - This operation is irreversible. - Does not affect other endpoint settings (CORS, rate limits, etc.) **Best Practices:** - Export/backup rules before deletion (use GET /rules endpoint) - Consider disabling rules instead of deleting if you may need them later - Verify the endpoint name before executing this operation **Response:** Returns the count of deleted rules and a success flag. tags: [Mock Rules] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' responses: '200': description: Rules deleted content: application/json: schema: type: object properties: deleted: type: boolean count: type: integer example: deleted: true count: 5 '401': $ref: '#/components/responses/Unauthorized' /v2/endpoints/{endpoint}/rules/reorder: post: summary: Reorder rules description: | Reorders the existing mock rules by priority without modifying the rule content. **How It Works:** - Provide an ordered list of rule IDs in `order` - Rules listed in `order` are moved to the top in the exact sequence provided - Any rules not listed keep their relative order and are appended after the reordered block **Validation:** - All rule IDs in `order` must exist for the endpoint **Use Cases:** - Promote a rule to higher priority - Restore a known execution order after experiments **Response:** Returns the count of rules that were reordered. tags: [Mock Rules] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' requestBody: required: true content: application/json: schema: type: object required: - order properties: order: type: array description: Ordered list of rule IDs to move to the top. items: type: string example: order: - vshn31wteh - 1ua4j6kb1e2 responses: '200': description: Rules reordered content: application/json: schema: type: object properties: data: type: object properties: reordered: type: integer example: data: reordered: 2 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' /v2/endpoints/{endpoint}/rules/{ruleId}: get: summary: Get a single rule description: | Retrieves the complete configuration of a specific mock rule by its unique identifier. **Purpose:** - Inspect rule details programmatically - Verify rule configuration after creation/update - Debug rule matching behavior **Response Format:** Returns the complete rule object with: - `id`: Unique identifier - `enabled`: Active status - `method`: HTTP method filter - `description`: Human-readable label - `conditions`: Array of matching criteria - `action`: Response behavior configuration **Use Cases:** - Retrieve rule details before updating - Verify rule configuration in automated tests tags: [Mock Rules] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' - in: path name: ruleId required: true schema: type: string description: The unique identifier of the rule (auto-generated during creation). example: vshn31wteh responses: '200': description: Rule details content: application/json: schema: $ref: '#/components/schemas/RuleWithId' example: id: vshn31wteh enabled: true method: GET description: "my simple rule" conditions: - type: path operator: equals value: /simple-rule action: type: mock delay: 0 status: 200 headers: - key: Content-Type value: "application/json;charset=utf-8" body: "{\n \"status\": \"Awesome!\"\n}" templated: false '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' put: summary: Update a rule (full replacement) description: | Performs a **complete replacement** of an existing mock rule. All fields must be provided in the request body, as this is not a partial update. **How It Works:** 1. **Full Replacement**: The entire rule object is replaced with the new configuration 2. **ID Preservation**: The rule ID remains unchanged (specified in the URL path) 3. **Position Preservation**: The rule maintains its position in the execution order 4. **Validation**: The new rule configuration is validated before replacement **Limitations:** - Cannot move the rule to a different position (use reorder endpoint) - All validation rules apply (same as rule creation) - Partial updates not supported (use PATCH for partial updates) **Use Cases:** - Update response templates based on external data - Modify conditions to match new API contracts - Change action types (e.g., mock → callout) - Update weighted response probabilities **Response:** Returns the updated rule with all fields. tags: [Mock Rules] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' - in: path name: ruleId required: true schema: type: string description: The unique identifier of the rule to update. example: vshn31wteh requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Rule' responses: '200': description: Rule updated content: application/json: schema: $ref: '#/components/schemas/RuleWithId' example: id: vshn31wteh enabled: true method: GET description: "my simple rule" conditions: - type: path operator: equals value: /simple-rule action: type: mock delay: 0 status: 200 headers: - key: Content-Type value: "application/json;charset=utf-8" body: "{\n \"status\": \"Awesome!\"\n}" templated: false '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' patch: summary: Update a rule (partial) description: | Performs a **partial update** of an existing mock rule. Only the fields provided in the request body are modified; all other fields remain unchanged. **Purpose:** - Update specific rule fields without affecting others - Toggle rule enabled/disabled status - Modify individual conditions or actions - Update rule descriptions **How It Works:** 1. **Partial Update**: Only specified fields are updated 2. **Field Merging**: Provided fields overwrite existing values; omitted fields remain unchanged 3. **ID Preservation**: The rule ID cannot be changed 4. **Position Preservation**: The rule maintains its position in the execution order 5. **Validation**: Updated fields are validated before applying changes **Supported Partial Updates:** - `enabled`: Toggle rule on/off without changing conditions or actions - `description`: Update the human-readable label - `method`: Change the HTTP method filter - `conditions`: Replace the entire conditions array - `action`: Replace the entire action object **Important Notes:** - Complex fields like `conditions` and `action` are replaced entirely (not merged) - To update a single condition, you must provide the complete `conditions` array - To update action properties, you must provide the complete `action` object - Partial updates within nested objects are not supported **Common Use Cases:** **Example 1: Toggle Rule Status** ```json { "enabled": false } ``` Disables the rule without modifying conditions or actions. **Example 2: Update Description** ```json { "description": "Updated rule description" } ``` Changes only the rule's label. **Example 3: Change HTTP Method** ```json { "method": "POST" } ``` Updates the method filter while preserving conditions and actions. **Limitations:** - Cannot move the rule to a different position - Nested object merging not supported (entire objects must be replaced) - All validation rules apply to updated fields **Response:** Returns the complete updated rule with all fields (including unchanged ones). tags: [Mock Rules] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' - in: path name: ruleId required: true schema: type: string description: The unique identifier of the rule to update. example: vshn31wteh requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Rule' responses: '200': description: Rule updated content: application/json: schema: $ref: '#/components/schemas/RuleWithId' example: id: vshn31wteh enabled: true method: GET description: "my simple rule" conditions: - type: path operator: equals value: /simple-rule action: type: mock delay: 0 status: 200 headers: - key: Content-Type value: "application/json;charset=utf-8" body: "{\n \"status\": \"Awesome!\"\n}" templated: false '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' delete: summary: Delete a rule description: | Permanently deletes a specific mock rule by its unique identifier. This operation cannot be undone. **Purpose:** - Clean up unused mock configurations - Programmatically manage rule lifecycle **How It Works:** 1. **Rule Removal**: The rule is removed from the endpoint's rule array 2. **Order Adjustment**: Remaining rules maintain their relative order 3. **Priority Shift**: Rules below the deleted rule move up in priority 4. **Real-time Updates**: Connected dashboard clients are notified. **Limitations:** - Operation is irreversible. - Deleted rules cannot be recovered unless backed up externally - Does not affect other endpoint settings or rules **Best Practices:** - Backup the rule before deletion (use GET /rules/{ruleId}) - Consider disabling the rule first to test impact before permanent deletion - Verify the rule ID before executing this operation - Review remaining rules to ensure correct execution order after deletion **Use Cases:** - Remove temporary test rules after testing - Clean up rules after API contract changes - Delete duplicate or conflicting rules - Programmatic rule lifecycle management in CI/CD pipelines **Response:** Returns the deleted rule ID and a success flag. tags: [Mock Rules] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' - in: path name: ruleId required: true schema: type: string description: The unique identifier of the rule to delete. example: vshn31wteh responses: '200': description: Rule deleted content: application/json: schema: type: object properties: id: type: string deleted: type: boolean example: id: vshn31wteh deleted: true '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /v2/endpoints/{endpoint}/blobs: post: summary: Upload a blob file description: | Uploads a binary file (e.g., image, JSON, PDF) to Beeceptor's storage. Returns a `blobPath` which can be used in a `MockAction` to serve this file as a response. Blobs are automatically managed and deleted by the system. tags: [Mock Rules] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary description: The file to upload. responses: '201': description: Blob uploaded successfully. content: application/json: schema: type: object properties: blobPath: type: string description: The identifier for the uploaded blob (e.g., res-body-20260120062822-u70ynu7gyy.yml). example: blobPath: "res-body-20260121042538-e53mertosm.json" '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' description: Internal server error - failed to upload blob. /v2/endpoints/{endpoint}/requests: get: summary: Get request history description: | Retrieves a paginated, searchable list of HTTP requests received by the mock server. Each request log contains metadata about the incoming request, the generated response, and how Beeceptor processed it. ### Purpose The Request History API enables: - Debugging API integrations by inspecting request/response payloads - Auditing API traffic patterns and usage - Verifying webhook deliveries and payload contents - Analyzing which mock rules matched incoming requests ### How Request Logging Works When a request arrives at a Beeceptor endpoint, the following information is captured: 1. **Request Metadata**: HTTP method, path, timestamp, source IP 2. **Request Details**: Headers, body content, HTTP version 3. **Processing Information**: Which rule matched (if any), processing time, behavior type 4. **Response Details**: Status code, headers, body content 5. **Callout Information**: If the request was proxied, details of the upstream request/response ### Behavior Types Each logged request includes a `behavior` field indicating how it was processed: | Behavior | Description | |----------|-------------| | `mock-rule` | Matched a user-defined mock rule | | `proxy` | Forwarded to upstream proxy target | | `callout` | Triggered an HTTP callout (sync or async) | | `grpc` | Processed as a gRPC request | | `wsdl` | Matched a SOAP/WSDL operation | | `graphql` | Processed as a GraphQL request | | `tunnel` | Forwarded to local machine via tunnel | | `oas` | Generated response from OpenAPI specification | ### Response Modes **Compact Mode (Default)** Returns basic request information optimized for listing and overview: - `id`, `date`, `method`, `path`, `status`, `timeTaken` - `rule`: Whether a rule matched and which rule ID - `behavior`: How the request was processed **Verbose Mode (`mode=verbose`)** Returns complete request and response details for debugging: - All compact mode fields - `request`: Full request body, headers, HTTP version - `response`: Full response body, headers, HTTP version - `callout`: If proxied, includes target request/response details - `multipartData`: Metadata for file uploads (file content available via download endpoint) ### Pagination Uses cursor-based pagination for efficient traversal of large datasets: - Default page size: 20 requests - Maximum page size: 100 requests - Results are sorted by date descending (newest first) - Use the `cursor` from the response to fetch the next page - Continue until `pagination.hasMore` is `false` ### Filtering Capabilities Multiple filters can be combined to narrow down results: **Time-Based Filters:** - `dateFrom` / `dateTo`: ISO 8601 timestamps for absolute date range - `dateRange`: Relative duration (e.g., '1h', '24h', '7d') **Request Filters:** - `method`: HTTP method (GET, POST, PUT, DELETE, PATCH) - `path`: Path substring or regex pattern - `status`: Response status code (200-599) - `requestBody`: Search within request body and multipart field names - `responseBody`: Search within response body **Processing Filters:** - `behavior`: How the request was handled - `ruleMatched`: Whether a mock rule matched (true/false) - `isMultipart`: Requests with file uploads ### Multipart/Form-Data Handling For requests containing file uploads: - File metadata (field name, file name, content type, size) is included in verbose mode - Actual file content is stored separately and available via the download endpoint - Search by field name or file name using the `requestBody` filter ### Data Retention - Request history is retained for up to **10 days** - Older requests are automatically purged - Use the DELETE endpoint to manually clean up old requests ### Sensitive Data Handling If header masking is enabled in endpoint settings: - Sensitive headers (Authorization, API keys, etc.) are redacted - `redacted: true` flag indicates data was masked tags: [Request History] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' - in: query name: limit schema: type: integer default: 20 maximum: 100 description: Maximum number of request logs to return (default 20, max 100). - in: query name: cursor schema: type: string description: Cursor for pagination to fetch the next set of results. Use the cursor from the previous response. - in: query name: id schema: type: string description: Filter by specific request ID (alternative to using the {requestId} path parameter). - in: query name: method schema: type: string description: Filter by HTTP method (e.g., 'GET', 'POST', 'PUT', 'DELETE', 'PATCH'). - in: query name: status schema: type: integer description: Filter by HTTP response status code (e.g., 200, 404, 500). - in: query name: path schema: type: string description: Filter by request path substring or regex pattern. - in: query name: behavior schema: type: string enum: [mock-rule, proxy, callout, grpc, wsdl, graphql, tunnel, oas] description: Filter by request behavior mode (how the request was handled). - in: query name: ruleMatched schema: type: boolean description: Filter requests that matched (true) or missed (false) user-defined mock rules. - in: query name: isMultipart schema: type: boolean description: Filter requests that contain multipart/form-data content. - in: query name: hasAttachments schema: type: boolean description: Filter requests that have file attachments (alias for isMultipart). - in: query name: dateFrom schema: type: string format: date-time description: Filter requests received after this ISO 8601 timestamp (e.g., 2024-01-15T10:30:00Z). - in: query name: dateTo schema: type: string format: date-time description: Filter requests received before this ISO 8601 timestamp (e.g., 2024-01-15T23:59:59Z). - in: query name: dateRange schema: type: string description: Filter requests within a relative time range (e.g., '1h', '24h', '7d'). Cannot be used with both dateFrom and dateTo. - in: query name: requestBody schema: type: string description: Search for keywords or regex patterns within the request body and multipart field names. - in: query name: responseBody schema: type: string description: Search for keywords or regex patterns within the response body. - in: query name: mode schema: type: string enum: [verbose] description: Set to 'verbose' to include full request and response details (headers, body, httpVersion, redaction status). Without this parameter, only basic request information is returned. responses: '200': description: | Request history retrieved successfully. Response format: - Without `requestId` path parameter: Returns paginated array with cursor-based pagination - With `requestId` path parameter: Returns single RequestLog object directly content: application/json: schema: oneOf: - type: object properties: data: type: array items: $ref: '#/components/schemas/RequestLog' pagination: $ref: '#/components/schemas/PaginationNew' description: Paginated response for request history list - $ref: '#/components/schemas/RequestLog' description: Single request details when fetched by requestId '400': description: Bad Request - Invalid query parameters or filter values content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '404': description: Not Found - Returned when fetching by requestId and request not found content: application/json: schema: $ref: '#/components/schemas/Error' delete: summary: Delete request history description: | Deletes request history entries with optional filtering. Supports the same filtering parameters as GET, enabling selective bulk deletion of requests matching specific criteria. ### Purpose Use this endpoint to: - Bulk delete old or irrelevant request logs - Remove requests matching specific criteria (method, status, path, etc.) - Clean up test data after automated test runs ### How It Works 1. **Build Query**: Apply the same filters available in GET to target specific requests 2. **Execute Delete**: All matching requests are permanently deleted 3. **Return Count**: Response includes the number of deleted requests ### Filtering Options All GET filters are supported for selective deletion: **Time-Based:** - `dateFrom` / `dateTo`: Delete requests within a date range - `dateRange`: Delete requests from a relative time period **Request Attributes:** - `method`: Delete requests with specific HTTP method - `path`: Delete requests matching path pattern - `status`: Delete requests with specific status code - `behavior`: Delete requests handled by specific behavior type - `ruleMatched`: Delete requests that matched (or didn't match) rules **Content Search:** - `requestBody`: Delete requests containing specific text in body - `responseBody`: Delete requests with specific response content ### Delete All Requests To delete ALL requests for an endpoint, call this endpoint without any query parameters. **Warning**: This permanently removes all request history and cannot be undone. ### Common Deletion Patterns **Delete requests older than 7 days:** ``` DELETE /requests?dateTo=2024-01-08T00:00:00Z ``` **Delete all failed requests (5xx errors):** ``` DELETE /requests?status=500 ``` **Delete requests from last hour:** ``` DELETE /requests?dateRange=1h ``` **Delete requests to a specific path:** ``` DELETE /requests?path=/api/test ``` ### Limitations - Operation is irreversible; deleted requests cannot be recovered - Associated multipart files are also deleted - Does not affect endpoint configuration, rules, or state ### Use Cases - **Post-Test Cleanup**: Remove all requests after a test run completes - **Retention Policy**: Automatically delete requests older than N days - **Privacy Compliance**: Remove requests containing specific patterns tags: [Request History] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' - in: query name: id schema: type: string description: Delete a specific request by ID (alternative to using the {requestId} path parameter). - in: query name: method schema: type: string description: Delete requests matching this HTTP method. - in: query name: status schema: type: integer description: Delete requests matching this HTTP response status code. - in: query name: path schema: type: string description: Delete requests matching this path substring or regex pattern. - in: query name: behavior schema: type: string enum: [mock-rule, proxy, callout, grpc, wsdl, graphql, tunnel, oas] description: Delete requests matching this behavior mode. - in: query name: ruleMatched schema: type: boolean description: Delete requests that matched (true) or missed (false) mock rules. - in: query name: dateFrom schema: type: string format: date-time description: Delete requests received after this ISO 8601 timestamp. - in: query name: dateTo schema: type: string format: date-time description: Delete requests received before this ISO 8601 timestamp. - in: query name: dateRange schema: type: string description: Delete requests within a relative time range (e.g., '1h', '24h', '7d'). responses: '200': description: Requests deleted successfully content: application/json: schema: oneOf: - type: object properties: id: type: string deleted: type: boolean description: Response when deleting a single request by ID - type: object properties: deleted: type: boolean count: type: integer description: Response when deleting multiple requests via filtering '400': description: Bad Request - Invalid query parameters content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' /v2/endpoints/{endpoint}/requests/{requestId}: get: summary: Get a single request description: | Retrieves complete details for a specific request by its unique identifier. This endpoint always returns the verbose format with full request and response payloads. ### Purpose Use this endpoint to: - Inspect the full details of a specific request - Debug why a particular request succeeded or failed - View the exact headers and body sent by the client - Examine the response that Beeceptor returned - Analyze proxy/callout details if the request was forwarded ### Response Structure The response includes all available information about the request: **Core Fields:** - `id`: Unique request identifier - `date`: ISO 8601 timestamp when request was received - `method`: HTTP method (GET, POST, PUT, DELETE, etc.) - `path`: Full request path including query parameters - `status`: HTTP response status code returned - `timeTaken`: Processing time in milliseconds **Rule Matching:** - `rule.matched`: Boolean indicating if a mock rule matched - `rule.ruleId`: ID of the matched rule (if any) - `rule.weightedResponse`: Name of selected response (for weighted rules) **Request Details:** - `request.body`: Raw request body content - `request.headers`: Object containing all request headers - `request.httpVersion`: HTTP version used (e.g., "HTTP/1.1", "HTTP/2") - `request.isMultipart`: Boolean for multipart/form-data requests - `request.multipartData`: Array of file/field metadata (for multipart requests) - `request.redacted`: Boolean indicating if sensitive data was masked **Response Details:** - `response.body`: Raw response body content - `response.headers`: Object containing all response headers - `response.httpVersion`: HTTP version used - `response.blob`: Boolean if response was served from blob storage - `response.blobPath`: Path to blob file (if blob response) - `response.redacted`: Boolean indicating if sensitive data was masked **Callout Details (if request was proxied):** - `callout.url`: Target URL for the callout - `callout.method`: HTTP method used for callout - `callout.behavior`: Sync or async callout - `callout.delay`: Artificial delay applied (if any) - `callout.targetRequest`: Headers and body sent to upstream - `callout.targetResponse`: Headers and body received from upstream **gRPC Requests:** For gRPC requests, the structure differs slightly: - `request.messages`: Array of gRPC request messages with body, headers, timestamp - `response.messages`: Array of gRPC response messages with body, timestamp ### Use Cases - **Debugging Integration Issues**: Examine exact payloads when API calls fail - **Webhook Verification**: Confirm webhook payloads match expectations - **Rule Testing**: Verify that the correct rule matched a request - **Proxy Analysis**: Inspect both client and upstream communications - **Support Requests**: Share specific request details when reporting issues tags: [Request History] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' - in: path name: requestId required: true schema: type: string description: The unique identifier of the request to retrieve. responses: '200': description: Request details (verbose format with full details) content: application/json: schema: $ref: '#/components/schemas/RequestLogVerbose' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' delete: summary: Delete a single request description: | Permanently deletes a specific request from the history by its unique identifier. This operation is irreversible. ### Purpose Use this endpoint to: - Remove sensitive requests containing confidential data - Clean up test or debug requests ### What Gets Deleted - The request log entry (metadata, headers, body) - Associated response data - Callout/proxy details (if applicable) - Multipart file metadata (actual files may be retained separately) ### Limitations - Operation is irreversible; deleted requests cannot be recovered - Does not affect endpoint configuration, rules, or state - Multipart file content may be retained temporarily for other requests ### Use Cases - **Test Cleanup**: Delete test requests that clutter the history - **Security**: Remove requests with accidentally exposed credentials tags: [Request History] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' - in: path name: requestId required: true schema: type: string description: The unique identifier of the request to delete. responses: '200': description: Request deleted successfully content: application/json: schema: type: object properties: id: type: string description: The ID of the deleted request deleted: type: boolean description: Always true on successful deletion '401': $ref: '#/components/responses/Unauthorized' /v2/endpoints/{endpoint}/requests/{requestId}/multipart/download: get: summary: Download multipart file from request description: | Downloads a file attachment from a multipart/form-data request. This endpoint retrieves the actual file content that was uploaded as part of a request. ### Purpose Use this endpoint to: - Retrieve files uploaded via multipart requests - Download attachments for inspection or analysis - Export uploaded files for testing or compliance - Verify file contents match expected uploads ### How It Works When a multipart/form-data request is received by Beeceptor: 1. File metadata (field name, file name, content type, size) is stored with the request log 2. File content is stored separately in binary format 3. The request history shows file metadata but not content (to keep responses manageable) 4. This endpoint retrieves the actual file content ### Required Parameters Both query parameters are required to identify the specific file: **fieldName**: The name of the form field containing the file - Must match the `name` attribute in the multipart form - Example: For ``, use `fieldName=document` **component**: Where the file was captured - `Request`: File from the incoming client request - `CalloutRequest`: File forwarded to an upstream proxy target ### Response Returns the raw file content with appropriate headers: - `Content-Type`: Original MIME type of the uploaded file - `Content-Disposition`: Attachment with original filename - `Content-Length`: File size in bytes ### Finding File Information To identify which files are available for a request: 1. Call GET `/requests/{requestId}` (returns verbose format) 2. Check `request.multipartData` array for file metadata 3. Use `fieldName` and `fileName` from the metadata ### Limitations - Only files (not text fields) can be downloaded - File must exist in the request's multipart data - Files are retained for the same duration as request history (up to 10 days) - Maximum file size depends on subscription plan ### Use Cases - **Debugging File Uploads**: Verify uploaded files match expectations - **Compliance Auditing**: Review files submitted through your API - **Test Verification**: Confirm test files were received correctly - **Data Export**: Extract files for external analysis tags: [Request History] tags: [Request History] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' - in: path name: requestId required: true schema: type: string description: The unique identifier of the request containing the file. - in: query name: fieldName required: true schema: type: string description: The name of the form field containing the file. - in: query name: component required: true schema: type: string enum: [Request, CalloutRequest] description: The component where the file is located (Request or CalloutRequest). responses: '200': description: File downloaded successfully content: application/octet-stream: schema: type: string format: binary '400': description: Bad Request - Missing required query parameters (fieldName or component) content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /v2/endpoints/{endpoint}/settings: get: summary: Get endpoint settings description: Retrieve the current settings for the endpoint. tags: [Endpoint Settings] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' responses: '200': description: Endpoint settings content: application/json: schema: $ref: '#/components/schemas/EndpointSettings' example: security: enabled: true headerKey: "some-key" headerValue: "some-value" cors: origins: - "https://one.example.com" - "https://two.example.com" locale: "en" rateLimit: enabled: true rate: 5 period: "Second" crud: autoDelete: true customDomain: enabled: true domain: "whitelabel.example.com" mtls: enabled: false localTunnel: false proxy: targetUrl: "https://target.example.com" ignoreSSLErrors: false rules: enabled: true '401': $ref: '#/components/responses/Unauthorized' patch: summary: Update endpoint settings description: Update specific settings for the endpoint. tags: [Endpoint Settings] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EndpointSettings' responses: '200': description: Settings updated content: application/json: schema: $ref: '#/components/schemas/EndpointSettings' example: security: enabled: true headerKey: "some-key" headerValue: "some-value" cors: origins: - "https://one.example.com" - "https://two.example.com" locale: "en" rateLimit: enabled: true rate: 5 period: "Second" crud: autoDelete: true customDomain: enabled: true domain: "whitelabel.example.com" mtls: enabled: false localTunnel: false proxy: targetUrl: "https://target.example.com" ignoreSSLErrors: false rules: enabled: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /v2/endpoints/{endpoint}/state: get: summary: Get all state variables description: | Retrieves a list of all persistent state variables (Counters, Lists, Data Store keys) defined for this endpoint. tags: [State Store] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' - in: query name: limit schema: type: integer example: 50 - in: query name: offset schema: type: integer example: 0 - in: query name: type schema: type: string enum: [string, counter, list] example: list - in: query name: keyPrefix schema: type: string example: cart_ responses: '200': description: List of state variables content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/StateItem' pagination: $ref: '#/components/schemas/Pagination' example: data: - type: "String" key: "someStore" value: "someVal" lastModified: "2025-12-24T07:01:21.476Z" - type: "List" key: "someList" value: - "item1" - "item2" - "item3" lastModified: "2026-01-28T07:50:32.849Z" - type: "Counter" key: "someCounter" value: 5 lastModified: "2026-01-28T07:50:42.985Z" pagination: total: 3 limit: 20 offset: 0 hasMore: false '401': $ref: '#/components/responses/Unauthorized' put: summary: Upsert state variables description: Bulk updates or creates state variables. tags: [State Store] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' requestBody: required: true content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/StateItem' responses: '200': description: State items upserted content: application/json: schema: type: object properties: created: type: integer updated: type: integer example: created: 2 updated: 1 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' delete: summary: Delete state items description: Remove specified state variables by their keys. tags: [State Store] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' requestBody: required: true content: application/json: schema: oneOf: - type: object properties: all: type: boolean - type: object properties: items: type: array items: type: object properties: type: type: string key: type: string responses: '200': description: State items deleted content: application/json: schema: type: object properties: deleted: type: boolean count: type: integer example: deleted: true count: 3 '401': $ref: '#/components/responses/Unauthorized' /v2/endpoints/{endpoint}/state/{type}/{key}: get: summary: Get a single state item description: Retrieve the value of a specific state item. tags: [State Store] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' - in: path name: type required: true schema: type: string enum: [string, counter, list] example: list - in: path name: key required: true schema: type: string example: cart_items responses: '200': description: State item content: application/json: schema: $ref: '#/components/schemas/StateItem' example: type: "List" key: "someList" value: - "item1" - "item2" - "item3" lastModified: "2026-01-28T07:50:32.849Z" '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' delete: summary: Delete a single state item description: Delete a specific state item. tags: [State Store] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' - in: path name: type required: true schema: type: string example: list - in: path name: key required: true schema: type: string example: cart_items responses: '200': description: State item deleted content: application/json: schema: type: object properties: key: type: string deleted: type: boolean example: key: "someList" deleted: true '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /v2/endpoints/{endpoint}/specs: get: summary: Get specification details description: Returns the metadata and current configuration of the uploaded API specification (OAS, WSDL, gRPC, or GraphQL). tags: [Endpoint Settings] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' responses: '200': description: Success content: application/json: schema: type: object properties: data: type: object properties: type: type: string enum: [openapi, grpc, graphql, wsdl] intelligenceMock: type: boolean example: data: type: openapi intelligenceMock: true '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' post: summary: Upload API specification (Async) description: | Uploads an OpenAPI (YAML/JSON), WSDL, GraphQL, or Proto file to automate mock response generation. This is an asynchronous operation that returns a Job ID. tags: [Endpoint Settings] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary description: The specification file to upload (Max 2.5MB). intelligenceMock: type: boolean description: Enable AI-driven mock response generation. responses: '202': description: Upload accepted and processing initiated. content: application/json: schema: $ref: '#/components/schemas/Job' example: jobId: job-9a7f3b2c1d status: QUEUED type: oas message: Job queued for oas processing '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' delete: summary: Delete API specification description: | Removes the uploaded API specification and stops any automated mock behaviors tied to it. tags: [Endpoint Settings] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' responses: '200': description: Specification deleted content: application/json: schema: type: object properties: data: type: object properties: deleted: type: boolean example: data: deleted: true '401': $ref: '#/components/responses/Unauthorized' /v2/endpoints/{endpoint}/jobs/{jobId}: get: summary: Get job status description: Polls the status of an asynchronous background job using the Job ID returned during a specification upload. tags: [Endpoint Settings] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' - in: path name: jobId required: true schema: type: string example: job-6a1ed3b07798 responses: '200': description: Job status retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/Job' example: jobId: job-6a1ed3b07798 status: COMPLETED message: Job completed successfully result: channelId: endpoint-name dashboardUrl: "https://app.beeceptor.com/console/endpoint-name" completedAt: '2026-01-28T09:31:02.729Z' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /v2/endpoints/{endpoint}/mtls/certificates: get: summary: Get all mTLS certificates description: Lists all client certificates associated with this endpoint for Mutual TLS. tags: [Endpoint Settings] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' responses: '200': description: A list of certificates. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Certificate' example: data: - id: "6979d6d456c8ed5324860496" name: "cert-1" cert: "-----BEGIN CERTIFICATE-----\nMIIEoDCCAogCAQ... (truncated)\n-----END CERTIFICATE-----\n" key: "-----BEGIN PRIVATE KEY-----\nMIIJQwIBAD... (truncated)\n-----END PRIVATE KEY-----\n" expiry: "2027-01-28T09:28:50.960Z" createdAt: "2026-01-28T09:28:52.938Z" - id: "6979d6d856c8ed53248604a6" name: "cert-2" cert: "-----BEGIN CERTIFICATE-----\nMIIEnjCCAoYCAQ... (truncated)\n-----END CERTIFICATE-----\n" key: "-----BEGIN PRIVATE KEY-----\nMIIJQgIBAD... (truncated)\n-----END PRIVATE KEY-----\n" expiry: "2027-01-28T09:28:55.827Z" createdAt: "2026-01-28T09:28:56.747Z" '401': $ref: '#/components/responses/Unauthorized' post: summary: Add mTLS certificate description: Generates a new client certificate and private key for Mutual TLS authentication. tags: [Endpoint Settings] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: A friendly name for the certificate. required: [name] responses: '201': description: Certificate added. content: application/json: schema: $ref: '#/components/schemas/Certificate' example: id: "6979d6d456c8ed5324860496" name: "cert-1" cert: "-----BEGIN CERTIFICATE-----\nMIIEoDCCAogCAQ... (truncated)\n-----END CERTIFICATE-----\n" key: "-----BEGIN PRIVATE KEY-----\nMIIJQwIBAD... (truncated)\n-----END PRIVATE KEY-----\n" expiry: "2027-01-28T09:28:50.960Z" createdAt: "2026-01-28T09:28:52.938Z" '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' /v2/endpoints/{endpoint}/mtls/certificates/{certId}: delete: summary: Delete mTLS certificate description: Remove a specific client certificate. tags: [Endpoint Settings] security: - ApiKeyAuth: [] parameters: - $ref: '#/components/parameters/EndpointName' - in: path name: certId required: true schema: type: string example: "6979d6d456c8ed5324860496" responses: '200': description: Certificate deleted. content: application/json: schema: type: object properties: id: type: string deleted: type: boolean example: id: "6979d6d456c8ed5324860496" deleted: true '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound'