Reference

Controlled BetaVerification Required

Message Broker HTTP Reference

Source-backed reference for Message Broker health, stream, record, cursor, queue, replication, audit, metrics, auth, and storage administration HTTP routes.

Current availability

Private Beta. Public beta is scheduled for October 5, 2026.

Maturity Status

Runtime Routes

Controlled Beta

The routes below are implemented in the current broker route classifier and handler modules, with local smoke coverage for the main stream, queue, and inspection workflows.

Review Boundary

Verification Required

Product, security, operations, and docs QA review still need to accept the route wording before this page is used for external commitments.

Reference Summary

ID	Type	Name	Method	Path	Maturity	Evidence
`smb-http-health`	api	Health readiness Public readiness route with storage, release, security, audit, and metrics exporter posture.	`GET`	`/health`	Controlled Beta	SMB-EVID-002, runtime_observability.rs
`smb-http-auth`	api	Runtime auth Classifies non-health routes before handlers run and maps them to tenant or stream permissions.	`mixed`	`all non-health routes`	Controlled Beta	SMB-EVID-002, runtime-authentication-middleware.md
`smb-http-stream-management`	api	Stream management Creates, lists, and describes tenant-visible runtime streams.	`PUT, GET`	`/v1/streams`	Controlled Beta	SMB-EVID-002, SMB-EVID-003, runtime_streams.rs
`smb-http-versioned-records`	api	Versioned records Publishes one native-shaped record or replays a bounded page by offset or time.	`POST, GET`	`/v1/streams/{stream}/records`	Controlled Beta	SMB-EVID-003, runtime_records.rs
`smb-http-cursors-and-inspection`	api	Cursors and inspection Inspects groups, cursors, leases, delayed retries, replay consumers, and audited cursor writes.	`GET, PUT, POST`	`/v1/streams/{stream}/consumer-groups/{group}`	Controlled Beta	SMB-EVID-003, runtime_cursors.rs, runtime_inspection.rs
`smb-http-shared-queue`	api	Shared queue Claims work, renews leases, acknowledges, nacks, retries, or dead-letters delivery state.	`POST`	`/claims and /deliveries/{delivery}/{action}`	Controlled Beta	SMB-EVID-004, runtime_queue.rs
`smb-http-replication`	api	Replication controls Inspects configured replication binding state and runs bounded worker control actions.	`GET, POST`	`/v1/replication/status and worker routes`	Controlled Beta	SMB-EVID-005, runtime_replication.rs
`smb-http-audit`	api	Audit query and export Reads parsed audit events or NDJSON exports from the reserved system audit stream.	`GET`	`/v1/audit/events, /v1/audit/export`	Controlled Beta	SMB-EVID-002, runtime_audit.rs
`smb-http-metrics`	api	Metrics scrape Returns text metrics when the broker starts with HTTP metrics exposure enabled.	`GET`	`/metrics`	Controlled Beta	SMB-EVID-002, runtime_observability.rs
`smb-http-storage-admin`	api	Storage admin Inspects catalog, retention, tiering readiness, archive manifests, and quarantine state.	`GET, POST`	`/streams/{stream} storage routes`	Controlled Beta	SMB-EVID-002, runtime_storage_admin.rs

Authentication Model

GET /health is public. Every other implemented route is protected in api-key, mtls, or external mode. The default insecure-local mode allows local protected requests without credentials and reports that posture in health.

Route family	Permission
GET /health	public readiness
GET /v1/audit/events and /v1/audit/export	tenant administer
GET /metrics and GET /v1/replication/status	tenant inspect
GET /v1/streams	tenant inspect
PUT /v1/streams/{stream}	create_stream
GET /v1/streams/{stream} and storage inspection routes	stream inspect
POST /v1/streams/{stream}/records	stream publish
GET /v1/streams/{stream}/records and queue routes	stream consume
Cursor commit and rewind routes	stream ack
Replication poll, pause, resume, and target apply	tenant administer

Streams And Records

Versioned stream and record routes
Route	Request	Response	Errors	Evidence
`PUT /v1/streams/{stream}`	JSON body with optional default_durability, retention, and failure_policy.	201 Created with stream, created flag, and acknowledgement.	400 invalid_request; 409 stream_already_exists; 500 internal_error.	runtime_streams.rs
`GET /v1/streams`	No query string or body.	200 OK with tenant-visible stream descriptions.	400 invalid_query.	runtime_streams.rs
`GET /v1/streams/{stream}`	No query string or body.	200 OK with one stream description.	400 invalid_request; 404 stream_not_found.	runtime_streams.rs
`POST /v1/streams/{stream}/records`	JSON record with message_id plus payload or payload_hex, optional key, event_time_ms, headers, and durability_mode.	201 Created with offset, next_offset, payload bytes, durability acknowledgement, and optional replication receipt.	400 invalid_request or invalid_payload; 429 quota_exceeded; 503 replication_unavailable; 500 internal_error.	runtime_records.rs
`GET /v1/streams/{stream}/records`	Optional start_offset, event_time_ms, or ingest_time_ms; max_records; max_payload_bytes; optional consumer_group plus consumer_id.	200 OK with records encoded as payload_hex and diagnostics for the read page.	400 invalid_start, invalid_page_size, or invalid_query; 404 stream_not_found; 500 internal_error.	runtime_records.rs

Cursors And Inspection

Cursor and consumer group inspection routes
Route	Request	Response	Errors	Evidence
`GET /v1/streams/{stream}/consumer-groups/{group}`	No body.	Payload-free group description with cursors, in-flight work, delayed retries, and lag.	400 invalid_request; 404 stream_not_found; 500 internal_error.	runtime_inspection.rs
`GET /v1/streams/{stream}/consumer-groups/{group}/leases`	Optional include_completed=true\|false.	Payload-free delivery lease entries.	400 invalid_query; 404 stream_not_found.	runtime_inspection.rs
`GET /v1/streams/{stream}/consumer-groups/{group}/delayed`	No body.	Payload-free delayed retry entries.	400 invalid_query; 404 stream_not_found.	runtime_inspection.rs
`GET /v1/streams/{stream}/consumer-groups/{group}/replay-consumers`	No body; populated by fetch requests that include consumer_group and consumer_id.	Payload-free replay consumer activity observations.	400 invalid_query; 404 stream_not_found.	runtime_inspection.rs
`GET /v1/streams/{stream}/consumer-groups/{group}/cursors`	No body.	Cursor count and cursor state entries.	400 invalid_query; 404 stream_not_found.	runtime_inspection.rs
`PUT /v1/streams/{stream}/consumer-groups/{group}/cursors/{cursor}`	JSON body with offset.	Cursor commit acknowledgement.	400 invalid_request; 409 write_not_allowed; 500 internal_error.	runtime_cursors.rs
`POST /v1/streams/{stream}/consumer-groups/{group}/cursors/{cursor}/rewind`	JSON body with offset and non-empty reason.	Cursor rewind response and audit evidence.	400 invalid_request; 409 write_not_allowed; 500 internal_error.	runtime_cursors.rs

Shared Queue

Shared queue claim and delivery mutation routes
Route	Request	Response	Errors	Evidence
`POST /v1/streams/{stream}/consumer-groups/{group}/claims`	Optional start_offset, max_messages, and lease_timeout_millis.	Claim result with subscription id, deliveries, next_offset, and delivery_count.	400 invalid_request; 404 missing_stream; 429 quota_exceeded; 500 queue_state_persistence_failed.	runtime_queue.rs
`POST /v1/streams/{stream}/subscriptions/{subscription}/deliveries/{delivery}/ack`	Optional empty JSON object.	Acknowledged offset, attempt, timestamp, and local queue-state acknowledgement.	404 delivery_not_found; 409 lease_expired or lease_not_active.	runtime_queue.rs
`POST /v1/streams/{stream}/subscriptions/{subscription}/deliveries/{delivery}/nack`	reason and requeue.	Policy action, redelivery decision, optional retry time, and optional dead-letter target.	400 invalid_request; 404 delivery_not_found; 409 lease_expired or lease_not_active.	runtime_queue.rs
`POST /v1/streams/{stream}/subscriptions/{subscription}/deliveries/{delivery}/renew`	Positive extend_by_millis.	Renewed lease body.	400 invalid_request; 404 delivery_not_found; 409 lease_expired or lease_not_active.	runtime_queue.rs
`POST /v1/streams/{stream}/subscriptions/{subscription}/deliveries/{delivery}/retry`	reason and delay_millis.	Retry availability timestamp.	400 invalid_request; 404 delivery_not_found; 409 lease_expired or lease_not_active.	runtime_queue.rs
`POST /v1/streams/{stream}/subscriptions/{subscription}/deliveries/{delivery}/dead-letter`	dead_letter_stream and reason.	Source offset and dead-letter offset.	400 invalid_request; 404 missing_stream or delivery_not_found; 409 lease conflict.	runtime_queue.rs

Replication

Replication status, worker, and target apply routes
Route	Request	Response	Errors	Evidence
`GET /v1/replication/status`	No query string or body.	Scheduler, transport, managed worker, checkpoint, target state, and operator controls.	400 invalid_query.	runtime_replication.rs
`POST /v1/replication/workers/poll`	Empty POST; requires runtime binding.	Bounded poll report and transport status.	400 invalid_payload; 409 replication_not_configured; runtime poll errors.	runtime_replication.rs
`POST /v1/replication/workers/pause`	stream, source_site, target_site, optional tenant, optional reason.	Paused control and operator control summary.	400 invalid_request; 404 replication_worker_not_found; 409 replication_not_configured.	runtime_replication.rs
`POST /v1/replication/workers/resume`	stream, source_site, target_site, optional tenant, optional reason.	Resumed control and operator control summary.	400 invalid_request; 404 replication_worker_not_found; 409 replication_not_configured.	runtime_replication.rs
`POST /v1/replication/target/apply`	Bounded source-record metadata batch with source/target sites and policy metadata.	Apply counts, next expected offset, target watermark, and newly applied origin offsets.	400, 409, 413, or 500 replica_apply errors.	runtime_replication.rs

Audit, Metrics, And Storage Admin

Operational and storage administration routes
Route	Request	Response	Errors	Evidence
`GET /v1/audit/events`	Optional start_offset and max_records.	JSON page of parsed audit event records.	400 invalid_request, invalid_query, invalid_start_offset, or invalid_page_size; 500 internal_error.	runtime_audit.rs
`GET /v1/audit/export`	Optional start_offset and max_records.	application/x-ndjson audit export.	400 invalid_request, invalid_query, invalid_start_offset, or invalid_page_size; 500 internal_error.	runtime_audit.rs
`GET /metrics`	No query or body; requires --metrics-exposure http.	text/plain metrics with OpenTelemetry names and Prometheus-safe aliases.	400 invalid_query; 404 metrics_disabled; auth errors in protected modes.	runtime_observability.rs
`GET /streams/{stream}/retention/dry-run`	Optional max_bytes and max_age_ms.	Non-mutating retention plan.	400 invalid_retention_policy or invalid_query; 404 missing_stream.	runtime_storage_admin.rs
`GET /streams/{stream}/tiering/readiness`	Optional max_bytes and max_age_ms.	Payload-free tiering readiness manifest.	400 invalid_tiering_policy or invalid_query; 404 missing_stream; 500 tiering_manifest_failed.	runtime_storage_admin.rs
`GET /streams/{stream}/tiering/archive-manifest`	Optional max_bytes and max_age_ms.	Archive-manifest JSON with storage-tiering content type.	400 invalid_tiering_policy or invalid_query; 404 missing_stream; 500 tiering_manifest_failed.	runtime_storage_admin.rs
`GET /streams/{stream}/quarantine`	No query or body.	Payload-free quarantine incident list.	400 invalid_query; 404 missing_stream; 500 quarantine storage errors.	runtime_storage_admin.rs
`POST /streams/{stream}/quarantine/{incident}/acknowledge`	Optional acknowledged_by and note.	Acknowledged quarantine incident.	400 invalid_request; 404 quarantine_not_found; 409 write_not_allowed; 500 quarantine storage errors.	runtime_storage_admin.rs

Limits

Limit	Value	Applies To
Default fetch page size	100 records	Versioned fetch, legacy fetch, audit events, audit export
Maximum fetch page size	1000 records	Versioned fetch, legacy fetch, audit events, audit export
Default queue claim count	1 message	Queue claim route
Maximum queue claim count	1000 messages	Queue claim route
Default queue lease timeout	30000 ms	Queue claim route
Replica apply records	1000 records	/v1/replication/target/apply
Replica apply payload bytes	64 MiB	/v1/replication/target/apply aggregate payload_bytes metadata
Route token shape	No slash, tab, or control chars	consumer group, cursor, subscription, and delivery path tokens
Metrics exposure	opt-in	--metrics-exposure http

Errors

Status	Error Code	Meaning	Recovery
`400`	invalid_request	Body, route token, offset, or route-specific validation failed.	Fix request fields and retry.
`400`	invalid_query	Query string is unsupported or malformed.	Remove or correct the query string.
`401`	authentication_required / authentication_failed	Protected route credentials are missing or invalid.	Supply configured credentials or use insecure-local intentionally.
`403`	authorization_denied	Authenticated caller lacks the required permission.	Check tenant, stream, role grants, and auth mode.
`404`	stream_not_found / missing_stream / not_found	Stream or route is not visible to the caller.	Create the stream, check tenant context, or use a documented route.
`409`	lease_expired / lease_not_active	Queue mutation targeted stale or terminal delivery state.	Claim work again or inspect queue state.
`409`	replication_not_configured	Replication worker action needs a binding file.	Start with --replication-binding-file.
`429`	quota_exceeded	Tenant quota rejected publish, queue, or replication egress work.	Reduce request rate or review quota configuration.
`503`	replication_unavailable	Required stream replication policy is not currently satisfied.	Inspect /v1/replication/status before retrying.
`500`	internal_error	Storage, registry, queue, audit, or replication state failed unexpectedly.	Check broker logs, storage permissions, and disk health.

Examples

Create And Publish

Stream

curl -s -X PUT -H 'Content-Type: application/json' \
  --data '{}' \
  http://127.0.0.1:9101/v1/streams/orders

curl -s -X POST -H 'Content-Type: application/json' \
  --data '{"message_id":"msg-1","payload":"hello","durability_mode":"local-append"}' \
  http://127.0.0.1:9101/v1/streams/orders/records

Replay And Inspect

Records

curl -s \
  'http://127.0.0.1:9101/v1/streams/orders/records?start_offset=0&max_records=10&consumer_group=workers&consumer_id=replay-1'

curl -s \
  http://127.0.0.1:9101/v1/streams/orders/consumer-groups/workers/replay-consumers

Claim And Ack

Queue

curl -s -X POST -H 'Content-Type: application/json' \
  --data '{"max_messages":1,"lease_timeout_millis":30000}' \
  http://127.0.0.1:9101/v1/streams/orders/consumer-groups/workers/claims

curl -s -X POST -H 'Content-Type: application/json' \
  --data '{}' \
  http://127.0.0.1:9101/v1/streams/orders/subscriptions/sub-1/deliveries/del-1/ack

Operate

Ops

curl -s http://127.0.0.1:9101/v1/replication/status
curl -s 'http://127.0.0.1:9101/v1/audit/events?start_offset=0&max_records=100'
curl -s http://127.0.0.1:9101/metrics
curl -s 'http://127.0.0.1:9101/streams/orders/tiering/readiness?max_age_ms=86400000'

Safe Next Steps

Available now
Run stream and queue quickstart
Create streams, publish records, replay data, claim queue work, ack results, and inspect controlled-beta limits.
Available now
Review Message Broker evidence
Use the evidence index before strengthening stream, queue, auth, replication, or pilot-readiness claims.
Available: DOCS-032
Read CLI and SDK reference
Lifecycle flags, diagnostics, data CLI, remote CLI, and Rust SDK publish and replay entry points.
Available: DOCS-040
Compare route and auth scope
Separate controlled-beta routes from auth, replication, queue, CLI, SDK, and Kafka protocol boundaries.