Skip to main content
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

1

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"}
2

Register it in aegra.json

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

Start the server

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

​
Route priority

Custom routes follow this priority order:
PriorityRoutesBehavior
1/health, /ready, /live, /docs, /openapi.jsonAlways accessible, cannot be overridden
2Your custom routesTake precedence over shadowable routes
3/, /infoCan be overridden by custom routes
4/assistants, /threads, /runs, /storeCore 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
  }
}

​
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_credentials": true
    }
  }
}
The default is allow_origins: ["*"] with allow_credentials: false. When you specify concrete origins, allow_credentials defaults to true automatically. You can always set allow_credentials explicitly to override the default.

​
Configuration reference

OptionTypeDefaultDescription
http.appstringNoneImport path to custom FastAPI app (./file.py:variable)
http.enable_custom_route_authboolfalseApply Aegra auth to all custom routes
http.cors.allow_originslist[str]["*"]Allowed CORS origins
http.cors.allow_credentialsboolfalse when origins is ["*"], true otherwiseAllow credentials in CORS requests