AI Assistant Endpoints

The AI Assistant API provides endpoints for interacting with the AI-powered chat interface to query identity data and get intelligent insights.

Base URL

All endpoints are relative to /api/v1/ai.

---

Chat

Send a message to the AI assistant and receive a response.

POST /api/v1/ai/chat

Request Body

{
  "message": "Show me all privileged accounts that haven't been used in 90 days",
  "history": [
    {
      "role": "user",
      "content": "Previous message"
    },
    {
      "role": "assistant",
      "content": "Previous response"
    }
  ],
  "stream": true
}

Request Parameters

Parameter	Type	Description
message	string	The user's question or query
history	array	Previous conversation messages for context
stream	boolean	Enable streaming responses (recommended: true)

Response (Non-Streaming)

{
  "response": "I found 15 privileged accounts that haven't been used...",
  "tools_used": ["query_accounts"],
  "status": "complete"
}

Response (Streaming)

When stream: true, the response is delivered as Server-Sent Events (SSE):

event: content
data: {"text": "I found "}

event: content
data: {"text": "15 privileged accounts..."}

event: tool_results
data: {"tools": ["query_accounts"], "count": 15}

event: status
data: {"status": "complete"}

event: [DONE]
data: {}

SSE Event Types

Event	Description
content	Text content being streamed
tool_results	Tools used and their results
status	Progress updates
warning	Warnings (e.g., data limits reached)
[DONE]	Completion signal

---

Query Capabilities

The AI assistant can query the following data types when the corresponding features are enabled:

Identity Data (identity_data feature)

Tool	Description
query_accounts	Search and filter accounts
query_groups	Search and filter groups
query_owners	Search and filter owners
query_applications	Search and filter applications

Configuration (configuration feature)

Tool	Description
query_campaign_rules	Search campaign rules
query_policies	Search policies
query_roles	Search roles

Campaigns (campaigns feature)

Tool	Description
list_campaigns	List active campaigns
query_approvals	Query approval status
query_compliance	Query compliance metrics

---

Example Queries

Security Questions

{
  "message": "Find accounts with high threat levels and no MFA",
  "stream": true
}

Access Control

{
  "message": "Which users have access to critical applications?",
  "stream": true
}

Compliance

{
  "message": "Show me accounts with policy violations",
  "stream": true
}

Analytics

{
  "message": "What department has the most inactive accounts?",
  "stream": true
}

---

Conversation Context

The AI maintains conversation context through the history parameter:

{
  "message": "Which of these are in the Finance department?",
  "history": [
    {
      "role": "user",
      "content": "Show me privileged accounts"
    },
    {
      "role": "assistant",
      "content": "I found 50 privileged accounts..."
    }
  ],
  "stream": true
}

---

Access Control

AI features are controlled by:

1. Master Toggle - Global AI enable/disable
2. Feature Permissions - Granular control per feature group
3. User Role - Scoped access for Reviewers and Auditors

Administrators have full access when AI is enabled. Reviewers and Auditors access AI features within their configured scope.

---

Error Responses

Status Code	Description
400	Bad Request - Invalid message format
401	Unauthorized - Authentication required
403	Forbidden - AI features disabled or insufficient permissions
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error Response Format

{
  "error": {
    "code": "AI_DISABLED",
    "message": "AI features are not enabled for this tenant"
  }
}

---

Rate Limiting

AI requests are rate-limited to prevent abuse. If you receive a 429 response, wait before retrying.

---

Related Topics

• AI Search - User guide
• AI Assistant Settings - Configuration guide
• API Reference - Complete API index