Skip to main content

Routes

A route publishes an HTTP or WebSocket API of your own through DIAL Core. Core matches a request's path and method to the route, authenticates and authorizes the caller, and proxies the request to the route's upstreams with load balancing. Clients such as DIAL Chat can then call the API with their DIAL credentials. This reference is for platform engineers who expose custom APIs; it assumes you know how DIAL Core is configured.

For when to use a route instead of an application or a toolset, see Custom APIs through routes.

Where routes are defined​

SourceLocation
Config fileroutes.<name>, for global routes
Configuration API/v1/routes/platform/<name>
An applicationapplications.<name>.routes, see Application routes

Routes are matched by their paths, not their names, so a file route and a blob route with the same name both stay in force. DIAL Admin manages routes in Routes.

Fields​

FieldDescription
pathsThe paths matched against the request path. A path can be a plain string or a regular expression. If any path matches, the route handles the request.
methodsThe HTTP methods the route accepts: GET, POST, PUT, DELETE, HEAD, or PATCH.
rewritePathWhen true, the upstream path is replaced with the path of the original request.
userRolesThe roles, from identity provider claims or API keys, that may call the route. When unset, every user may call it.
orderThe priority among global routes; a lower value wins. Cannot be negative. Default 2147483647.
upstreamsThe servers the route proxies to. See Upstreams. Set upstreams or response.
responseA fixed response Core returns at once, with status and body. Set upstreams or response.
maxRetryAttemptsThe maximum number of attempts when an upstream answers with an error; Core tries another available upstream. See Load balancing and upstreams.

Upstreams​

FieldDefaultDescription
endpoint—The backend URL: http://, https://, ws://, or wss://. Routes support HTTP and WebSocket.
key—The API key, token, or credential sent to the upstream.
authTypeAPI_KEYHow key is sent: API_KEY as API-KEY: <key>, or BEARER as Authorization: Bearer <key>, which OpenRouter requires, for example. BEARER requires key. Honored on global routes only.
weight1The upstream's share of traffic within its tier. 0 or below takes it out of routing.
tier0The priority group; the lowest value is used first.
extraData—Additional data passed to the upstream, as JSON or a string.

Upstream keys are encrypted at rest in the platform bucket and never returned by the Configuration API.

Example​

{
  "routes": {
    "vector_store_query": {
      "paths": ["/v1/vector_store(/[^/]+)*$"],
      "rewritePath": true,
      "methods": ["GET", "HEAD"],
      "userRoles": ["analyst"],
      "upstreams": [
        { "endpoint": "http://vector-store-1:9876" },
        { "endpoint": "http://vector-store-2:9876" }
      ],
      "maxRetryAttempts": 2
    },
    "rate": {
      "paths": ["/v1/rate"],
      "methods": ["GET", "HEAD"],
      "response": { "status": 200, "body": "OK" }
    },
    "openai-realtime": {
      "paths": ["/openai/realtime"],
      "rewritePath": true,
      "upstreams": [
        {
          "endpoint": "wss://${AZURE_FOUNDRY_PROJECT_NAME}.cognitiveservices.azure.com/openai/realtime",
          "key": "${AZURE_FOUNDRY_API_KEY}"
        }
      ]
    },
    "openrouter": {
      "paths": ["/v1/chat/completions"],
      "rewritePath": true,
      "methods": ["POST"],
      "upstreams": [
        {
          "endpoint": "https://openrouter.ai/api/v1/chat/completions",
          "key": "${OPENROUTER_API_KEY}",
          "authType": "BEARER"
        }
      ]
    }
  }
}

Call an application route​

Core exposes an application's routes at:

<METHOD> /v1/deployments/<application>/route/<route_path>
  • <METHOD> is one of the route's methods.
  • <application> is the application's deployment ID.
  • <route_path> is matched against the route's paths. It must not contain the word route, so Core can split the deployment ID from the route path.

Further reading​