AURA Web Server Reference

Active development — APIs and configuration may change between releases as AURA evolves. Issues and feature requests are welcome — we’d love your feedback.

Part of the AURA Project - A production-ready framework for building AI agents with declarative TOML configuration.

OpenAI-compatible web API server that exposes AURA agents through a standard chat completions endpoint.

When to run the server

The CLI starts an agent per terminal session, which suits interactive work. Running aura webserver instead keeps agents resident behind an HTTP API, so a caller that isn’t a person at a keyboard can start a run: an alert pipeline reacting to a firing monitor, a scheduled job, a CI step, or a chat client such as LibreChat or OpenWebUI. Requests arrive as OpenAI chat completions, so any system that already speaks that format can call AURA directly. The server exposes no alert-specific receiver, so a monitoring tool that posts its own schema (Alertmanager and PagerDuty webhooks, for example) needs a small adapter to translate its payload into a chat completion request. Long-running investigations can stream progress back over SSE; see the Streaming API Guide.

Features

OpenAI Compatible: Implements /v1/chat/completions endpoint following OpenAI’s API schema
Multi-Turn Conversations: Maintains conversation context across requests
Full Tool Integration: Supports all MCP transports (HTTP, SSE, STDIO) and client-side tool passthrough
Health Monitoring: /health endpoint for container health checks
Production Ready: Stateless processing with pre-built agent, Docker-ready

Quick Start

# Build
cargo build --release --bin aura

# Start with default config (config.toml)
cargo run --bin aura -- webserver

# Or with custom configuration file
CONFIG_PATH=my-config.toml cargo run --bin aura -- webserver

# Or with a directory of configs (serves multiple agents)
CONFIG_PATH=configs/ cargo run --bin aura -- webserver

# Custom host/port
HOST=0.0.0.0 PORT=3000 cargo run --bin aura -- webserver

API Endpoints

Health Check

GET /health

Response:

{"status": "healthy"}

List Models (Agents)

GET /v1/models

Returns all loaded agents. Each agent’s alias (or name if no alias is set) is its model id. The owned_by field defaults to the underlying LLM provider (e.g. "openai", "anthropic") and can be overridden with model_owner in the agent config. Clients like LibreChat and OpenWebUI use this endpoint to populate their model picker. Each entry can also carry a description, a human-readable summary sourced from the agent’s [agent].description config (see the configuration reference). This extends the OpenAI model object. The key is omitted when [agent].description is unset, so strict OpenAI clients can ignore it. The /aura/info endpoint reports this same per-agent description; both read the agent’s [agent].description config value rather than computing it independently. /v1/models alone is enough to populate a model picker in an OpenAI-compatible client. Response:

{
  "object": "list",
  "data": [
    {"id": "devops", "object": "model", "created": 1677649963, "owned_by": "mezmo", "description": "General-purpose assistant with tool access"},
    {"id": "research-assistant", "object": "model", "created": 1677649963, "owned_by": "mezmo"}
  ]
}

Chat Completions

POST /v1/chat/completions
Content-Type: application/json

The model field selects which agent handles the request by matching against agent alias or name. Agent selection follows this order:

If only one config is loaded, it is always used (the model field is ignored)
Otherwise, model is matched first, then DEFAULT_AGENT if model is absent
Returns a 400 error if multiple configs are loaded and neither model nor DEFAULT_AGENT is supplied at all
Returns a 404 error if a model or DEFAULT_AGENT value is supplied but matches no loaded config

Request body:

{
  "model": "devops",
  "messages": [
    {"role": "user", "content": "What tools do you have available?"}
  ]
}

Response:

{
  "id": "chatcmpl-1865d39015e49520",
  "object": "chat.completion",
  "created": 1758043845,
  "model": "openai/gpt-4o-mini",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "I have the following tools available:\n\n1. **Log Analysis**: Export logs, analyze for root causes, and apply time-based filtering.\n2. **Knowledge Base**: Search AWS Bedrock knowledge bases for documentation and procedures.\n3. **Current Time**: Get the current timestamp for time-based operations.\n4. **Pipeline Management**: List and analyze Mezmo pipelines.\n5. **Filesystem**: Read configuration files and logs when needed."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 118,
    "total_tokens": 160
  }
}

Testing with curl

# Health check
curl -X GET http://127.0.0.1:8080/health

# List available agents
curl http://127.0.0.1:8080/v1/models

# Chat completion (uses DEFAULT_AGENT when model is omitted)
curl -X POST http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What tools do you have available?"}
    ]
  }'

# Chat completion with a specific agent
curl -X POST http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "devops",
    "messages": [
      {"role": "user", "content": "What tools do you have available?"}
    ]
  }'

Configuration

The server uses the AURA TOML configuration system. See the configuration reference for:

LLM provider configuration (OpenAI, Anthropic, Bedrock, Gemini, Ollama, OpenRouter)
MCP server setup (HTTP, SSE, STDIO)
Vector store and RAG integration
Agent settings and prompts

Example configurations are in the examples/ directory — see Example Configs.

Architecture

Multi-Agent Serving: Load multiple agents from a config directory, selectable via the model field
Stateless Requests: Each HTTP request is processed independently
Multi-Turn Support: Conversation history passed via messages array
OpenAI Compatible: Request/response schemas match OpenAI’s format
Error Handling: Proper HTTP status codes and error responses

Deployment

Environment Variables:

Variable	Default	Description
`CONFIG_PATH`	`config.toml`	Path to a config file or directory of configs
`HOST`	`127.0.0.1`	Server bind address
`PORT`	`8080`	Server port
`AURA_ENABLE_A2A`	`false`	Enable A2A protocol endpoints (`/a2a/v1/*`, `/.well-known/agent-card.json`). Disabled by default — see A2A Integration
`AURA_SERVER_URL`	host/port	Canonical public origin published in the A2A agent card. Set when running behind a proxy, load balancer, or in Kubernetes — see A2A Integration
`DEFAULT_AGENT`	(none)	Agent name or alias used when `model` is omitted. Not needed when only one config is loaded.
`AURA_CUSTOM_EVENTS`	`false`	Emit `aura.*` SSE events alongside OpenAI-compatible chunks
`AURA_EMIT_REASONING`	`false`	Emit `aura.reasoning` events (requires `AURA_CUSTOM_EVENTS=true`)
`TOOL_RESULT_MODE`	`none`	How tool results are streamed: `none`, `open-web-ui`, or `aura`
`TOOL_RESULT_MAX_LENGTH`	`1000`	Truncation limit for streamed tool results (0 = no truncation)
`STREAMING_TIMEOUT_SECS`	`900`	Max duration for a streaming request before cancellation
`FIRST_CHUNK_TIMEOUT_SECS`	`90`	Max wait for the first LLM chunk before treating the connection as hung (0 = disabled)
`STREAM_INACTIVITY_TIMEOUT_SECS`	`0`	Max silence between stream items after the first chunk before the server fails the streaming request (0 = disabled). Applies to single-agent streaming; tool execution is exempt. For orchestrated deployments, use the TOML `stream_inactivity_timeout_secs` instead. See request lifecycle for tuning guidance, and the configuration reference for the TOML field.
`SHUTDOWN_TIMEOUT_SECS`	`30`	Grace period for in-flight streams after SIGTERM/SIGINT
`STREAMING_BUFFER_SIZE`	`400`	SSE chunk buffer size; higher values reduce latency but increase memory use
`AURA_DEBUG_PROVIDER_ERRORS`	`false`	Dev only. Surface raw upstream provider errors to clients (capped). Keep off when public-facing — error bodies can echo request content. Raw error is always in logs/OTel.

Getting Started

Configuration

Features

CLI Reference

Web Server Reference

AURA Web Server Reference

When to run the server

Features

Quick Start

API Endpoints

Health Check

List Models (Agents)

Chat Completions

Testing with curl

Configuration

Architecture

Deployment

See Also

​When to run the server

​Features

​Quick Start

​API Endpoints

​Health Check

​List Models (Agents)

​Chat Completions

​Testing with curl

​Configuration

​Architecture

​Deployment

​See Also

When to run the server

Features

Quick Start

API Endpoints

Health Check

List Models (Agents)

Chat Completions

Testing with curl

Configuration

Architecture

Deployment

See Also