Building on Iris
This page is for developers who want Iris-style answers outside the chat panel. Two common scenarios:
- Pre-flight data lookups during integration debugging (“show me the pending access requests for Salesforce, to verify my integration is creating them correctly”)
- Ad-hoc reports for stakeholders (a PM asks “what’s our agent count by risk band?”)
The short answer: use Iris in the app for ad-hoc questions, and the /api/v1 API for anything programmatic.
The chat endpoint is not a public API
The Iris panel talks to POST /api/chat. That endpoint:
- authenticates with the signed-in browser session only — it does not accept API keys or bearer tokens;
- takes
{ "message": "...", "history": [...], "stream": true }and returns either a server-sent-event stream or, withoutstream, a JSON body{ message, tools_used, provenance? }; - is not part of the published
/api/v1contract, so its request and response shapes can change between releases without notice.
There is no supported way today to call Iris from a script, a server or another product, and no endpoint for calling a catalog tool directly.
Getting the same data programmatically
Most questions Iris answers map onto a published, versioned /api/v1 endpoint authenticated with an API key — for example users, identities, access requests, entitlements, applications, agents, SoD violations, audit events, JML events and webhooks. Those endpoints paginate ({ data, total, page, limit, total_pages }, default 25, max 100), follow the standard error shape and are covered by the OpenAPI spec.
If you are building a dashboard, call those endpoints from your server-side code rather than proxying natural-language questions — you get deterministic results, stable shapes and no model in the loop.
The iris_sql view query
Inside the app, Iris’s most flexible tool is iris_sql, offered to identity_admin, security_analyst, compliance_officer, ciso and super_admin. It is useful to understand even though you can’t call it directly:
- It does not accept SQL text. Iris describes the query as a structure — one view, columns, filters, grouping, aggregates, ordering and a limit of up to 200 rows.
- The server checks every column against the view’s real columns and builds the parameterised query itself. Joins across views, unions and subqueries are not possible.
- The query runs on a separate read-only database login that can see only the curated views, inside a read-only transaction with a 5-second limit, with the tenant taken from the user’s session.
- Results are checked for rows from another tenant before they are returned.
Each query is audited as IRIS_SQL_EXECUTED, IRIS_SQL_REJECTED, IRIS_SQL_EXEC_ERROR or IRIS_SQL_TENANT_LEAK, with the exact query text. The answer shows the query under Query run.
What it can read: curated, read-only views of user access (grants, applications reached and last login per person), application entitlements, separation-of-duties violations with their context, certification campaign progress, recent audit volume, NHI credential rotation health, workflow status, compliance posture, an IAM summary and entitlement dormancy.
Raw tables are not reachable through Iris.
Limits
| Limit | Value |
|---|---|
| Chat requests | 60 per minute per IP |
| Iris questions per person | 120 per hour and 1,000 per day (defaults; set per deployment) |
| Iris questions per organisation | 5,000 per day (default; set per deployment) |
| Sensitive actions (API keys, break-glass) | 5 confirmations per minute per action |
| One Iris turn | 60 seconds |
iris_sql |
5-second query limit, at most 200 rows |
When a usage limit is reached, /api/chat returns HTTP 429 with code: "IRIS_BUDGET_EXCEEDED" and a Retry-After header. A message flagged as a prompt-injection attempt is refused with HTTP 400 and recorded in the audit log as PROMPT_INJECTION_BLOCKED.
Models behind Iris
Iris’s chat answers use an Anthropic Claude Haiku-class model. Routing by meaning uses Voyage AI embeddings (voyage-3-lite). “How do I…” questions answered from this documentation use a Claude Sonnet model. Model choices change over time. The model sees the results of the tools it calls in order to write the answer.
Adjacent reading
- Getting started with Iris — first-5-minutes walkthrough
- Iris tool catalog — what tools exist and who is offered them
- Iris failure modes — how to handle the edge-case responses
- API Reference — the published endpoints for programmatic access
© AtmanID · Privacy