> ## Documentation Index > Fetch the complete documentation index at: https://docs.mezmo.com/llms.txt > Use this file to discover all available pages before exploring further. # AURA Web Server Reference > OpenAI-compatible web API server that exposes AURA agents through a standard chat completions endpoint — endpoints, deployment env vars, and architecture. **Open Alpha** — AURA is under active development. APIs and configuration may change between releases. [Issues and feature requests](https://github.com/mezmo/aura/issues) are welcome — we'd love your feedback. **Part of the [AURA Project](https://github.com/mezmo/aura)** - 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. ## 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 ```bash theme={null} # Build the server cargo build --release --bin aura-web-server # Start with default config (config.toml) cargo run --bin aura-web-server # Or with custom configuration file CONFIG_PATH=my-config.toml cargo run --bin aura-web-server # Or with a directory of configs (serves multiple agents) CONFIG_PATH=configs/ cargo run --bin aura-web-server # Custom host/port HOST=0.0.0.0 PORT=3000 cargo run --bin aura-web-server ``` ## API Endpoints ### Health Check ```bash theme={null} GET /health ``` Response: ```json theme={null} {"status": "healthy"} ``` ### List Models (Agents) ```bash theme={null} 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. Response: ```json theme={null} { "object": "list", "data": [ {"id": "devops", "object": "model", "created": 1677649963, "owned_by": "mezmo"}, {"id": "research-assistant", "object": "model", "created": 1677649963, "owned_by": "mezmo"} ] } ``` ### Chat Completions ```bash theme={null} 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: 1. If only one config is loaded, it is always used (the `model` field is ignored) 2. Otherwise, `model` is matched first, then `DEFAULT_AGENT` if `model` is absent 3. Returns a 400 error if multiple configs are loaded and neither `model` nor `DEFAULT_AGENT` is supplied at all 4. Returns a 404 error if a `model` or `DEFAULT_AGENT` value is supplied but matches no loaded config Request body: ```json theme={null} { "model": "devops", "messages": [ {"role": "user", "content": "What tools do you have available?"} ] } ``` Response: ```json theme={null} { "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 ```bash theme={null} # 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](/aura/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/`](https://github.com/mezmo/aura/tree/main/examples) directory — see [Example Configs](/aura/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/a2a-implementation) | | `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](/aura/a2a-implementation#agent-card-url-aura_server_url) | | `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) | | `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. | ## See Also * [AURA on GitHub](https://github.com/mezmo/aura) — source, issues, and contributing