State Management

Beeceptor’s State Management APIs allow you to persist and manipulate data across mock API calls. These persistent store introduce a stateful behavior into your mock API orchestration, when multiple service calls are interlinked.

With a flexible key-value datastore and support for counters and lists, you can build more realistic mocks that evolve over time - such as tracking user sessions, managing resource states, or counting API usage.

Supported Data Types

The state management system supports three data types, each tailored to specific use cases:

Type	Description	Ideal Use Case
counter	Numeric value that supports increment/decrement	Track page views, API call counts, metrics
datastore	Generic key-value store for JSON-serializable data	Save user sessions, config flags, temporary data
list	Ordered collection of items (array-based)	Maintain queues, logs, or grouped items

Creating or Updating State Data

You can create or update multiple state items in a single API call using the /datastore endpoint. The operation is atomic, meaning that either **all operations succeed or none are applied. This is especially useful for setting up initial test data or modifying the state during test automation workflows.

This API performs an upsert — if the item (type + key combination) already exists, it will be updated; otherwise, it will be created.

Request Details

Method	Request Path
POST	https://api.beeceptor.com/api/v1/endpoints/<my-endpoint>/datastore

• <my-endpoint> - name of the Beeceptor endpoint

Request Parameters

Parameter	Type	Description
data	array	Array of datastore operations to perform
data[].type	string	Type of datastore item. Must be one of: datastore, list, counter
data[].key	string	Unique identifier for the item (1-100 characters)
data[].value	mixed	Value to store. Type depends on the type parameter

Example: Mixed Data Types

This example demonstrates creating multiple items of different types in a single request.

Request Payload

{
  "data": [
    {
      "type": "datastore",
      "key": "user_session",
      "value": {
        "userId": "12345",
        "sessionId": "sess_abc123",
        "loginTime": "2023-11-02T12:00:00Z"
      }
    },
    {
      "type": "list",
      "key": "recent_activities",
      "value": [
        "login",
        "view_dashboard",
        "update_profile"
      ]
    },
    {
      "type": "counter",
      "key": "page_views",
      "value": 42
    },
    {
      "type": "datastore",
      "key": "app_config",
      "value": "production"
    }
  ]
}

Success Response

The following represents a successful response with 200 as HTTP response code.

{
  "result": {
    "successful": 4
  }
}

Error Response - Validation Error

For validation errors, the HTTP response code will be 400.

{
  "error": {
    "code": "validation_error",
    "message": "/data/0/key: should NOT be shorter than 1 characters",
    "parameter": "/data/0/key"
  }
}

Error Response - Duplicate Key

When duplicate type+key combinations are found in the request:

{
  "error": {
    "code": "duplicate_key",
    "message": "Duplicate key found: type=\"datastore\", key=\"user_session\". Each type+key combination must be unique in the request.",
    "parameter": "type: datastore, key: user_session"
  }
}

Error Response - Internal Error

For server errors, the HTTP response code will be 500.

{
  "error": {
    "code": "internal_error",
    "message": "Some error occurred during bulk operations. Contact support."
  }
}

Example: Counter Usage

Track usage metrics such as API calls and error counts.

Request Payload

{
  "data": [
    {
      "type": "counter",
      "key": "api_calls_today",
      "value": 150
    },
    {
      "type": "counter",
      "key": "error_count",
      "value": 0
    }
  ]
}

Example: List Storage

Store array data like shopping carts or permissions.

Request Payload

{
  "data": [
    {
      "type": "list",
      "key": "shopping_cart",
      "value": [
        {"id": 1, "name": "Product A", "price": 29.99},
        {"id": 2, "name": "Product B", "price": 15.50}
      ]
    },
    {
      "type": "list",
      "key": "user_permissions",
      "value": ["read", "write", "admin"]
    }
  ]
}

Limitations

• type + key combination must be unique within a request.
• Key length must be between 1 to 100 characters.
• You can send up to 100 items per request.
• The is an upsert API. It creates new items or updates existing ones.

State Cleanup

The State Cleanup API allows you to remove stored data from Beeceptor’s persistent state, either entirely or for specific items. This is useful for resetting state between test runs, removing temporary data, or maintaining a clean testing environment.

Request Details

Method	Request Path
DELETE	https://api.beeceptor.com/api/v1/endpoints/<my-endpoint>/datastore

• <my-endpoint> - name of the Beeceptor endpoint

The API supports two cleanup modes.

Cleanup Mode: Delete All

Use this mode to remove all state items for an endpoint, send a request with the all flag set to true.

Request Payload

{
  "all": true
}

Success Response

{
  "data": {
    "scope": "all",
    "successful": 15
  }
}

Cleanup Mode: Selective Delete

Use this to remove specific items, include an array of type and key pairs in the request body.

Request Parameters

Parameter	Type	Description
data	array	Array of 1 to 100 items to delete
data[].type	string	Type of item: datastore, list, or counter
data[].key	string	Key of the item to delete

Request Payload

{
  "data": [
    {
      "type": "datastore",
      "key": "user_session"
    },
    {
      "type": "counter",
      "key": "page_views"
    },
    {
      "type": "list",
      "key": "recent_activities"
    }
  ]
}

Success Response

{
  "data": {
    "scope": "some",
    "successful": 3,
    "items": [
      {
        "type": "datastore",
        "key": "user_session"
      },
      {
        "type": "counter",
        "key": "page_views"
      },
      {
        "type": "list",
        "key": "recent_activities"
      }
    ]
  }
}

Error Response: Validation Error

Returned when the request payload is missing required fields or is malformed (400 Bad Request).

{
  "error": {
    "code": "validation_error",
    "message": "/data: should NOT have fewer than 1 items",
    "parameter": "/data"
  }
}

Error Response: Internal Server Error

Returned when an unexpected error occurs during the cleanup operation (500 Internal Error).

{
  "error": {
    "code": "internal_error",
    "message": "Some error occurred during cleanup operation. Contact support."
  }
}

Limitations

• Maximum of 100 items per cleanup request
• Cleanup operations are non-reversible
• Cleanup requests are atomic - all or none of the deletions will be applied