Custom routes

Aegra lets you mount a custom FastAPI app alongside the core Agent Protocol endpoints. Use this for webhooks, admin panels, health dashboards, or any other HTTP endpoints your application needs.

Setup

Create a FastAPI app

# custom_routes.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/custom/hello")
async def hello():
    return {"message": "Hello from custom route!"}

@app.post("/custom/webhook")
async def webhook(data: dict):
    return {"received": data, "status": "processed"}

{
  "graphs": {
    "agent": "./src/agent/graph.py:graph"
  },
  "http": {
    "app": "./custom_routes.py:app"
  }
}

Start the server

aegra dev

Your custom routes are now available alongside the Agent Protocol API.

Route priority

Custom routes follow this priority order:

Priority	Routes	Behavior
1	`/health`, `/ready`, `/live`, `/docs`, `/openapi.json`	Always accessible, cannot be overridden
2	Your custom routes	Take precedence over shadowable routes
3	`/`, `/info`	Can be overridden by custom routes
4	`/assistants`, `/threads`, `/runs`, `/store`	Core Agent Protocol routes, cannot be overridden

You can override the root route / and /info, but you cannot override the Agent Protocol endpoints or health checks.

# This works — overrides the default root
@app.get("/")
async def custom_root():
    return {"message": "Custom Aegra Server", "custom": True}

Authentication on custom routes

By default, custom routes do not have Aegra’s authentication applied. You have two options:

Option 1: Apply auth to all custom routes

Set enable_custom_route_auth in your config:

{
  "http": {
    "app": "./custom_routes.py:app",
    "enable_custom_route_auth": true
  }
}

A request without valid credentials then gets 401 on every FastAPI HTTP route your app declares, including routes from included routers and from mounted FastAPI sub-apps. Auth runs before any other dependency on those routes, including app-level and router-level ones. Aegra’s own routes are not affected: /health, /live, /ready, /info and the docs pages stay public, and the Agent Protocol routes keep their usual auth. Aegra’s default / stays public too. If your app declares its own /, that is a custom route, and this setting protects it. This setting does not cover:

Websocket routes. Authentication here runs on the HTTP request, so websocket connections pass through. Authenticate them inside the handler.
Plain Starlette routes added with app.add_route, and mounted non-FastAPI apps such as StaticFiles. These take no FastAPI dependency.

Aegra logs a startup warning that lists any of these it finds.

Option 2: Apply auth to specific routes

Use the require_auth dependency on individual routes:

from fastapi import Depends
from aegra_api.core.auth_deps import require_auth
from aegra_api.models.auth import User

@app.get("/custom/whoami")
async def whoami(user: User = Depends(require_auth)):
    return {
        "identity": user.identity,
        "display_name": user.display_name,
    }

@app.get("/custom/public")
async def public():
    # No auth required
    return {"message": "Public endpoint"}

CORS configuration

Configure CORS for your custom routes in aegra.json:

{
  "http": {
    "app": "./custom_routes.py:app",
    "cors": {
      "allow_origins": ["https://myapp.com"],
      "allow_origin_regex": "^https://[a-z0-9-]+\\.myapp\\.com$",
      "allow_credentials": true
    }
  }
}

Without allow_origin_regex, the default is allow_origins: ["*"] with allow_credentials: false. When you specify concrete origins and no regex, allow_credentials defaults to true automatically. When allow_origin_regex is non-null, allow_credentials defaults to false, and if allow_origins is omitted, it defaults to []. An explicit origin list and regex are combined, while an explicit "*" remains a wildcard. You can always set allow_credentials explicitly to override the default. The regex is passed to Starlette and matched against the complete origin. Note: the allow_credentials default only recognizes an exact ["*"] or "*". A wildcard mixed with other concrete origins (e.g. ["*", "https://example.com"]) currently still defaults allow_credentials to true, even though Starlette treats that list as allow-all — tracked in #633. Set allow_credentials explicitly if you use a mixed list.

Configuration reference

Option	Type	Default	Description
`http.app`	`string`	`None`	Import path to custom FastAPI app (`./file.py:variable`)
`http.enable_custom_route_auth`	`bool`	`false`	Require Aegra auth on every FastAPI route in the custom app
`http.cors.allow_origins`	`list[str]`	`["*"]` (`[]` if `allow_origin_regex` is set)	Allowed CORS origins
`http.cors.allow_origin_regex`	`string`	`None`	Regular expression for additional allowed origins; when present without `allow_origins`, the origin-list default is `[]`
`http.cors.allow_credentials`	`bool`	`false` with a regex or wildcard origins, `true` with concrete origins and no regex	Allow credentials in CORS requests

Getting started

Core concepts

Data & storage

Configuration

Contributing

Reference

Custom routes

Setup

Route priority

Authentication on custom routes

Option 1: Apply auth to all custom routes

Option 2: Apply auth to specific routes

CORS configuration

Configuration reference

​Setup

​Route priority

​Authentication on custom routes

​Option 1: Apply auth to all custom routes

​Option 2: Apply auth to specific routes

​CORS configuration

​Configuration reference

Setup

Route priority

Authentication on custom routes

Option 1: Apply auth to all custom routes

Option 2: Apply auth to specific routes

CORS configuration

Configuration reference