Management API

The management API lets operators inspect and change Wanaku at runtime. It listens on port 8080 by default. Set WANAKU_MGMT_LISTEN to use a different address.

The server uses Pingora's ServeHttp trait. Core routes run first. Feature routes run after core routes.

Access and Response Format

Wanaku does not apply built-in authentication or rate limits to the management API. Restrict access to port 8080. In production, put the API behind an authenticated reverse proxy and apply a rate limit there.

Most JSON responses use this envelope:

{
  "data": {
    "name": "example"
  },
  "error": null
}

For an error, data is null and error contains a message:

{
  "data": null,
  "error": "Tool 'unknown-tool' not found"
}

The data value can be an object, an array, or null. This envelope keeps the API compatible with the classic Wanaku CLI.

Service and Core Routes

Method	Path	Purpose
GET	/health	Get the server health.
GET	/healthz	Get the server health.
GET	/openapi.json	Get the OpenAPI document.
GET	/api/v1/management/info	Get the server name and version.
GET	/api/v1/management/statistics	Get registry counts.
GET	/api/v1/tools	List tools.
GET	/api/v1/tools/{name}	Get a tool.
PUT	/api/v1/tools/{name}	Replace a tool entry with the JSON request body.
DELETE	/api/v1/tools/{name}	Delete a tool.
GET	/api/v1/resources	List resources.
GET	/api/v1/resources/{name}	Get a resource.
PUT	/api/v1/resources/{name}	Replace a resource entry with the JSON request body.
DELETE	/api/v1/resources/{name}	Delete a resource.
GET	/api/v1/prompts	List prompts.
GET	/api/v1/prompts/{name}	Get a prompt.
DELETE	/api/v1/prompts/{name}	Delete a prompt.
GET	/api/v1/namespaces	List namespaces.
GET	/api/v1/namespaces/{name}	Get a namespace.
POST	/api/v1/namespaces	Create a namespace from the JSON request body.
PUT	/api/v1/namespaces/{name}	Replace a namespace entry with the JSON request body.
DELETE	/api/v1/namespaces/{name}	Delete a namespace.
GET	/api/v1/forwards	List forwards.
GET	/api/v1/forwards/{name}	Get a forward.
POST	/api/v1/forwards	Create a forward and run upstream discovery.
DELETE	/api/v1/forwards/{name}	Delete a forward and its discovered entries.
POST	/api/v1/forwards/{name}/refreshes	Run upstream discovery again.

Wanaku discovers tools, resources, and prompts when you create or refresh a forward. The API does not have create routes for these entries. The PUT routes let you change existing tool and resource metadata.

Create a Namespace

Send one request:

curl -X POST http://localhost:8080/api/v1/namespaces \
  -H 'Content-Type: application/json' \
  -d '{"name":"finance"}'

Namespace names can contain lowercase letters, numbers, and hyphens. They cannot start or end with a hyphen. The maximum length is 63 characters.

Create a Forward

Include the namespace in the request:

curl -X POST http://localhost:8080/api/v1/forwards \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "upstream-mcp",
    "address": "http://upstream-server:8080/mcp",
    "namespace": "finance"
  }'

Wanaku stores the forward even if discovery fails. In that case, the response reports zero discovered entries and the forward records the error in status_message.

Feature Routes

Metrics

Method	Path	Purpose
GET	/api/v1/metrics	Get filter, evaluator, LLM, WASM, and pipeline metrics.

Interactions

Method	Path	Purpose
GET	/api/v1/interactions	List recorded interactions.
DELETE	/api/v1/interactions	Clear recorded interactions.

The evaluator uses these interactions as conversation history.

Evaluators

Method	Path	Purpose
GET	/api/v1/evaluators	List evaluator definitions.
PUT	/api/v1/evaluators	Replace evaluator definitions. The body uses the evaluators configuration schema.
GET	/api/v1/evaluators/namespaces	List namespace-to-conversation bindings.
PUT	/api/v1/evaluators/namespaces/{namespace}	Bind a namespace to a conversation.
DELETE	/api/v1/evaluators/namespaces/{namespace}	Remove a namespace binding.

Use this body to bind a namespace:

{
  "conversation_id": "conversation-123"
}

See Evaluator Engine for the evaluator configuration schema.

Chat

Method	Path	Purpose
GET	/api/v1/chat/llms	List configured LLM backends.
GET	/api/v1/chat/{llm}/models	List models from an LLM backend.
POST	/api/v1/chat/completions	Send a chat-completion request to the configured inference upstream.

The completion request uses the OpenAI chat-completions shape:

{
  "model": "llama3.1:8b",
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ]
}

Wanaku sends this request to WANAKU_INFERENCE_UPSTREAM/v1/chat/completions.

OAuth Metadata

When you set WANAKU_AUTH_ISSUER, the MCP metadata feature exposes OAuth Protected Resource Metadata:

GET /.well-known/oauth-protected-resource/{namespace}/mcp

MCP clients use this document to find the authorization server. An external authentication proxy enforces access to the MCP endpoint. See Authentication.

Web UI Plugins

Method	Path	Purpose
GET	/api/v1/plugins	List discovered UI plugin manifests.
GET	/plugins/{pluginId}/{path}	Get a static plugin file.
Any HTTP method	/api/plugins/{pluginId}/{serviceId}/{path}	Send a request through a configured plugin service mapping.

The plugin proxy accepts only plugin and service IDs that Wanaku loaded from configuration. It forwards the request method, body, query, and selected headers to the configured service. See Plugin Development Guide.

Persistence

Wanaku enables file persistence by default. It writes registry snapshots to $HOME/.wanaku/server when the process shuts down in an orderly manner.

Set WANAKU_PERSIST_BACKEND=none to disable persistence. Set WANAKU_PERSIST_PATH to use a different directory.

File persistence supports one writer. Do not run multiple replicas against the same persistence directory.

Status Codes

The API uses these status codes:

• 200 OK: The request succeeded. Core delete routes return a JSON confirmation in the standard envelope.
• 400 Bad Request: The request body is missing or invalid.
• 404 Not Found: The route or requested entry does not exist.
• 500 Internal Server Error: The server could not complete the request.

Plugin file and proxy routes can return other status codes from file handling or the upstream service.

CORS

The management API sets Access-Control-Allow-Origin from WANAKU_CORS_ORIGIN. The default value is *.

Set a specific origin in production:

export WANAKU_CORS_ORIGIN=https://app.example.com

The MCP endpoint on port 8081 uses the pipeline CORS filter.

Related Docs

• Architecture — See how the management API fits into the server.
• Configuration — Configure the listen address, persistence, and CORS.
• Features — Add management routes through the feature system.
• Authentication — Put the management API behind oauth2-proxy.