Management API Guide

1. Base path and authentication

Default base path: /api/v1 (configurable via buzen.esb.management.base-path).

Authenticate with credentials and use bearer access token:

BASE_URL="${BUZEN_ESB_BASE_URL:-https://your-esb-host:8443/api/v1}"
TOKEN=$(curl -ksS -X POST "${BASE_URL}/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin"}' | jq -r '.data.accessToken')

curl -ksS "${BASE_URL}/auth/session" \
  -H "Authorization: Bearer ${TOKEN}" | jq .

OpenAPI endpoints:

• /api-docs
• /swagger-ui.html

2. Response envelope

Most endpoints return an ApiResponse<T> envelope:

{
  "success": true,
  "message": "optional",
  "data": {},
  "timestamp": "2026-02-23T00:00:00Z",
  "error": null
}

Error pattern:

{
  "success": false,
  "error": "Short error",
  "message": "Operator-readable detail",
  "timestamp": "..."
}

3. Role authorization matrix

Method-level authorization can narrow path-level rules for specific endpoints.

4. Endpoint catalog by group

Auth

• GET /auth/session
• POST /auth/login
• POST /auth/logout
• POST /auth/change-password

Apps and Route Content

• GET /apps, GET /apps/{appId}, GET /apps/{appId}/export
• POST /apps (multipart deploy), POST /apps (JSON create shell)
• DELETE /apps/{appId} (undeploy app, supports optional force=true)
• POST /apps/{appId}/start, POST /apps/{appId}/stop, POST /apps/{appId}/redeploy
• GET /apps/{appId}/routes
• GET /apps/{appId}/routes/{routeId}/content
• POST /apps/{appId}/routes
• PUT /apps/{appId}/routes/{routeId}/content
• DELETE /apps/{appId}/routes/{routeId}
• POST /apps/{appId}/routes/{routeId}/duplicate
• GET /apps/{appId}/routes/{routeId}/duplicate/capabilities
• GET /apps/stats, GET /apps/history, GET /apps/{appId}/history
• GET /apps/{appId}/versions, GET /apps/{appId}/versions/{version}, POST /apps/{appId}/rollback

Route Runtime

• GET /routes, GET /routes/{routeId}, GET /routes/stats
• POST /routes/{routeId}/start|stop|suspend|resume

System and Backup

• GET /system/info, GET /system/health, GET /system/version
• POST /system/restart, POST /system/shutdown
• GET /system/backup, POST /system/backup/restore, GET /system/backup/restore-status

Metrics, Logs, Traces

• GET /metrics, /metrics/cpu, /metrics/memory, /metrics/routes, /metrics/throughput, /metrics/errors, /metrics/route/{routeId}
• GET /logs, /logs/tail, /logs/stream, /logs/route/{routeId}, /logs/info
• GET /traces, /traces/recent, /traces/{traceId}, /traces/exchange/{exchangeId}, /traces/correlation/{correlationId}, /traces/route/{routeId}, /traces/route/{routeId}/stats, DELETE /traces

Policies

• Platform: /policies/platform*
• App scope: /apps/{appId}/policies*
• Route scope: /routes/{routeId}/policies*
• Views: GET /policies, /policies/stats, /policies/types, /policies/apps, /policies/routes

Users, Variables, Data Sources, Connectors

• /users* CRUD + reset password + toggle + unlock
• /variables* CRUD
• /data-sources* CRUD + test
• /connectors* list/details/test/config/stats

Alerts, Templates, Debug, Telemetry

• Alerts: /alerts/rules*, /alerts/active*, /alerts/history*, POST /alerts/{id}/acknowledge, GET /alerts/summary
• Templates: GET /templates, GET /templates/categories, GET /templates/{templateId}, POST /templates/render|validate|deploy, CRUD template endpoints
• Debug sessions: /debug/sessions*, tracing toggle, breakpoints, step/resume, route definition, debug config
• Flow telemetry: POST /telemetry/flow-designer/events, GET /telemetry/flow-designer/summary

5. Automation workflows

Deploy archive and verify

BASE_URL="${BUZEN_ESB_BASE_URL:-https://your-esb-host:8443/api/v1}"
curl -ksS -X POST "${BASE_URL}/apps" \
  -H "Authorization: Bearer ${TOKEN}" \
  -F "file=@my-app.bar" | jq .

curl -ksS "${BASE_URL}/apps" \
  -H "Authorization: Bearer ${TOKEN}" | jq .

curl -ksS "${BASE_URL}/routes" \
  -H "Authorization: Bearer ${TOKEN}" | jq .

Create empty app shell (JSON)

CreateAppRequest fields: name (required), description (optional).

{
  "name": "my-app",
  "description": "Empty shell for incremental route authoring"
}

curl -ksS -X POST "${BASE_URL}/apps" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H 'Content-Type: application/json' \
  -d @create-app.json | jq .

The generated manifest version defaults to 1.0.0 unless later updated through archive/version workflows.

Create or update app route content

curl -ksS -X POST "${BASE_URL}/apps/my-app/routes" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H 'Content-Type: application/json' \
  -d @route-upsert.json | jq .

Duplicate route with ingress awareness

curl -ksS "${BASE_URL}/apps/my-app/routes/orders-api/duplicate/capabilities" \
  -H "Authorization: Bearer ${TOKEN}" | jq .

curl -ksS -X POST "${BASE_URL}/apps/my-app/routes/orders-api/duplicate" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H 'Content-Type: application/json' \
  -d @duplicate-request.json | jq .

Undeploy app

curl -ksS -X DELETE "${BASE_URL}/apps/my-app?force=false" \
  -H "Authorization: Bearer ${TOKEN}" | jq .

6. Source-synced contracts for bots and CI

For deterministic automation, use source-synced artifacts before site-maintained profile schemas.

• source-snapshot.json (commit, version, extraction metadata)
• management-endpoints.json (controller-derived endpoint inventory)
• Runtime OpenAPI: /api-docs and /swagger-ui.html
• Compatibility profile: app-route-upsert-request.schema.json
• Compatibility profile: app-route-duplicate-request.schema.json
• Compatibility profile: buzen-archive-manifest.schema.json
• Compatibility profile: buzen-flow-designer-route.schema.json

7. Error handling strategy

• 400: payload defects, fix and retry
• 401: re-authenticate
• 403: insufficient role
• 404: wrong app/route keying
• 409: conflict (route ID or ingress), resolve then retry
• 500: transient or internal fault, retry with bounded backoff