Beeceptor State Store API

openapi: 3.1.0
info:
  title: Beeceptor Endpoint Settings State Store API
  description: "\nThis documentation describes the **Beeceptor Mock Server Management APIs**. It is used to programmatically configure, inspect, and operate Beeceptor mock servers.\n\n**You can find the OpenAPI specification here:** [Beeceptor Management APIs (OpenAPI Spec)](https://beeceptor.com/docs/openapi/beeceptor-openapi-v2.yaml) \n\n## What is Beeceptor?\n\nBeeceptor is a developer-focused API simulation platform. It is a **behavioral API simulator** designed for mocking, service virtualization, contract testing, and controlled failure simulation.\n\nBeeceptor provides:\n\n- HTTP, Rest, SOAP, gRPC and GraphQL API mocking\n- Stateful API prototyping (CRUD, counters, lists)\n- Failure, latency, and chaos testing\n- Proxying and controlled callouts to real upstream services\n\nBeeceptor operates by **matching incoming requests against declarative rules**\nand **emitting predefined or dynamically generated responses**. It guarantees:\n- Deterministic rule evaluation order\n- Isolation between endpoints\n- Explicit behavior only, no hidden defaults\n\nBeeceptor 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.\n\n## Entities\n\n### Endpoint\n\nAn **Endpoint** is an isolated mock server identified by a unique subdomain.\n\n- Owns its own configuration, rules, and state\n- Receives all incoming HTTP or traffic for that subdomain\n- Acts as the root execution boundary\n\nAll requests are evaluated strictly within the context of the endpoint they arrive on.\n\n### Mock Rule\n\nA **Mock Rule** is an ordered, declarative instruction that defines:\n\n- How to match an incoming request\n- What response to emit when matched\n- Optional delays, randomness, or state conditions\n\nThese 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:\n- HTTP method\n- URL path or regex\n- Headers\n- Request body content\n- Stateful conditions (counters, lists, datastore values)\n\nAll the conditions must evaluate to true for a rule to match or win for the response generation.\n\n## Response Generation\n\nA response definition specifies what Beeceptor returns when a rule is matched.\n\nA response may include:\n- HTTP status code\n- Headers\n- Static payloads\n- Templated payloads\n- Weighted random responses\n\nThe responses are emitted exactly as defined in the mock rule. Beeceptor does not modify payloads beyond explicit templating instructions.\n\n### Template Engine\n\nThe template engine serves as an optional response processor, enabling the creation of dynamic and context-aware payloads.\n\nWhen this feature is enabled, responses can:\n- Reference data from the incoming request, such as headers, query parameters, and the body.\n- Generate synthetic or randomized values using built-in functions.\n- Apply conditional logic and iterative loops for complex response structures.\n- Integrate with stateful storage to maintain persistence across calls.\n\nThese templates are evaluated dynamically at the time of the request, following the identification of a matching rule.\n\n## Stateful Storage\n\nBeeceptor provides a suite of lightweight, endpoint-scoped state primitives designed to facilitate dynamic response behavior and simulate stateful API interactions.\n\nThe following storage types are supported:\n- CRUD Datastore: A flexible storage mechanism for JSON objects, supporting standard create, read, update, and delete operations.\n- Counters: Numeric primitives suitable for maintaining sequence-based or incremental state.\n- Lists: Ordered collections that allow for both append operations and structured querying.\n- Key-Value Store: A fundamental storage type for persisting simple data pairs.\n\nAll 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.\n\n## HTTP Callout\n\nBeeceptor can be configured as a programmable intermediary to forward incoming traffic to specified upstream services.\n\nThese rules support several advanced integration patterns:\n- Synchronous Forwarding: Inbound requests are transmitted to the target service, and the resulting response is relayed back to the client.\n- Payload Transformation: The system can dynamically modify both request and response data while in transit.\n- Latency Simulation: Artificial delays can be introduced to model various network conditions or service dependencies.\n- Asynchronous Callouts: Operations can be executed in a fire-and-forget mode, which is ideal for triggering background webhooks without delaying the client response.\n\n## Primary Use Cases\n\n**Automated Testing and CI/CD Integration**\n- Configure and update mock behaviors dynamically through the Beeceptor Management API.\n- Substitute external dependencies with consistent mock endpoints during automated test suites.\n- Enable deterministic environment setup and teardown for reliable continuous integration.\n\n**Accelerating Frontend Development**\n- Implement mock rules to simulate specific edge cases and error scenarios.\n- Proceed with user interface development independently of backend progress.\n- Utilize OpenAPI, GraphQL, gRPC, WSDL specifications and predefined examples to generate functional response payloads.\n\n**Performance and Resilience Evaluation**\n- Introduce artificial network latency and weighted response distribution to test system limits.\n- Reproduce timeouts, server-side errors, and intermittent service unavailability.\n- Validate application stability and retry logic without impacting live infrastructure.\n\n**Rapid Stateful Prototyping**\n- Design complex, state-dependent API workflows using built-in CRUD and storage primitives.\n- Iterate on application logic and data flows without the overhead of database management.\n- Programmatically manage and reset simulation state to maintain test consistency.\n"
  version: 2.0.0
  x-release-status: testing
  x-internal: true
servers:
- url: https://api.beeceptor.com/api
  description: Production API Server
tags:
- name: State Store
paths:
  /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'
components:
  responses:
    Forbidden:
      description: Unauthorized - You don't have access to this endpoint.
      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'
    BadRequest:
      description: Bad Request - Payload validation failed.
      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'
  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:
    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
    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'
    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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization