openapi: 3.0.3
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 `<input type="file" name="document">`, 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]
      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'