Skip to main content

Interceptors

An interceptor is a service that DIAL Core calls on the way to a model or application and on the way back, so it can inspect, change, or block requests and responses. Use interceptors for PII redaction, guardrails, safety checks, and audit logging. This reference covers registering interceptors in Core and attaching them to deployments; it is for platform engineers who know how DIAL Core is configured.

To build an interceptor, see Interceptors. For what interceptors can and cannot enforce, see Guardrails.

Where interceptors are defined​

SourceLocation
Config fileinterceptors.<name>
Configuration API/v1/interceptors/platform/<name>

An interceptor must be registered before any deployment can use it. Its name is a deployment ID, shared with models, applications, and toolsets; keep it URL-safe and lowercase with hyphens, for example pii-redaction. DIAL Admin manages interceptors in Interceptors.

Fields​

FieldDescription
endpointThe URL of the interceptor service, used as is. Required unless interfaces is used.
baseUrlThe root URL for every interfaces entry that declares no base_url.
interfacesA typed alternative to endpoint. Only openaiChatCompletions is supported. See Interfaces.
displayNameThe name shown in DIAL clients, tables, and logs.
descriptionWhat the interceptor does and the parameters it uses.
iconUrlThe URL of the icon shown for the interceptor.
authorThe interceptor's developer.
createdAt, updatedAtThe dates the interceptor was created and last updated.
overrideNameRewrites the Chat Completions body's model field, and the X-DIAL-OVERRIDE-NAME header, to this value. Applied only when the interceptor runs for a Chat Completions request; the Responses API flow ignores it. It does not change routing.
forwardAuthTokenForwards the caller's Authorization header to the interceptor, for an interceptor service that needs its own authentication.
featuresFeatures of the interceptor, for example configurationEndpoint.
configurationEndpointThe URL that exposes the interceptor's configuration.
defaultsBody parameters Core adds to a Chat Completions request that does not carry them, on the hop to this interceptor.
defaultHeadersHeaders Core adds on the hop to this interceptor. See Default headers.

Interfaces​

An interfaces.openaiChatCompletions entry is served by a base URL. Core sends the request to the base URL plus the request path, with the {deployment-id} segment rewritten to the interceptor's name: /openai/deployments/<model>/chat/completions goes to <base_url>/openai/deployments/<interceptor-name>/chat/completions. When interfaces and endpoint are both set, interfaces wins.

Other interface types, including openaiResponses, are not supported and are dropped with a warning when Core reads the configuration.

FieldDescription
base_urlThe root URL the request path is appended to. Optional when the interceptor has a baseUrl.
defaultHeadersHeaders for this interface, laid over the interceptor-level defaultHeaders.
defaultsBody parameters for this interface. They replace the interceptor-level defaults; the two are not merged.
overridePathsReplaces the path for the hop to this interceptor, as for models. The applicable key is postAzureOpenaiChatCompletions, and {id} is the interceptor's name.

Default headers​

Core adds defaultHeaders on the hop that calls the interceptor, to a request without a header of that name. A header the client sends, or one Core sets itself, wins. A header Core strips on the way to the interceptor is stripped from the defaults too: hop-by-hop headers, Api-Key and x-api-key, and traceparent and tracestate.

The defaultHeaders of the model or application the interceptor fronts are applied at the first interceptor of the chain and travel down it. Where both declare the same name, the interceptor's value wins.

Categories​

A registered interceptor runs where you attach it:

CategoryApplies toWhere you attach it
GlobalEvery deployment in DIALglobalInterceptors in Global settings
Application typeEvery application of one application typedial:applicationTypeInterceptors in the application type schema
LocalOne model or applicationinterceptors on the model or application

Local interceptors on an application can be set by a DIAL administrator when the application is published or changed, or by its author through the API.

Execution order​

When all three categories apply, Core runs them in this order:

  • Request: global, then application type, then local.
  • Response: local, then application type, then global.

Global interceptors see the original input first and the final response last, so they suit the strictest rules.

Example​

{
  "interceptors": {
    "pii-redaction": {
      "endpoint": "http://pii-interceptor:4088/api/v1/interceptor/handle",
      "displayName": "PII redaction",
      "features": { "configurationEndpoint": "http://pii-interceptor:4088/configuration" },
      "defaults": {
        "custom_fields": { "interceptor_configuration": { "<OPTION>": "<VALUE>" } }
      }
    },
    "audit-logger": {
      "interfaces": {
        "openaiChatCompletions": { "base_url": "http://audit-interceptor:4089" }
      }
    }
  },
  "globalInterceptors": ["audit-logger"],
  "applications": {
    "forecast": {
      "endpoint": "http://forecast-app:5000/openai/deployments/forecast/chat/completions",
      "interceptors": ["pii-redaction"]
    }
  }
}

For more examples, see the DIAL Interceptors SDK.

Further reading​