API Reference
Integrations
Guardrails, caching and telemetry: integration types, integrations, and attaching them to routers.
An integration is a configured guardrail, cache or telemetry service that runs on the requests a router serves. Each integration has a type, such as pii_regex or bedrock_guardrails, a type-specific config, behavior settings, and, for services that need one, a credential. An integration runs only on the routers it is attached to. Reading needs integrations:read, and every write, including deletes and the router attachment endpoints, needs integrations:write.
Endpoints
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /v1/integration-types | List every integration type, with its availability, defaults and capabilities. | integrations:read |
| GET | /v1/integration-types/{slug} | Get one type. | integrations:read |
| GET | /v1/integrations | List the organization's integrations. | integrations:read |
| POST | /v1/integrations | Create an integration. Returns 201. Accepts an Idempotency-Key. | integrations:write |
| GET | /v1/integrations/{id} | Get one integration. | integrations:read |
| PATCH | /v1/integrations/{id} | Change name, enabled, config, settings or credential. Requires If-Match. | integrations:write |
| DELETE | /v1/integrations/{id} | Delete an integration. Requires If-Match. Returns 204. detach=true also removes it from every router. | integrations:write |
| POST | /v1/integrations/{id}/test | Check the integration's connection to its service. | integrations:write |
| GET | /v1/routers/{id}/integrations | List a router's attachments. | integrations:read |
| POST | /v1/routers/{id}/integrations | Attach an integration to a router, sent as integration_id and an optional settings_override. Returns 201. | integrations:write |
| PATCH | /v1/routers/{id}/integrations/{attachment_id} | Change an attachment's enabled or settings_override. Requires If-Match. | integrations:write |
| DELETE | /v1/routers/{id}/integrations/{attachment_id} | Detach an integration from the router. Requires If-Match. Returns 204. | integrations:write |
| PUT | /v1/routers/{id}/integrations/order | Set the order of the router's attachments. | integrations:write |
| GET | /v1/routers/{id}/integrations/explain | List the integrations that run on the router, in the order they run. | integrations:read |
Integration and attachment responses return the object itself, not wrapped in data, with an integer version. The ETag header carries the same version quoted, such as "3", and If-Match accepts "3" or 3. A PATCH or DELETE without If-Match returns 428 if_match_required, and a stale one returns 412 version_conflict with the current object in current. Lists return all items at once in types, integrations or attachments, without pagination. Integration ids start with int_, and attachment ids with inta_.
Types
GET /v1/integration-types lists the types below. Each type has a category: a guardrail checks requests and answers, and can block or change them; the cache answers repeated requests; telemetry records request activity and cannot change or block a request.
| Type | Name | Category | Credential | Available |
|---|---|---|---|---|
pii_regex | PII redaction | guardrail | None | Yes |
size_limit | Size limit | guardrail | None | Yes |
secrets_detection | Secrets detection | guardrail | None | Yes |
prompt_judge | Prompt judge | guardrail | router_id | Yes |
bedrock_guardrails | Bedrock Guardrails | guardrail | provider_key_id | Yes |
presidio | Presidio | guardrail | secret, optional | Yes |
azure_pii | Azure PII | guardrail | secret | Yes |
azure_content_safety | Azure Content Safety | guardrail | secret | Yes |
model_armor | Model Armor | guardrail | service_account | Yes |
lakera | Lakera Guard | guardrail | secret | Yes |
repello_argus | Repello Argus | guardrail | secret | Yes |
grayswan_cygnal | Gray Swan Cygnal | guardrail | secret | Yes |
cache | Cache | cache | None | Yes |
langfuse | Langfuse | telemetry | secret | Yes |
s3_export | S3 export | telemetry | None; the IAM role is in config.role_arn | Yes |
falcon_guardian | Falcon Guardian | guardrail | secret | No |
patronus | Patronus | guardrail | secret | No |
singulr | Singulr | guardrail | secret | No |
a10_guardrails | A10 Guardrails | guardrail | secret | No |
Creating an integration of a type that is not available returns 400 type_not_available. Each type in the list has these fields:
| Field | Type |
|---|---|
slug | string |
The type, sent as type on create. | |
display_name | string |
| The name shown in the dashboard. | |
category | string |
| guardrail, cache or telemetry. | |
built_in | boolean |
| Whether Multi-Router runs the check itself, without an outside service. | |
available | boolean |
| Whether integrations of this type can be created. | |
caps | object |
What the type supports: sides, content_kinds, actions, streaming, input_shape, spans, credential, endpoint, and for some types screening_scope. | |
sides | object or null |
Whether the type can check the request and the answer, as request and answer. Null for telemetry. | |
defaults | object |
| The settings a new integration of this type starts with. | |
credential_kind | string |
| none, bedrock_provider_key, secret_required, secret_optional, assume_role, api_key, azure_key, google_service_account or router. | |
max_piece_with_overlap | integer or null |
| The largest piece_chars plus overlap_chars the type accepts. 1000 for Bedrock Guardrails. | |
alongside_allowed_when | string |
block_only when check_timing can be alongside_dispatch for a configuration whose action is block, or never. | |
editable_settings | array |
The settings a router's settings_override can set. | |
Creating an integration
POST /v1/integrations takes name, type and config, and optionally settings and credential. The name has 1 to 120 characters without leading or trailing spaces, and is unique in the organization. Without settings, the integration takes the type's defaults. A new integration is enabled.
Integration fields
| Field | Type |
|---|---|
id | string |
The integration id, prefixed int_. | |
name | string |
| 1 to 120 characters, unique in the organization. | |
type | string |
| The type slug. Fixed. | |
category | string |
| guardrail, cache or telemetry. | |
type_display_name | string |
| The type's name. | |
built_in | boolean |
| Whether the type runs inside Multi-Router. | |
enabled | boolean |
| Whether the integration runs. A disabled integration is skipped on every router. | |
status | string |
| active, paused after repeated failures, or disabled. | |
settings | object |
| Behavior settings. See Settings below. | |
config | object |
| The type-specific configuration. | |
credential | object |
The credential, without its secret: kind none, provider_key (provider_key_id, provider_key_name), secret (hint), router (router_id) or assume_role (role_arn, external_id). | |
runs_on | array |
The routers it is attached to: attachment_id, router_id, router_name, position, chain_length, enabled, and custom_settings, the settings the router overrides. | |
delivery | object |
Telemetry only: last_delivery_at, last_delivery_result and failure_count. | |
version | integer |
| The version, for If-Match. | |
created_at | string |
| When the integration was created. | |
updated_at | string |
| When the integration last changed. | |
Credentials
credential is an object with exactly one field, and is never returned. Secrets are stored encrypted, and reads show only a hint with the last four characters of a secret of 16 characters or more.
| Field | Types | Value |
|---|---|---|
secret | presidio, langfuse, azure_pii, azure_content_safety, lakera, repello_argus, grayswan_cygnal | The service's API key or token, up to 16 KB. For Langfuse, the secret key; the public key goes in config. |
provider_key_id | bedrock_guardrails | An enabled AWS Bedrock provider key in the organization, prefixed llpk_. |
router_id | prompt_judge | An enabled static router in the organization, with its model set on the router and no bound prompt. The judge sends its checks through this router. |
service_account | model_armor | A Google service account key, as the JSON object of the key file, with type service_account, client_email and private_key. Up to 64 KB. |
S3 export takes no credential: Multi-Router assumes the IAM role in config.role_arn, and the response shows the role and the external_id Multi-Router generated, for the role's trust policy. Changing role_arn generates a new external id. On PATCH, a missing credential keeps the current one, an object replaces it, and null clears it, which only Presidio allows.
Settings
settings is sent whole, on create and on PATCH. Optional fields left out take the default in the table, and responses omit sides both, content_kinds of text, thinking, tool_arguments and tool_results, unchecked_media allow, log_redaction match_live, streaming.mode auto and streaming.replay_interval_ms 0. Unknown fields and values return 400.
| Field | Values |
|---|---|
enforcement | block, detect_only, logs_only |
| block checks live traffic and can block or change it. detect_only checks after the response and never affects live traffic; logs_only checks after the response and affects only the stored copy, and needs sides request. detect_only and logs_only are for guardrails only, and their matches are recorded as would_block in Traffic. | |
check_timing | before_dispatch, alongside_dispatch |
| before_dispatch finishes the request check before calling the provider. alongside_dispatch calls the provider while the check runs, and returns nothing until the check passes; it needs enforcement block and a type that allows it, such as Bedrock Guardrails with action block. | |
on_failure | block, continue |
| What happens when the integration fails or times out. Guardrails can change it; other types keep continue. | |
attempt_scope | request, attempt |
| request checks once and reuses the result on fallback attempts; attempt checks every provider attempt. | |
streaming | object |
How streamed answers are checked: first_piece_chars, piece_chars, overlap_chars and max_hold_ms, all integers, and optionally mode (auto or whole_answer) and replay_interval_ms. whole_answer holds the whole answer and checks it once, for guardrails that check the answer. replay_interval_ms paces the release of a held answer, and needs whole_answer. | |
payload | decision_context, full_content |
| What the integration receives: request details without message content, or the content as well. | |
timeout_ms | integer |
| At least 1. Prompt judge allows up to 15000. | |
sides | request, answer, both |
| Optional, default both. The sides a guardrail checks, within the sides its type supports. | |
content_kinds | array |
| Optional. text, thinking, tool_definitions, tool_arguments, tool_results, images and documents, within the type's caps.content_kinds. At least one. Default text, thinking, tool_arguments and tool_results. Guardrails only. | |
unchecked_media | allow, block |
| Optional, default allow. Whether a request with images or files the guardrail cannot check is allowed or blocked. Guardrails only. | |
log_redaction | match_live, reversible |
Optional, default match_live. reversible keeps the originals of redacted values, encrypted, with the stored payload, for a key with traffic:reveal; see Traffic. Only pii_regex with sides request or both. | |
The type's defaults set every field. Built-in guardrails start with a 50 ms timeout and per-chunk streaming; Bedrock Guardrails, Presidio and the outside guardrails start with 1500 ms and pieces of 900 characters after a first piece of 200, with 100 characters of overlap and a hold of up to 1000 ms; Lakera and Gray Swan Cygnal also check tool_definitions by default; prompt judge starts with 5000 ms and sides request; Langfuse and S3 export start with 5000 ms, payload decision_context and on_failure continue.
Config by type
Each type takes its own config. Unknown fields return 400.
pii_regex
| Field | Required | Values |
|---|---|---|
patterns | Yes | 1 to 64 rules. Each rule sets exactly one of builtin or regex. |
patterns[].builtin | One of builtin or regex | email, phone, credit_card, us_ssn, ip_address, aws_access_key. |
patterns[].regex | One of builtin or regex | Up to 512 characters. It must not match empty text, and its matches are at most 256 bytes. |
patterns[].name | With regex | The label used in placeholders, such as [EMPLOYEE_ID_1]. |
patterns[].action | Yes | mask replaces each whitespace-separated word the match touches with a numbered placeholder and restores it in the answer; block blocks the request. |
size_limit
| Field | Required | Values |
|---|---|---|
max_input_chars | At least one limit | Characters of message text and tool-call arguments, excluding system text and tool definitions. |
max_messages | At least one limit | Messages, excluding system messages. |
max_tools | At least one limit | Tools. |
Size limit checks the request only.
secrets_detection
| Field | Required | Values |
|---|---|---|
action | No | block or mask. Default block. mask replaces each whitespace-separated word a secret touches with [REDACTED_SECRET]; it is not restored. |
ignored_keywords | No | Up to 100 strings of 1 to 128 characters. |
ignored_rules | No | Up to 100 ids of detection rules to skip. |
max_bytes | No | The scan window, from 1 to 1048576 bytes. Default 1048576. |
prompt_judge
| Field | Required | Values |
|---|---|---|
policy | Yes | The policy the judge model checks against, 1 to 16384 bytes. |
Checking the answer with prompt judge needs streaming.mode whole_answer.
bedrock_guardrails
| Field | Required | Values |
|---|---|---|
guardrail_id | Yes | The AWS guardrail id. |
guardrail_version | Yes | The guardrail version. |
region | No | The AWS region. Defaults to the provider key's region. |
action | No | block, mask or redact. Default redact. block: anything the guardrail would anonymize blocks; mask: each value the guardrail reports becomes a numbered placeholder, restored in the answer; redact: the guardrail's own anonymized text is used, not restored. block allows alongside_dispatch. |
presidio
| Field | Required | Values |
|---|---|---|
analyzer_url | Yes | The https URL of your Presidio analyzer. |
score_threshold | Yes | From 0 to 1. |
action | Yes | block or mask. |
entities | No | Presidio entity names to detect. |
azure_pii
| Field | Required | Values |
|---|---|---|
region | No | east_us or west_europe. Default east_us. |
endpoint | No | Your resource, as https://<resource>.cognitiveservices.azure.com, with no path or port. Replaces region. |
action | No | block or mask. Default block. |
language | No | Default en. |
categories | No | Azure PII category names. Empty checks every category. |
min_score | No | From 0 to 1. Default 0.5. |
azure_content_safety
| Field | Required | Values |
|---|---|---|
endpoint | Yes | Your resource root, on cognitiveservices.azure.com, services.ai.azure.com or api.cognitive.microsoft.com, with no path. |
harm_threshold | No | From 1 to 7, for all four harm categories. Default 4. |
analyze_text | No | Default true. |
shield_prompt | No | Default true. |
detect_protected_material | No | Default true. |
analyze_images | No | Default true. |
At least one of the four checks is on.
model_armor
| Field | Required | Values |
|---|---|---|
project_id | Yes | The Google Cloud project, 1 to 63 letters, digits, hyphens or underscores. |
template_id | Yes | The Model Armor template, 1 to 128 letters, digits, hyphens or underscores. |
region | No | us_central1, us_east1, us_east4, us_west1, northamerica_northeast2, europe_west1, europe_west2, europe_west3, europe_west4, europe_west9, europe_southwest1, asia_northeast1, asia_northeast3, asia_south1, asia_southeast1, australia_southeast2, eu or us. Default us_central1. |
action | No | block, mask or redact. Default block. mask needs an inspect-only template: each reported finding becomes a numbered placeholder, restored in the answer. redact needs a de-identify template: its rewritten text is used, not restored. |
lakera
| Field | Required | Values |
|---|---|---|
region | No | us, eu or ap_southeast_1. Default us. |
action | No | block or mask. Default block. |
project_id | No | The Lakera project, up to 128 characters. |
repello_argus
| Field | Required | Values |
|---|---|---|
asset_id | Yes | The Argus asset, 1 to 128 letters, digits, hyphens or underscores. |
grayswan_cygnal
| Field | Required | Values |
|---|---|---|
endpoint | Yes | https://api.grayswan.ai, with no trailing slash. |
policy_id | Yes | The Cygnal policy, up to 128 characters. |
threshold | No | Greater than 0, up to 1. Default 0.5. |
cache
| Field | Required | Values |
|---|---|---|
ttl_seconds | Yes | From 1 to 86400. |
The cache always runs closest to the provider, whatever its position on the router.
langfuse
| Field | Required | Values |
|---|---|---|
host | Yes | The https URL of your Langfuse host, such as https://cloud.langfuse.com. |
public_key | Yes | The Langfuse public key. |
s3_export
| Field | Required | Values |
|---|---|---|
bucket | Yes | The S3 bucket. |
region | Yes | The bucket's AWS region. |
role_arn | Yes | The IAM role to assume, as arn:aws:iam::<12 digits>:role/<name>. |
prefix | No | A key prefix. Default empty. |
Customer URLs, the Presidio analyzer_url and the Langfuse host, must be https with a public host name; others return 400 unsafe_url.
Changing and deleting
PATCH /v1/integrations/{id} changes the fields sent. config and settings replace the current value whole, and the result is checked again against every router the integration is attached to. enabled false stops the integration on every router.
A DELETE of an integration that is attached to a router returns 409 integration_attached. Send ?detach=true to remove it from every router and delete it in one call.
Testing a connection
POST /v1/integrations/{id}/test checks that Multi-Router can reach and authenticate with the integration's service, without sending request content, and returns ok and latency_ms. A failed check also returns error connection_failed and a generic message, never the service's response. A check takes at most 10 seconds. Bedrock Guardrails, Presidio, S3 export, Langfuse, Azure PII, Azure Content Safety, Model Armor and Lakera check their service; PII redaction, size limit and cache check their config; other types return ok false. An organization can run 10 tests a minute and 2 at once; more return 429 test_rate_limited with Retry-After.
Attaching to routers
An attachment runs an integration on one router. The router endpoints take the router's rt_ id: an alias returns 400 alias_not_attachable, because an alias runs its target router's integrations. A router holds up to 99 attachments, and an integration is attached to a router once. A new attachment is enabled and goes last.
| Field | Type |
|---|---|
id | string |
The attachment id, prefixed inta_. | |
integration_id | string |
| The attached integration. | |
name | string |
| The integration's name. | |
type | string |
| The integration's type. | |
category | string |
| guardrail, cache or telemetry. | |
status | string |
| active, paused, or disabled when the integration or the attachment is disabled. | |
position | integer |
| The zero-based place in the router's order. | |
enabled | boolean |
| Whether the integration runs on this router. | |
sides | object or null |
| The sides the type can check. Null for telemetry. | |
forced_innermost | boolean |
| true for the cache, which runs closest to the provider whatever its position. | |
settings_override | object or null |
| The settings this router overrides, or null to use the integration's settings. | |
effective_settings | object |
| The integration's settings with the override applied. | |
version | integer |
| The version, for If-Match. | |
settings_override sets any of check_timing, attempt_scope, streaming, payload, sides, content_kinds and timeout_ms, with the values in Settings above. sides and content_kinds can only narrow the integration's own. enforcement and on_failure are set on the integration only, and return 400 setting_not_editable. On PATCH, a missing settings_override keeps the current one and null removes it.
Order
Request checks run in position order, and answer checks run in reverse. PUT .../order takes attachment_ids, listing every attachment on the router once, and returns attachments in the new order. A list that leaves one out or adds another returns 409 reorder_incomplete. Position cannot be changed by PATCH.
Explain
GET .../explain lists the integrations that run on a request to the router, in the order they run. It follows an alias to its target, and includes the members of a fallback or weighted router. Each step has integration_id, name, category and action.
Labels
A label is a short note a guardrail run carries about how the check ran, such as older turns being left out to fit the vendor's size limit. Labels never hold request or answer text. They are sent only to telemetry integrations: in the export record as integration_runs[].labels, in S3 export as runs[].labels (format v0) or integration_runs[].labels (format v1), and over OpenTelemetry as the span attribute multi_router.integration_run.labels.<name>. A run carries only the labels that apply.
The list is fixed and grows only with a release; a label's name and type never change. A bool label is always true when present. An integer label is a count. labels_dropped stays in the export for compatibility; with a fixed list no label is dropped.
| Label | Type | Set by | Meaning |
|---|---|---|---|
context_truncated | bool | Lakera, Gray Swan Cygnal | Older conversation turns were left out so the check fit the vendor's request size limit. The latest turn is always sent. |
tool_definition_as_text | bool | Lakera, Gray Swan Cygnal | Tool definitions were sent to the vendor as plain text because they could not be sent in its structured tool format. |
tool_result_as_text | bool | Lakera | A tool result was sent as plain text because it had no usable tool call id. |
tool_call_as_text | bool | Lakera | A tool call was sent as plain text because its id, name or arguments were missing or not valid JSON. |
tool_definitions_skipped_for_redact | bool | PII redaction | A redact rule matched inside a tool definition. Tool definitions are never changed, so the match was left as is. |
argus_flagged | bool | Repello Argus | Repello flagged the content, but not with a verdict set to block, so the request went on. |
secrets_redacted | bool | Secrets detection | One or more secrets were masked. |
pii_redacted | bool | PII redaction | One or more PII matches were masked. |
unexpected_mask | bool | Bedrock Guardrails, any guardrail | A check that may only inspect content tried to change it, or tried to mask an image, so the run was blocked. |
image_unchecked | bool | Bedrock Guardrails | Selected images could not be checked. |
image_check_failed | bool | Bedrock Guardrails | The image check failed and the guardrail is set to continue on failure. The text check still applied. |
cache_hit | bool | Cache | The answer came from the cache. |
memo_checked_reuse | bool | Any guardrail | On a retry, the result of an earlier check of the same content was reused instead of calling the vendor again. |
post_response_dropped_overload | bool | Any detect_only or logs_only guardrail | The check after the response was skipped because the server was running as many of these checks as it allows. |
post_response_dropped_budget | bool | Any detect_only or logs_only guardrail | The check after the response was skipped because the time allowed for these checks ran out. |
post_response_cancelled_shutdown | bool | Any detect_only or logs_only guardrail | The check after the response was stopped because the server was shutting down. |
answer_check_skipped_stream | bool | Any detect_only or logs_only guardrail | The answer was not checked because the request was streamed and the full answer text was not captured. Streamed answers are normally checked once they end. |
answer_check_skipped_cut_short | bool | Any detect_only or logs_only guardrail | The answer was not checked because it was cut short, was blocked, or was produced by Multi Router itself rather than the model (for example a cache hit). The name predates the last two cases and is kept for compatibility. |
answer_check_skipped_unreadable | bool | Any detect_only or logs_only guardrail | The answer was not checked because it could not be read. |
answer_check_skipped_request_failure | bool | Any detect_only or logs_only guardrail | The answer was not checked because the request to the model failed. |
tool_definitions_omitted | integer | Lakera, Gray Swan Cygnal, Azure Content Safety, Azure PII, Model Armor, Repello Argus | How many tool definitions were not sent to the vendor because the request had more than 128 of them, or more than 256 KiB. |
unchecked_images | integer | Every guardrail run on the request | How many images in the request no attached guardrail checked. |
unchecked_files | integer | Every guardrail run on the request | How many files in the request no attached guardrail checked. |
Errors
Config and settings errors return 400 with the field at fault and a code such as invalid_config, unknown_field, required, invalid_value, out_of_range, https_required, invalid_regex or setting_not_editable. Other errors:
| Code | Status | Meaning |
|---|---|---|
invalid_integration | 400 | An unknown type, or a credential that does not fit the type. |
invalid_input | 400 | The body has an unknown field or a field of the wrong type. |
type_not_available | 400 | The type is not available. |
credential_required | 400 | A PATCH clears a credential the type requires. |
invalid_router | 400 | The prompt judge router is not an enabled static router with its model set and no bound prompt. |
provider_key_not_found | 400 | The provider key is absent from the organization. |
provider_key_not_supported | 400 | The provider key is disabled or not an AWS Bedrock key, or the type takes no provider key. |
unsafe_url | 400 | A customer URL is not allowed. |
alias_not_attachable | 400 | The router id is an alias. Use the rt_ id of its target. |
not_found | 404 | No integration, type, attachment or router has that id in the organization. |
duplicate_name | 409 | Another integration has the name. |
integration_attached | 409 | A DELETE names an attached integration. Detach it, or send detach=true. |
already_attached | 409 | The integration is already attached to the router. |
too_many_attachments | 409 | The router has 99 attachments. |
reorder_incomplete | 409 | The order does not list every attachment on the router exactly once. |
written_by_newer_version | 409 | The integration was saved with settings this server cannot change. Retry later. |
version_conflict | 412 | The If-Match version is stale. current holds the current object. |
if_match_required | 428 | A PATCH or DELETE has no If-Match. |
test_rate_limited | 429 | Too many connection tests. Retry after Retry-After seconds. |
integration_unavailable | 503 | Integrations are unavailable. Retry. |