API reference · v0.2.0

The JumboBridge API

Everything the console does goes through this HTTP API — so everything the console does, your scripts and CI can do too. JSON in, JSON out, plus one WebSocket for live updates.

Basics

Base URL & conventions

The API is served next to the UI: http://localhost:8080/api by default. Requests and responses are JSON. Create endpoints accept port: 0 (or omit it) to auto-assign a free port from the reserved range. Entity run-state changes only through the start/stop endpoints.

No auth by default. JumboBridge trusts its network: the API is open unless the Enterprise login gate is enabled. Run it on a trusted network or behind your own auth proxy — don't expose it to the public internet.

Quickstart

Three requests to see the shape

Create a project

curl -X POST http://localhost:8080/api/projects \
  -H 'content-type: application/json' \
  -d '{"name":"Payments Gateway","description":"integration sandbox"}'

Create and start a forwarding rule

# port 0 = auto-assign from the reserved range
curl -X POST http://localhost:8080/api/forwarding-rules \
  -H 'content-type: application/json' \
  -d '{"project_id":"default","name":"api","source_port":0,
       "target_host":"api.internal","target_port":8080,"protocol":"http"}'

curl -X POST http://localhost:8080/api/rules/<id>/start

Create, start and seed a mock database

curl -X POST http://localhost:8080/api/mock-databases \
  -H 'content-type: application/json' \
  -d '{"project_id":"default","name":"orders-db"}'

curl -X POST http://localhost:8080/api/mock-dbs/<id>/start

curl -X POST http://localhost:8080/api/mock-dbs/<id>/query \
  -H 'content-type: application/json' \
  -d '{"sql":"CREATE TABLE orders (id INTEGER PRIMARY KEY, total REAL); INSERT INTO orders VALUES (1, 9.99);"}'

Endpoints

REST reference

Hand-maintained against v0.2.0 — the routes live in crates/server/src/api/ if you want the source of truth.

Health & info

Always available, no auth.

Method	Path	Description
GET	/api/health	Liveness check.
GET	/api/info	Server and build info.

Projects

Group forwards, mocks, databases and scenarios. The default project always exists and can't be deleted.

Method	Path	Description
GET	/api/projects	List projects.
POST	/api/projects	Create a project.
GET	/api/projects/{id}	Get one project.
PUT	/api/projects/{id}	Update a project.
DELETE	/api/projects/{id}	Delete a project.

Forwarding rules

TCP/UDP/HTTP forwarders. Pass port 0 on create to auto-assign from the range.

Method	Path	Description
GET	/api/forwarding-rules	List rules.
POST	/api/forwarding-rules	Create a rule.
GET	/api/forwarding-rules/{id}	Get one rule.
PUT	/api/forwarding-rules/{id}	Update a rule.
DELETE	/api/forwarding-rules/{id}	Delete a rule.
POST	/api/rules/{id}/start	Start the forwarder.
POST	/api/rules/{id}/stop	Stop the forwarder.
GET	/api/rules/{id}/statistics	Connection and byte counters.

Echo servers

Method	Path	Description
GET	/api/echo-servers	List echo servers.
POST	/api/echo-servers	Create an echo server.
GET	/api/echo-servers/{id}	Get one echo server.
PUT	/api/echo-servers/{id}	Update an echo server.
DELETE	/api/echo-servers/{id}	Delete an echo server.
POST	/api/echo/{id}/start	Start the listener.
POST	/api/echo/{id}/stop	Stop the listener.

Mock servers

Protocol-aware listeners (HTTP, WebSocket, raw TCP, MCP, LLM) that answer traffic.

Method	Path	Description
GET	/api/mock-servers	List mock servers.
POST	/api/mock-servers	Create a mock server.
GET	/api/mock-servers/{id}	Get one mock server.
PUT	/api/mock-servers/{id}	Update a mock server.
DELETE	/api/mock-servers/{id}	Delete a mock server.
POST	/api/mocks/{id}/start	Start the mock.
POST	/api/mocks/{id}/stop	Stop the mock.
POST	/api/mocks/{id}/restart	Restart (applies edits).
GET	/api/mocks/{id}/log	The request log.
DELETE	/api/mocks/{id}/log	Clear the request log.
GET	/api/mock-protocols	Supported protocols.

Mock rules

Priority-ordered request/message patterns and their responses.

Method	Path	Description
GET	/api/mock-rules?mock_server_id={id}	List rules (optionally per server).
POST	/api/mock-rules	Create a rule.
GET	/api/mock-rules/{id}	Get one rule.
PUT	/api/mock-rules/{id}	Update a rule.
DELETE	/api/mock-rules/{id}	Delete a rule.

Mock databases

Hosted SQLite databases served over the PostgreSQL wire protocol (plus Enterprise external connections).

Method	Path	Description
GET	/api/mock-databases	List mock databases.
POST	/api/mock-databases	Create a database.
GET	/api/mock-databases/{id}	Get one database.
PUT	/api/mock-databases/{id}	Update a database.
DELETE	/api/mock-databases/{id}	Delete a database (and its file).
POST	/api/mock-dbs/{id}/start	Start the wire listener.
POST	/api/mock-dbs/{id}/stop	Stop the wire listener.
POST	/api/mock-dbs/{id}/restart	Restart the listener.
GET	/api/mock-dbs/{id}/schema	Tables, columns and row counts.
GET	/api/mock-dbs/{id}/tables/{table}/rows	Page through table data.
POST	/api/mock-dbs/{id}/query	Run SQL from the console (DDL and multi-statement scripts supported).
GET	/api/mock-dbs/{id}/log	The live query log.
DELETE	/api/mock-dbs/{id}/log	Clear the query log.
GET	/api/mock-db-engines	Supported engines.
POST	/api/mock-dbs/test-connection	Test an external connection (Enterprise).

Disruptions

Latency, throttle, drop, corrupt, partial, blackhole and close — armed per scenario.

Method	Path	Description
GET	/api/disruptions	List scenarios.
POST	/api/disruptions	Create a scenario.
GET	/api/disruptions/{id}	Get one scenario.
PUT	/api/disruptions/{id}	Update a scenario.
DELETE	/api/disruptions/{id}	Delete a scenario.
POST	/api/disruptions/{id}/arm	Arm the scenario.
POST	/api/disruptions/{id}/disarm	Disarm the scenario.
GET	/api/disruptions-active	Effects currently applied.

API client

Saved requests sent server-side — no CORS, can reach internal ports.

Method	Path	Description
GET	/api/requests	List saved requests.
POST	/api/requests	Create a saved request.
GET	/api/requests/{id}	Get one request.
PUT	/api/requests/{id}	Update a request.
DELETE	/api/requests/{id}	Delete a request.
POST	/api/requests/{id}/send	Send it once, return the full response.
POST	/api/requests/{id}/load	Start a load run (concurrent traffic).
GET	/api/requests/{id}/load	Load-run status.
POST	/api/requests/{id}/load/stop	Stop the load run.
GET	/api/requests/{id}/runs	Run history for one request.
GET	/api/runs	All run history.
GET	/api/request-protocols	Supported request protocols.

Test suites

Method	Path	Description
GET	/api/test-suites	List suites.
POST	/api/test-suites	Create a suite.
GET	/api/test-suites/{id}	Get one suite.
PUT	/api/test-suites/{id}	Update a suite.
DELETE	/api/test-suites/{id}	Delete a suite.
GET	/api/test-suites/{id}/items	List suite items.
POST	/api/test-suites/{id}/items	Add a saved request to the suite.
PUT	/api/test-suites/{id}/items/order	Reorder items.
DELETE	/api/test-suites/{id}/items/{item_id}	Remove an item.
POST	/api/test-suites/{id}/run	Run the suite now.
GET	/api/test-suites/{id}/runs	Run history for the suite.
GET	/api/suite-runs/{id}	One run with per-request results.

Environments

Named {{var}} sets for the API client; one active per project.

Method	Path	Description
GET	/api/environments	List environments.
POST	/api/environments	Create an environment.
GET	/api/environments/{id}	Get one environment.
PUT	/api/environments/{id}	Update an environment.
DELETE	/api/environments/{id}	Delete an environment.
POST	/api/environments/{id}/activate	Make it the active one.

MCP explorer

Method	Path	Description
POST	/api/mcp/connect	Open a live session to an MCP server.
POST	/api/mcp/{conn}/call	Invoke a tool on the session.
POST	/api/mcp/{conn}/disconnect	Close the session.
GET	/api/mcp-targets	List saved MCP targets.
POST	/api/mcp-targets	Save a target.
GET	/api/mcp-targets/{id}	Get one target.
PUT	/api/mcp-targets/{id}	Update a target.
DELETE	/api/mcp-targets/{id}	Delete a target.

Ports, settings & access log

Method	Path	Description
GET	/api/ports	Port-range overview: free, reserved, running.
GET	/api/settings	All settings.
GET	/api/settings/{key}	One setting.
PUT	/api/settings/{key}	Set a setting.
GET	/api/access-log/{entity_type}/{entity_id}	Access log for a forward/echo (secrets redacted).
DELETE	/api/access-log/{entity_type}/{entity_id}	Clear that log.

Auth, users & Enterprise

Auth is disabled by default; these matter once the Enterprise login gate is on.

Method	Path	Description
GET	/api/auth/config	Whether login is required.
POST	/api/auth/login	Start a session.
POST	/api/auth/logout	End the session.
GET	/api/auth/me	The current user.
GET	/api/users	List users.
POST	/api/users	Create a user.
PUT	/api/users/{id}	Update a user.
DELETE	/api/users/{id}	Delete a user.
GET	/api/projects/{id}/members	List project members.
POST	/api/projects/{id}/members	Add or change a member role.
DELETE	/api/projects/{id}/members/{user_id}	Remove a member.
GET	/api/enterprise	License / entitlement status.
POST	/api/enterprise/license	Activate a license key.
DELETE	/api/enterprise/license	Deactivate the license.
PUT	/api/enterprise/database	Set the central database URL.
PUT	/api/enterprise/retention	Set audit-log retention.

Live updates

The WebSocket

GET /api/ws upgrades to a one-way server→client stream. Every frame is a JSON object { "type": …, …payload } — the same feed the console uses for its live counters and logs.

Event type	Meaning
entity_changed	A collection changed ({ entity: name }) — refetch it.
stats	Forwarding-rule connection/byte counters (every 3 s).
disruption	A disruption scenario activated / deactivated.
mock_log	A mock server handled a request.
mockdb_log	A mock database executed a statement.
access_log	A forward/echo access-log entry.
load_sample	One sampled response during a load run.
load_stats	Live load-run stats (every 2 s).
load_started	A load run started ({ request_id }).
load_stopped	A load run was stopped.
load_finished	A load run finished.

Prefer not to script HTTP at all? The install guide covers the jb CLI, which runs the same engines straight from a config file or the server's database.