Azure API Management Fragment Packages

Fragment packages define which APIM policy fragments are deployed and where they are inserted into an API policy. Each package includes:

package.json, which lists the package name, version, inbound fragments, and outbound fragments.
XML policy fragments that APIM executes during inbound or outbound processing.

v2 Request Evaluations

Package: v2-request-evals Inbound fragments:

hl-oauth-token-management
hl-v2-request-evaluations

Outbound fragments:

hl-v2-surface-runtime-action

This package calls POST /detection/v2/request-evaluations before APIM forwards the request to the backend. HiddenLayer returns the original request, a redacted request, or a provider-shaped block response. When HiddenLayer returns hl-runtime-action: BLOCK, APIM returns the block response without calling the backend.

v2 Response Evaluations

Package: v2-response-evals Inbound fragments:

hl-oauth-token-management
hl-v2-response-evals-inbound

Outbound fragments:

hl-v2-response-evaluations

This package captures request context in inbound processing and calls POST /detection/v2/response-evaluations in outbound processing. HiddenLayer returns the original response, a redacted response, or a provider-shaped block response. The response package skips response evaluation for:

model discovery requests such as GET /v1/models
streaming requests
empty responses
non-JSON responses

v1 Interactions

Package: v1-interactions Inbound fragments:

hl-oauth-token-management
hl-interactions-input

Outbound fragments:

hl-interactions-output

This legacy package constructs a structured HiddenLayer interactions payload and calls POST /detection/v1/interactions for input and output evaluation.

Provider Compatibility

Provider support is determined by the package, not by APIM:

Package	Provider handling	Supported providers
`v2-request-evals`	Forwards the original request body to HiddenLayer’s `/detection/v2/request-evaluations` endpoint. The fragment does not parse provider-specific request fields. HiddenLayer parses the payload and returns either the original body, a redacted body, or a provider-shaped block response.	Whatever HiddenLayer’s `/detection/v2/request-evaluations` endpoint accepts. Use `HL-Provider-Id` to override auto-detection when needed.
`v2-response-evals`	Forwards the original response body to HiddenLayer’s `/detection/v2/response-evaluations` endpoint. The fragment does not parse provider-specific response fields. HiddenLayer parses the payload and returns either the original body, a redacted body, or a provider-shaped block response.	Same as `v2-request-evals`. Response evaluation is skipped for streaming responses, non-JSON responses, empty responses, and `GET /v1/models` discovery calls.
`v1-interactions`	The APIM fragment itself parses the request and response bodies. It reads OpenAI `model` and `messages` from the request and OpenAI `choices[].message` from the response. The block response is an OpenAI chat-completion payload.	OpenAI / Azure OpenAI chat-completions. Other provider shapes are not transformed and will not produce a useful interaction record.

Choosing a package for non-OpenAI providersPick v2-request-evals and/or v2-response-evals. The APIM fragments stay provider-agnostic; provider support is governed by HiddenLayer’s v2 evaluation APIs. If a new provider is added to HiddenLayer Runtime, no APIM fragment change is required — set HL-Provider-Id on the request if HiddenLayer cannot infer the provider from the payload alone.

Header Behavior

The v2 packages forward these headers to HiddenLayer when available:

Header	Description
`HL-Roundtrip-Id`	Links request and response evaluations for one LLM call. APIM generates one when absent.
`HL-Runtime-Session-Id`	Groups interactions across multiple application requests.
`HL-Requester-Id`	Identifies the requester or end user.
`HL-Provider-Id`	Overrides provider auto-detection.
`HL-Runtime-Edge-Provider`	Identifies APIM as the edge integration. Defaults to `azure-apim`.
`HL-Runtime-Edge-Provider-Version`	Identifies the APIM fragment integration version.
`HL-Runtime-Edge-Provider-Metadata`	Adds APIM context such as API name, API version, service name, region, revision, subscription name, and operation ID.

HiddenLayer metadata headers are removed before APIM forwards the request to the backend.

​v2 Request Evaluations

​v2 Response Evaluations

​v1 Interactions

​Provider Compatibility

​Header Behavior

v2 Request Evaluations

v2 Response Evaluations

v1 Interactions

Provider Compatibility

Header Behavior