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:

json

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

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

json

{
  "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:

bash

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:

bash

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/llm-connections`	List configured LLM connection names only, never the model, URL, or credential. Connections are config-only. Set them in `wanaku.yaml`, not through this API.
`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.
`GET`	`/api/v1/evaluators/revisions`	List evaluator revision metadata.
`GET`	`/api/v1/evaluators/revisions/active`	Get the active evaluator revision.
`GET`	`/api/v1/evaluators/revisions/{id}`	Get one evaluator revision.
`POST`	`/api/v1/evaluators/revisions/{id}/activate`	Activate a prior evaluator configuration as a new revision.

Use this body to bind a namespace:

json

{
  "conversation_id": "conversation-123"
}

See Evaluator Engine for the evaluator configuration schema.

The OpenAPI document contains all evaluator request and response schemas. Run yarn run generate-api in ui/admin after you change an evaluator route or schema.

Action Policies

Method	Path	Purpose
`GET`	`/api/v1/action-policies`	Get the effective policy.
`PUT`	`/api/v1/action-policies`	Validate and activate a policy.
`GET`	`/api/v1/action-policies/revisions`	List policy revision metadata.
`GET`	`/api/v1/action-policies/revisions/active`	Get the active policy revision.
`GET`	`/api/v1/action-policies/revisions/{id}`	Get one policy revision.
`POST`	`/api/v1/action-policies/revisions/{id}/activate`	Activate a prior policy as a new revision.

The update and activation requests accept an optional expected_revision. Wanaku returns 409 Conflict if the value does not equal the active revision. See Action Policies for request examples and validation behavior.

The OpenAPI document contains all action-policy request and response schemas. Run yarn run generate-api in ui/admin after you change an action-policy route or schema.

Inference Proxy (not part of this API)

Chat completions do not go through the management API. Wanaku exposes a separate, raw reverse-proxy listener on port 8083 that forwards requests as-is to whatever OpenAI-compatible backend WANAKU_INFERENCE_UPSTREAM points at — including the caller's own Authorization header. The Admin UI's LLM Chat page calls this port directly with a key you supply in the browser:

bash

curl -X POST http://localhost:8083/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-key>" \
  -d '{
    "model": "llama3.1:8b",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

See Configuration for how to set the upstream.

OAuth Metadata

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

text

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:

bash

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

The MCP endpoint (port 8081) and the inference proxy (port 8083) each use their own pipeline CORS filter, set from the same WANAKU_CORS_ORIGIN value.

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.

Management API ​

Access and Response Format ​

Service and Core Routes ​

Create a Namespace ​

Create a Forward ​

Feature Routes ​

Metrics ​

Interactions ​

Evaluators ​

Action Policies ​

Inference Proxy (not part of this API) ​

OAuth Metadata ​

Web UI Plugins ​

Persistence ​

Status Codes ​

CORS ​

Related Docs ​

Management API

Access and Response Format

Service and Core Routes

Create a Namespace

Create a Forward

Feature Routes

Metrics

Interactions

Evaluators

Action Policies

Inference Proxy (not part of this API)

OAuth Metadata

Web UI Plugins

Persistence

Status Codes

CORS

Related Docs