Iris Control: LLM control plane

Overview

Iris Control is a control layer for the LLM calls your own applications make. Your apps send requests to one OpenAI-compatible endpoint, and Iris Control applies your policy to every call before and after the model runs:

Routing and failover. Each use case has a primary model and fallbacks. If a provider errors or times out, the next model answers.
Data scoping. Retrieval is limited to the product or tenant a call belongs to, so an answer only uses the data it is allowed to see.
Tool limits. Each workflow can call only the tools you allow.
Grounding checks. Answers are checked against approved sources before they are returned. Unsupported answers are flagged or replaced with your handoff message.
Call log and evals. Every prompt, answer, model, and policy decision is logged, and you can score models against your own questions.

Try it before you connect anything: the Iris Control live demo runs model failover, data scoping, and grounding checks on live models, with no signup.

How it works

Your application calls Iris Control with an OpenAI-compatible request. The model field names a use case (for example support-answers), not a specific model.
Iris Control looks up the use case’s policy and applies it: scoped retrieval, allowed tools, and the model chain.
The primary model answers. If its provider fails, Iris Control retries the call on the next model in the chain.
The answer runs through the grounding check, when the use case has it turned on.
Iris Control returns the answer in the standard OpenAI response format, with headers that show which model answered and what the policy did, and writes the call to the call log.

Quickstart

Step 1: Get an API key

API keys are provided by your Iris Control point of contact. Send them from your backend only, never from browser or mobile code.

Step 2: Add your model providers

In the Iris Control dashboard, open Providers and add the providers you use: OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, or a self-hosted model with an OpenAI-compatible endpoint. Provider keys are stored encrypted and are never returned by the API.

Step 3: Create a use case

In the dashboard, open Use cases and create one for each LLM feature you run, such as support-answers or invoice-agent. Set its model chain and, as needed, data scoping, tools, and grounding checks. The settings are described in Use case policies.

Step 4: Point your client at Iris Control

Change the base URL and API key in the OpenAI client your application already uses. Set model to the use case name.

from openai import OpenAI

client = OpenAI(
    base_url="https://api1.irisagent.com/v1/control",
    api_key=IRIS_API_KEY,
)

response = client.chat.completions.create(
    model="support-answers",
    messages=[{"role": "user", "content": "How do I export last month's invoices?"}],
    extra_headers={
        "X-Iris-Product": "billing",
        "X-Iris-Tenant": "acme-corp",
    },
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api1.irisagent.com/v1/control",
  apiKey: process.env.IRIS_API_KEY,
});

const response = await client.chat.completions.create(
  {
    model: "support-answers",
    messages: [{ role: "user", content: "How do I export last month's invoices?" }],
  },
  {
    headers: {
      "X-Iris-Product": "billing",
      "X-Iris-Tenant": "acme-corp",
    },
  }
);

console.log(response.choices[0].message.content);

curl https://api1.irisagent.com/v1/control/chat/completions \
  -H "Authorization: Bearer $IRIS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Iris-Product: billing" \
  -H "X-Iris-Tenant: acme-corp" \
  -d '{
    "model": "support-answers",
    "messages": [{"role": "user", "content": "How do I export last month'\''s invoices?"}]
  }'

Streaming (stream: true), tool calling, and structured outputs work the same way as with the OpenAI API.

Request headers

Tag each call so the policy can scope it and the call log can group it.

Header	Required	Description
`Authorization`	Yes	`Bearer` followed by your Iris Control API key.
`X-Iris-Product`	No	The product the call belongs to. Limits retrieval to knowledge tagged with this product.
`X-Iris-Tenant`	No	Your customer or tenant ID. Limits retrieval to that tenant’s knowledge and groups the call log by tenant.
`X-Iris-Workflow`	No	The workflow or agent making the call. Selects the tool allowlist for that workflow.
`X-Iris-Trace-Id`	No	Your own request or trace ID, stored with the call log entry so you can join it to your logs.

Response headers

Every response carries the outcome of the policy.

Header	Description
`X-Iris-Request-Id`	The call log ID for this request.
`X-Iris-Model`	The model that produced the answer.
`X-Iris-Attempts`	The number of models tried. `2` means the primary failed and the first fallback answered.
`X-Iris-Grounding`	`passed`, `flagged`, `blocked`, or `off`.
`X-Iris-Tools-Removed`	Tools removed from the request or response because the workflow is not allowed to call them.

Use case policies

Each use case has one policy. You can edit it in the dashboard, or export and import it as YAML.

use_case: support-answers
models:
  chain: [gpt-5.6-sol, grok-4.5, gemini-3.7-flash]
  attempt_timeout_seconds: 15
retrieval:
  enabled: true
  scope_by: [product, tenant]
  max_sources: 5
tools:
  workflows:
    billing-agent: [lookup_invoice, send_receipt]
    triage-agent: [lookup_account]
grounding:
  mode: block            # off, flag, or block
  check_links: true
  handoff_message: "Let me connect you with a teammate who can confirm this."
logging:
  store_prompts: true
  retention_days: 90

Models and failover

models.chain lists the models for the use case in order. Iris Control calls the first one. If the call fails with a provider error, a rate limit, or a timeout longer than attempt_timeout_seconds, it retries on the next model in the chain. Every attempt is recorded in the call log with its model, outcome, and latency, and X-Iris-Attempts shows how many models were tried. To change models, edit the chain. Your application code does not change, because it only names the use case.

Data scoping

When retrieval.enabled is on, Iris Control searches your connected knowledge before calling the model and adds the matching passages to the request. Knowledge comes from the data sources you connect, such as help centers, Confluence, websites, and uploaded content. retrieval.scope_by sets which request headers limit the search:

product: only knowledge tagged with the X-Iris-Product value is searched. Articles can belong to several products.
tenant: only knowledge tagged with the X-Iris-Tenant value is searched.

A call with a scope header that matches no knowledge gets no retrieved passages, so the model has nothing outside that scope to answer from. If you run your own retrieval, leave retrieval.enabled off and send the passages you retrieved with the request. Iris Control uses them for the grounding check:

response = client.chat.completions.create(
    model="support-answers",
    messages=messages,
    extra_body={
        "iris": {
            "sources": [
                {
                    "title": "Exporting invoices",
                    "url": "https://help.example.com/invoices/export",
                    "body": "Go to Billing, then Invoice history, and select Export.",
                }
            ]
        }
    },
)

Tool limits

tools.workflows maps each workflow to the tools it may call. For a request with an X-Iris-Workflow header:

Tools in the request that are not on the workflow’s list are removed before the model sees them.
A tool call in the model’s response to a tool that is not on the list is removed from the response.

Both cases are listed in X-Iris-Tools-Removed and recorded in the call log. A request without X-Iris-Workflow keeps the tools it sends.

Grounding checks

The grounding check runs after the model answers and before the response is returned. It runs two checks against the sources for the call, whether retrieved by Iris Control or sent in iris.sources:

Link check. Every link in the answer must point to one of the sources. Links that can’t be matched to a source are reported as unapproved.
Claim check. A judge model checks each claim in the answer against the source text and returns a verdict, a grounding score from 0 to 5, and any unsupported claims.

grounding.mode decides what happens when an answer fails either check:

Mode	Behavior
`off`	No check runs. `X-Iris-Grounding: off`.
`flag`	The answer is returned unchanged with `X-Iris-Grounding: flagged`, and the result is in the call log. Use this to review results before blocking.
`block`	The answer is replaced with `handoff_message` and `X-Iris-Grounding: blocked` is set, so your app can route the user to a person.

Grounding check API

To check answers produced outside Iris Control, call the grounding check directly.

curl https://api1.irisagent.com/v1/control/grounding-check \
  -H "Authorization: Bearer $IRIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How long does a refund for a duplicate charge take?",
    "answer": "Duplicate charges are refunded within 24 hours. See https://example.com/credit-policy.",
    "sources": [
      {
        "title": "Refunds for duplicate charges",
        "url": "https://help.example.com/refunds",
        "body": "Once we confirm the duplicate charge, we refund it to the original payment method within 5 business days."
      }
    ]
  }'

Response:

{
  "passed": false,
  "urlCheck": {
    "approved": [],
    "unapproved": ["https://example.com/credit-policy"]
  },
  "judge": {
    "model": "gemini-3.7-flash",
    "verdict": "defect",
    "failureType": "hallucination",
    "groundingScore": 1,
    "unsupportedClaims": ["Duplicate charges are refunded within 24 hours"],
    "explanation": "The source says refunds take up to 5 business days."
  }
}

Field	Description
`passed`	`true` when every link is approved and the judge’s verdict is `correct`.
`urlCheck.approved` / `urlCheck.unapproved`	Links in the answer that do and don’t match a source.
`judge.verdict`	`correct` or `defect`.
`judge.failureType`	For a defect: `hallucination`, `wrong_article`, `incomplete`, or `kb_gap`.
`judge.groundingScore`	0 to 5. Higher means better supported by the sources.
`judge.unsupportedClaims`	Claims in the answer the sources don’t support.

Send up to 5 sources per request.

Call log

Every call appears in the dashboard under Call log, with:

The use case, product, tenant, workflow, and your X-Iris-Trace-Id
Each model attempt, with its outcome and latency
The prompt, the retrieved or supplied sources, and the answer
Tools removed by policy
The grounding check result

Filter by use case, tenant, model, or grounding result, and export entries as CSV. Set how long prompts and answers are kept with logging.retention_days, or turn off logging.store_prompts to keep only metadata.

Evals on your own data

Compare models on your own questions before you change a use case’s model chain.

In the dashboard, open Evals and upload a CSV with question and, optionally, expected_answer columns, or select calls from the call log.
Pick the models to compare.
Iris Control runs every question through each model with the use case’s retrieval and grounding settings, and scores each answer for grounding and, when an expected answer is given, correctness.

The scorecard shows accuracy, grounded rate, latency, and cost per model, so you can pick the model chain on your own data rather than a public benchmark.

Errors

Iris Control returns errors in the OpenAI error format.

Status	Meaning
`400`	The request is malformed, or `model` doesn’t name a use case.
`401`	The API key is missing or invalid.
`404`	The use case doesn’t exist.
`429`	You’ve exceeded your rate limit. Retry after the `Retry-After` header.
`502`	Every model in the use case’s chain failed. The error body lists each attempt.

A blocked grounding check is not an error. It returns 200 with the handoff message and X-Iris-Grounding: blocked.

Questions? Contact us at contact@irisagent.com or book an Iris Control demo.

Getting started

Connecting Data Sources

Deploying IrisAgent

Configuring AI and Automation

User Guides

Security and Compliance

Account Management

Iris Control

Overview

How it works

Quickstart

Step 1: Get an API key

Step 2: Add your model providers

Step 3: Create a use case

Step 4: Point your client at Iris Control

Request headers

Response headers

Use case policies

Models and failover

Data scoping

Tool limits

Grounding checks

Grounding check API

Call log

Evals on your own data

Errors

​Overview

​How it works

​Quickstart

​Step 1: Get an API key

​Step 2: Add your model providers

​Step 3: Create a use case

​Step 4: Point your client at Iris Control

​Request headers

​Response headers

​Use case policies

​Models and failover

​Data scoping

​Tool limits

​Grounding checks

​Grounding check API

​Call log

​Evals on your own data

​Errors

Overview

How it works

Quickstart

Step 1: Get an API key

Step 2: Add your model providers

Step 3: Create a use case

Step 4: Point your client at Iris Control

Request headers

Response headers

Use case policies

Models and failover

Data scoping

Tool limits

Grounding checks

Grounding check API

Call log

Evals on your own data

Errors