Skip to main content

REST API Overview

YedMQ exposes a management REST API for automation, diagnostics, and cluster operations.

Canonical reference​

The generated Management API Reference is the canonical endpoint reference. This page summarizes authentication, API shape, and common patterns.

Base path​

All current endpoints are served under /api/v1.

Authentication​

The management API uses HTTP Basic Authentication configured in yedmq.toml.

The shipped example config binds the API to 127.0.0.1 and starts with users = [], so you need to add at least one user before calling the API:

[listener.api.auth]
users = [{ username = "admin", password = "replace_me" }]

Example request:

curl -u admin:replace_me \
  http://127.0.0.1:3456/api/v1/plugins

The built-in CLI status commands use the same Admin API and credentials:

export YEDMQ_API_USER=admin
export YEDMQ_API_PASSWORD=replace_me

yedmq node status
yedmq cluster status
yedmq broker stats

Main endpoint groups​

  • System and plugins:
    • GET /api/v1/system_info
    • GET /api/v1/node/status
    • GET /api/v1/broker/stats
    • GET /api/v1/plugins
    • POST /api/v1/plugins/rescan
    • GET /api/v1/plugins/{plugin_name}
    • POST /api/v1/plugins/{plugin_name}/start
    • POST /api/v1/plugins/{plugin_name}/stop
    • POST /api/v1/plugins/{plugin_name}/restart
    • GET /api/v1/plugins/{plugin_name}/logs
  • Tenant-scoped operations:
    • GET /api/v1/{tenant_id}/clients
    • GET /api/v1/{tenant_id}/topics
    • GET /api/v1/{tenant_id}/messages/retained
    • POST /api/v1/{tenant_id}/messages
    • POST /api/v1/{tenant_id}/clients/{client_id}/kickoff
  • Cluster management:
    • GET /api/v1/cluster/metrics
    • GET /api/v1/cluster/ready
    • GET /api/v1/cluster/status
    • POST /api/v1/cluster/learners
    • POST /api/v1/cluster/nodes
    • POST /api/v1/cluster/topic/learners
    • POST /api/v1/cluster/session_actor_map/learners
    • POST /api/v1/cluster/session_state/learners
    • POST /api/v1/cluster/membership
    • per-raft init and membership endpoints

Pagination​

List endpoints may expose offset and limit query parameters. When pagination applies, the response includes a meta object describing the current window.

Plugin workflow​

  • Use POST /api/v1/plugins/rescan after adding, removing, or editing plugin directories on disk.
  • rescan only updates discovery data. It does not start, stop, or restart plugin processes for you.
  • Use POST /api/v1/plugins/{plugin_name}/restart to apply the latest manifest from disk to an existing plugin.
  • Use GET /api/v1/plugins?scope=all plus GET /api/v1/plugins/{plugin_name} when you need to compare discovered vs managed state before taking action.
  • Use GET /api/v1/plugins/{plugin_name}/logs?tail=100 for recent runtime diagnostics.

Cluster workflow​

  • Use GET /api/v1/cluster/ready in automation or health checks before adding nodes or routing traffic.
  • Use GET /api/v1/cluster/status when an operator or dashboard needs the cluster name, configured members, readiness, and per-raft-group status in one response.
  • Use POST /api/v1/cluster/nodes as the high-level join workflow when you want to add a node across all raft groups.
  • Use the per-raft .../learners and .../membership endpoints only when you need lower-level recovery or staged cluster operations.

Use the generated OpenAPI pages whenever you need:

  • request and response schemas
  • exact field names
  • example payloads
  • per-endpoint parameter lists