HTTP API and OpenAPI

Contract and entry points

Mobazha Node exposes versioned HTTP routes under /v1/ and WebSocket connections under /ws. The generated OpenAPI document describes request methods, paths, schemas, response envelopes, and declared authentication mechanisms for the reviewed source revision shown in the API Reference.

The specification is a release-candidate contract, not proof that every optional operation is enabled by a particular backend. Read /v1/runtime-config and capability endpoints before exposing optional UI or automation.

First capability call

A local Node publishes its frontend runtime snapshot without requiring an authenticated business operation. Use it to verify schema version, deployment composition, readiness, features, and capabilities before constructing optional UI or automation.

curl -sS http://127.0.0.1:5102/v1/runtime-config | jq

Expected result

The runtime call should return a successful JSON envelope describing the Node schema, deployment composition, readiness, and effective capabilities. Record the Node version and capability you intend to use. A missing or unavailable capability is a decision to stop or degrade the integration—not a reason to enable a frontend-only switch.

A default standalone store currently returns this representative projection when the response is narrowed to the composition fields. Capability and feature values vary by the connected Node and remain authoritative.

curl -fsS http://127.0.0.1:5102/v1/runtime-config |
  jq '.data | {schemaVersion, authMode, deployment, experience, capabilitiesReady}'

{
  "schemaVersion": 3,
  "authMode": "standalone",
  "deployment": {
    "mode": "standalone",
    "allowExternalResources": true
  },
  "experience": {
    "kind": "store"
  },
  "capabilitiesReady": true
}

Authentication choices

• HTTP Basic authentication is available for the standalone administrator boundary.
• Bearer JWTs represent hosted identities where the deployment supports them.
• Scoped mbz_ API tokens are the preferred automation credential for supported standalone integrations.
• Choose the narrowest credential and scope set, store it outside source code, and rotate or revoke it after exposure.

Client requirements

• Choose the authentication mechanism required by the connected deployment; do not copy credentials into URLs or logs.
• Treat non-success responses and stable error codes as part of the state machine, not only as transport failures.
• Use idempotency and reconciliation for operations that may be retried or have financial effects.
• Pin integrations to a tested Node version and re-run contract tests before upgrades.
• Never infer support from an endpoint appearing in source or OpenAPI when the effective capability is absent.

Request and response workflow

BASE_URL=http://127.0.0.1:5102
curl -fsS "$BASE_URL/v1/runtime-config" | jq
curl -fsS -H "Authorization: Bearer $MBZ_API_TOKEN" "$BASE_URL/v1/webhooks" | jq

Inspect HTTP status before consuming the success envelope. Exact inner response schemas belong to the generated OpenAPI contract. Keep base URL, Node version, credential type, and expected capability explicit in client configuration.

Errors, retries, and compatibility

• Handle 401, 403, 404, 409, 429, and 5xx as distinct classes.
• Reconcile authoritative state after a timeout on an order, payment, refund, or settlement operation.
• Do not retry a financial mutation unless the endpoint contract provides idempotency or reconciliation.
• Test generated clients and hand-written integrations against the exact release tag before upgrades.