Beeceptor Endpoint Settings API
The Endpoint Settings API from Beeceptor — 5 operation(s) for endpoint settings.
OpenAPI Specification
openapi: 3.1.0
info:
title: Beeceptor Endpoint Settings 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: Endpoint Settings
paths:
/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}/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 \nresponse generation. This is an asynchronous operation that returns a Job ID.\n"
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 \nbehaviors tied to it.\n"
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-----
MIIEoDCCAogCAQ... (truncated)
-----END CERTIFICATE-----
'
key: '-----BEGIN PRIVATE KEY-----
MIIJQwIBAD... (truncated)
-----END PRIVATE KEY-----
'
expiry: '2027-01-28T09:28:50.960Z'
createdAt: '2026-01-28T09:28:52.938Z'
- id: 6979d6d856c8ed53248604a6
name: cert-2
cert: '-----BEGIN CERTIFICATE-----
MIIEnjCCAoYCAQ... (truncated)
-----END CERTIFICATE-----
'
key: '-----BEGIN PRIVATE KEY-----
MIIJQgIBAD... (truncated)
-----END PRIVATE KEY-----
'
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-----
MIIEoDCCAogCAQ... (truncated)
-----END CERTIFICATE-----
'
key: '-----BEGIN PRIVATE KEY-----
MIIJQwIBAD... (truncated)
-----END PRIVATE KEY-----
'
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'
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'
schemas:
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. \nRequests missing the secret header will be rejected without affecting your quota.\n"
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 \nstorage limit is reached to accommodate new data.\n"
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
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
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-----
MIIDDTCCAfWgAwIBAgIJAJ...
-----END CERTIFICATE-----'
key:
type: string
description: Private key in PEM format (Redacted in list views).
example: '-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0B...
-----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'
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'
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
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization